feat(coordination): move the worklist API-side (server authority + TUI/app clients + push)

[TraderSamwise]

Summary

Moves the Coordination model fully to the per-project control service so the worklist is built once, server-side, and consumed by both front-ends — the terminal TUI now, the Expo app next. Completes the A+C direction (service = single authority; front-ends are thin clients) for the Coordination screen.

Previously the TUI recomputed the reconciled "needs-you" worklist locally on every render. Now the service owns it; the TUI is a service-first client with a local fallback, and updates arrive via push.

Phases

1. Server authority — pure buildCoordinationView(input) → { model, worklist } (shared by server + TUI fallback so they never diverge) + GET /coordination-worklist assembling it from desktop.getState() + notifications + thread entries.
2. TUI as client — getFromProjectService (shares postToProjectService's retry/recovery loop); applyCoordinationModel/applyCoordinationFilter shared by service + local paths; refresh decoupled from render (nav renders cache; screen entry, heartbeat, and mutations refresh from the service; local build is the offline fallback).
3. App client contract — getCoordinationWorklist + typed response in app/lib/api.ts so the non-TUI app can consume the same authority (client only, no UI yet).
4. Push liveness — the dashboard's in-process event-bus subscriber pushes an instant, coalesced refresh+rerender when a coordination-relevant alert fires on-screen; the 1s heartbeat remains the fallback.

Testing

• yarn typecheck, yarn lint, full yarn vitest (1489 passing), yarn build — all green.
• cd app && yarn typecheck + eslint lib/api.ts — clean.
• New coverage: buildCoordinationView parity, the /coordination-worklist route, TUI service-first + fallback, and scheduleCoordinationPush (off-screen no-op / refresh / coalesce).

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Coordination worklist now fetches live coordination data from the service endpoint (with participant support).
  • Adds a unified coordination view that keeps the displayed worklist and underlying model in sync.

• Improvements

  • Service refresh is triggered more reliably from the coordination screen, including background updates and alert-driven pushes.
  • Awake/reachable entries are sorted ahead of unreachable/missing ones.
  • Multiple rapid refresh requests are coalesced to avoid redundant reloads.

• Bug Fixes

  • Better handling of missing/invalid coordination state with safe defaults and clamping.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jun 19, 2026 11:52pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8798d15a-c0d8-4c89-bcfa-435520bf55d0

📥 Commits

Reviewing files that changed from the base of the PR and between 48f11ab and 6e563ce.

📒 Files selected for processing (5)

• src/multiplexer/coordination.ts
• src/multiplexer/notifications.ts
• src/multiplexer/runtime-state.ts
• src/multiplexer/session-launch.ts
• src/multiplexer/subscreens.ts

🚧 Files skipped from review as they are similar to previous changes (5)

• src/multiplexer/session-launch.ts
• src/multiplexer/subscreens.ts
• src/multiplexer/runtime-state.ts
• src/multiplexer/coordination.ts
• src/multiplexer/notifications.ts

---

📝 Walkthrough

Walkthrough

Adds a /coordination-worklist HTTP endpoint to the metadata server, a buildCoordinationView model helper that produces a CoordinationModel+CoordinationWorklist pair in one call, a getFromProjectService GET transport sharing retry/recovery logic with POST, and a refreshCoordinationFromService client path that prefers service authority and falls back locally, with push coalescing and render sequencing updated throughout the coordination screen.

Changes

Service-driven coordination worklist

Layer / File(s)	Summary
buildCoordinationView model helper and API types src/coordination-model.ts, app/lib/api.ts, src/coordination-model.test.ts	buildCoordinationView builds a CoordinationModel then derives a CoordinationWorklist from the same model instance, returning both. New CoordinationReachability, CoordinationBucket, CoordinationWorklistItem, CoordinationWorklistResponse types and getCoordinationWorklist added to the app API layer. Tests verify view output matches separately built model+worklist.
Metadata server /coordination-worklist endpoint src/metadata-server.ts, src/metadata-server.test.ts	New GET /coordination-worklist route reads desktop state, builds threads via buildCoordinationThreadEntries, builds view via buildCoordinationView, and returns { ok, serviceInfo, worklist, model, threads }. Test seeds a live and a ghost session and asserts awake-before-unreachable ordering.
Generic GET project-service transport src/multiplexer/dashboard-control.ts, src/multiplexer/dashboard-actions-methods.ts	Shared requestProjectService helper extracted from postToProjectService with full retry/recovery semantics. New exported getFromProjectService delegates to the same helper. Both getFromProjectService and refreshCoordinationFromService exposed as delegating methods on dashboardActionMethods.
applyCoordinationModel, applyCoordinationFilter, refreshCoordinationFromService src/multiplexer/notifications.ts, src/multiplexer/notifications.test.ts	applyCoordinationModel applies a reconciled coordination payload to host state in one place. applyCoordinationFilter derives coordinationWorklist from coordinationWorklistAll based on coordinationFilter. refreshNotificationEntries reworked to use buildCoordinationView. New refreshCoordinationFromService fetches /coordination-worklist, applies via applyCoordinationModel, and falls back to local build on error. Tests cover both service authority hydration and fallback paths.
Coordination screen render, push coalescing, and trigger wiring src/multiplexer/coordination.ts, src/multiplexer/coordination.test.ts, src/multiplexer/subscreens.ts, src/multiplexer/session-launch.ts, src/multiplexer/runtime-state.ts, src/multiplexer/index.ts	showCoordination renders immediately then async refreshes from service. renderCoordination only rebuilds when not yet loaded. New reloadCoordination prefers service with local fallback. scheduleCoordinationPush uses reloadCoordination with coalescing. Navigation via "coordination" action sets coordinationLoaded = false. Alert events trigger scheduleCoordinationPush. Tests cover no-op, single-refresh, and burst-coalescing scenarios.

Sequence Diagram(s)

sequenceDiagram
  rect rgba(70, 130, 180, 0.5)
    Note over Multiplexer,MetadataServer: Push-triggered coordination refresh
  end
  participant Multiplexer
  participant scheduleCoordinationPush
  participant reloadCoordination
  participant refreshCoordinationFromService
  participant MetadataServer
  participant applyCoordinationModel
  participant renderCoordination

  Multiplexer->>scheduleCoordinationPush: alert event (coalesced)
  scheduleCoordinationPush->>reloadCoordination: host
  reloadCoordination->>refreshCoordinationFromService: host (service preferred)
  refreshCoordinationFromService->>MetadataServer: GET /coordination-worklist?participant=user
  MetadataServer-->>refreshCoordinationFromService: { model, worklist, threads }
  refreshCoordinationFromService->>applyCoordinationModel: payload
  applyCoordinationModel-->>refreshCoordinationFromService: host state updated
  refreshCoordinationFromService-->>reloadCoordination: true
  reloadCoordination-->>scheduleCoordinationPush: done
  scheduleCoordinationPush->>renderCoordination: re-render
  scheduleCoordinationPush->>scheduleCoordinationPush: clear coordinationPushScheduled

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• TraderSamwise/aimux#157: Modifies the same showCoordination/renderCoordination/handleCoordinationKey paths in src/multiplexer/coordination.ts that this PR extends with service-driven refresh and push coalescing.
• TraderSamwise/aimux#171: Extends the coordination inbox redesign by building a shared buildCoordinationView/applyCoordinationModel path and adding service-backed /coordination-worklist refresh using the same reachability/actionable/stale row metadata concepts.
• TraderSamwise/aimux#173: Directly establishes buildCoordinationWorklist/worklist-driven navigation in src/coordination-model.ts and src/multiplexer/notifications.ts; this PR builds buildCoordinationView and refreshCoordinationFromService on top of that exact foundation.

Poem

🐇 Hoppity-hop through the worklist anew,
The service now answers with sessions in view!
A ghost session lurks but is marked unreachable,
While awake ones sort first — neatly teachable.
buildCoordinationView bundles model and list,
No divergent rebuilds — nothing gets missed! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.93% 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 clearly and specifically describes the main change: moving the coordination worklist API to be server-authoritative and consumed by both TUI and app clients, with push-driven updates.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/tui-service-reads

---

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

[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/multiplexer/runtime-state.ts`:
- Around line 166-167: The promise chain at line 166 with the void operator in
the heartbeat path is missing a rejection handler. The call to
host.refreshCoordinationFromService().then(() =>
host.renderCurrentDashboardView()) needs to have a .catch() handler appended to
it to gracefully handle any rejections from refreshCoordinationFromService,
preventing unhandled rejection errors from surfacing on the status-refresh
interval. Add the rejection handler right after the .then() call to ensure any
errors are properly caught and logged.

🪄 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: 93ed2378-f198-48d1-b629-07fb45724a56

📥 Commits

Reviewing files that changed from the base of the PR and between 2e5941e and 48f11ab.

📒 Files selected for processing (15)

• app/lib/api.ts
• src/coordination-model.test.ts
• src/coordination-model.ts
• src/metadata-server.test.ts
• src/metadata-server.ts
• src/multiplexer/coordination.test.ts
• src/multiplexer/coordination.ts
• src/multiplexer/dashboard-actions-methods.ts
• src/multiplexer/dashboard-control.ts
• src/multiplexer/index.ts
• src/multiplexer/notifications.test.ts
• src/multiplexer/notifications.ts
• src/multiplexer/runtime-state.ts
• src/multiplexer/session-launch.ts
• src/multiplexer/subscreens.ts