[bra1nDump]

What

The simplified v1 of the host sessions surface — the agent-agnostic session/thread/event model that mobile and web sync against. One squashed commit, rebased on main.

Read this first: plans/host-sessions-sync.md — the single design doc, structured as three review layers (1: principles + budgets, 2: state ownership + surface + recovery, 3: one realistic scenario with exact payloads), plus rollout and the E2E gym story.

Shape

• Budgets (hard): 9 tRPC procedures · 12 socket packet types · 2 opaque incarnation-tagged cursor kinds · 1 automatic recovery path + the existing "restart host" hammer.
• Snapshots ride tRPC (sessions.list/get carry the head cursor); the /sessions/sync socket carries only small frames; subscribe.after is required.
• Claimless client tool calls: cards render on every device, first resolve wins.
• Recovery = the cold path re-run per stream, guarded by a client circuit breaker (3 resets / 30 s → error).
• camelCase everywhere on the wire; inputs AND outputs schema-validated at the router.

Evidence

• 602 host-service src tests, 46 protocol/client tests, 11-test realistic-scenario suite (mid-stream disconnect, scrollback parity vs the full journal, session switching under load, host reboot with exactly one reset).
• Gym user story 10/10 with a real Opus instance on this exact surface (ACP_E2E=1 bun test test/integration/sessions-user-story.integration.test.ts).
• Known gap (pinned by a test, fixed by the durable store next): a host-reboot journal rebuild loses causationId attribution.

Also in here

Doc consolidation: the old protocol/rollout pair and the stale Mastra/ACP-era chat docs are deleted (−5.7k lines); direction recorded — ACP gets replaced by a direct SDK adapter behind this unchanged surface (deferred, prototype in claude-sdk-session-harness), Mastra chat stays frozen for existing desktop users and is never used by mobile.

Out of scope (deferred)

Direct SDK adapter / ACP removal, host control-plane extension (workspace lifecycle etc. — see the "Trajectory" section in the doc). Next up after this: durable history store, React bindings + mobile rewire, Maestro phone replay.

https://claude.ai/code/session_01N98A6Rs53rLfRb8Qf5pM3Y

---

---

Summary by cubic

Ships v1 of Host Sessions sync: a canonical session/thread/event model with tRPC snapshots and a lightweight WebSocket for live updates. Adds sessions.*, /sessions/sync, a shared protocol package, and a small client store; cleans up old Mastra/ACP docs.

• New Features

  • New @superset/host-service-sync package with zod-validated protocol, a shared projection reducer, and a framework-free zustand client (createSessionsSyncClient).
  • Host sessions.* tRPC (snapshots via list/get, idempotent receipts, camelCase wire) and /sessions/sync hub (hello/ack, subscribe.after from head, replay/reset with invalid/expired cursor handling).
  • Canonical runtime that translates ACP into canonical events and serves both tRPC and the hub; claimless client tool-call resolves; host and client fold the same reducer.
  • Documentation consolidated into plans/host-sessions-sync.md; removed stale Mastra/ACP-era docs.

• Migration

  • No breaking changes; legacy Mastra chat remains for existing users. This surface is gated.
  • To adopt: fetch sessions.list/sessions.get to seed, then open /sessions/sync and send subscribe.after using the returned head cursor; on reset, refetch the snapshot and resubscribe.
  • The reference client lives in @superset/host-service-sync (createSessionsSyncClient).

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

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f833baab-905c-4b4b-8d79-449914dc19de

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[ghost]

Ready to review this PR? Stage has broken it down into 11 individual chapters for you:

	Title
1	Consolidate design documentation and rollout plans
2	Define the Host Sessions wire protocol
3	Implement the shared projection reducer
4	Build the framework-free sync client
5	Translate ACP events to canonical protocol
6	Implement the canonical sessions runtime
7	Build the sessions sync hub and route
8	Wire the new surface into host-service
9	Update mobile and legacy ACP references
10	Add integration tests and E2E user story
11	Other changes

_{Chapters generated by Stage for commit 2fdbde0 on Jul 12, 2026 9:27pm UTC.}

[bra1nDump]

Accidental duplicate of #5630 (same commit, different branch name) — consolidated there; #5630 keeps the review history.