Fix mobile agent timeline catch-up

docs/architecture.md

@@ -92,6 +92,7 @@ Cross-platform React Native app that connects to one or more daemons.
 - `SessionContext` wraps the daemon client for the active session
 - Composer UI and submit/draft behavior live in `packages/app/src/composer/`; screens and panels should integrate it from there instead of dropping composer internals into `components/`, `hooks/`, or `screens/workspace/`
 - Timeline reducers in `timeline/session-stream-reducers.ts` handle compaction, gap detection, sequence-based deduplication
+- Timeline sync correctness is documented in [docs/timeline-sync.md](timeline-sync.md): live streams are for immediacy, `fetch_agent_timeline_request` is authoritative, and catch-up is paged but complete.
 - Voice features: dictation (STT) and voice agent (realtime)
 
 ### `packages/cli` — Command-line client
@@ -222,7 +223,7 @@ initializing → idle ⇄ running
 - **AgentManager** is the source of truth for agent state and broadcasts updates to all subscribers
 - Timeline is append-only with epochs (each run starts a new epoch). Storage uses sequence numbers for client-side dedup; the default fetch page is 200 items
 - Timeline row `timestamp` values are canonical daemon-owned timestamps. Providers may supply original replay timestamps, but clients must not guess timestamp trust or hide time UI based on local clock heuristics.
-- Events stream to all subscribed clients in real time
+- Events stream to connected clients in real time; correctness is backed by authoritative timeline fetches and paged-to-completion catch-up.
 - Agent state persists to `$PASEO_HOME/agents/{cwd-with-dashes}/{agent-id}.json` (timeline rows live alongside the record)
 
 ## Agent providers

docs/timeline-sync.md

@@ -0,0 +1,42 @@
+# Timeline sync
+
+Agent chat delivery has two paths:
+
+1. **Live stream** — `agent_stream` WebSocket messages for immediacy.
+2. **Authoritative history** — `fetch_agent_timeline_request` for correctness.
+
+The invariant is:
+
+> If the daemon has committed timeline rows for an agent, any connected client that opens or resumes that agent eventually displays every row through the daemon's current tail.
+
+## Presence is not delivery
+
+Client heartbeat reports presence:
+
+- device type
+- app visibility
+- focused agent
+- last activity time
+
+Heartbeat is used for notification routing. It must not be used as a correctness gate for `agent_stream` delivery. A stale mobile focus heartbeat may affect whether the user gets notified; it must not make timeline rows disappear from the live stream.
+
+## Catch-up is paged but complete
+
+Large unbounded timeline responses can exceed relay frame limits, so catch-up uses bounded pages. Bounded does not mean partial.
+
+When the app fetches `direction: "after"` and the daemon responds with `hasNewer: true`, the app must immediately fetch the next page from `endCursor`. The catch-up is complete only when `hasNewer: false`.
+
+The first load of an agent without a local cursor is different: it fetches a bounded latest tail page. Older history remains user-driven by scrolling upward.
+
+## Resume behavior
+
+When a client resumes with a known cursor, it catches up after that cursor to completion. It does not replace the view with a latest tail page, because tail pagination can skip the middle of a long background run.
+
+When a client resumes without a cursor, it fetches the latest tail page.
+
+## Relevant code
+
+- Server live stream forwarding: `packages/server/src/server/session.ts`
+- App sync planning: `packages/app/src/timeline/timeline-sync-plan.ts`
+- App stream/timeline reducer: `packages/app/src/timeline/session-stream-reducers.ts`
+- Session wiring: `packages/app/src/contexts/session-context.tsx`