fix: continue paginating transcript history (#3174)

This commit is contained in:
Carlos Florêncio
2026-08-31 09:13:50 +00:00
committed by GitHub
parent 361d561cb7
commit fd2c7dcdff
26 changed files with 1450 additions and 428 deletions
@@ -0,0 +1,155 @@
---
created: 2026-08-30
status: implemented
requirements:
- REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001
system_design:
- ../../specs/ui/system-design/task-prompt-transcript-visibility.md
legacy_specs: []
---
# Implementation plan: Continuous conversation history pagination
## Overview
Make the transcript distinguish initialized history from default empty state,
then use that state to suppress the task-description fallback until the true
conversation start is reached. After that boundary is trustworthy, replace
visible-row identity pagination stops with committed sentinel geometry and
show the manual loader only for recoverable failures.
## Scope
### In scope
- Record whether authoritative message pagination metadata initialized.
- Gate the synthetic task description on initialized, exhausted history.
- Continue upward pagination while the committed sentinel remains in preload.
- Keep prompt `#1` as the visible start.
- Show the explicit older-page control only after error or no progress.
- Preserve scroll anchors and raw search pagination.
- Prove the same outcome on desktop and mobile with tool-heavy history.
### Out of scope
- Backend queries, cursor fields, persistence, or message ordering.
- Eagerly loading history when a task opens.
- Rendering internal rows before prompt `#1`.
- Changing prompt-history panel behavior beyond shared state compatibility.
- New user-facing copy or a new mobile composition.
## Confirmed root cause
`shouldShowTaskDescriptionFallback` checks only the currently loaded visible
rows. A bounded newest window containing no user row therefore synthesizes the
task description while raw `has_more` is still true.
The native transcript stops a load cycle whenever an older page changes the
oldest visible boundary. Its retry path requires `scrollTop` to decrease, which
cannot happen while the reader is pinned at the top. The always-visible manual
loader becomes the only reliable continuation.
The reported running session placed the latest user prompt behind 516 newer
rows. The initial 100-row window plus 20-row older pages required 21 requests,
which made both defects visible.
## Technical approach
### Trustworthy transcript start
- Add an initialization bit to per-session message metadata and its merge,
hydration, default, reconciliation, and purge paths.
- Expose initialized and raw-history state from `useSessionMessages`.
- Pass an explicit history-start condition into `useProcessedMessages`.
- Require initialized, exhausted history before synthesizing the task
description when no stored user prompt is visible.
- Keep prompt ordinals and the visible `hasMore` boundary unchanged.
### Geometry-driven pagination and recovery
- Re-evaluate the sentinel against the scroll root and configured preload
margin after page commit and prepend restoration.
- Continue positive loads while current geometry remains eligible, regardless
of whether a standalone boundary key changed.
- Retain boundary keys for scroll anchoring and diagnostics, not continuation.
- Track a transcript-local recovery state for rejected or zero-progress loads.
- Render the existing localized older-page button only in recovery state and
clear that state after progress, exhaustion, prompt `#1`, or session change.
- Give the recovery control a coarse-pointer 44-pixel hit area while retaining
existing desktop density.
## Tests
| Acceptance criteria | Evidence |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.1` to `.4` | `use-processed-messages-fallback.test.ts`, session slice/fetch tests |
| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.5` to `.8` | `use-lazy-load-sentinel.test.ts`, `message-list-native.test.tsx`, `message-list-shared.test.tsx` |
| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.9` | Existing native prepend-anchor unit and browser assertions |
| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.10` | Existing bounded-opening browser request watcher |
| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.12` | Existing inactive-session reconciliation coverage |
The TDD regression starts with the current tool-heavy case: initialized
history has `hasMore: true`, contains agent/tool rows, and has no loaded user
row. The expected synthetic fallback count is zero, which fails against the
current implementation.
## E2E tests
- Desktop Chromium: update
`apps/web/e2e/tests/chat/message-pagination.spec.ts` to prove one upward
navigation crosses more than twenty tool-heavy pages, reveals the stored
latest prompt, and never shows the task-description fallback or normal retry
control.
- Mobile Chrome: update
`apps/web/e2e/tests/chat/mobile-message-pagination.spec.ts` with the same user
outcome in the full-height mobile Chat surface.
- Shared seed: extend
`apps/web/e2e/tests/chat/message-pagination-helpers.ts` with an efficient
long-history fixture and retain prompt-`#1`, hidden pre-prompt, and anchor
scenarios.
## Mobile design contract
- Desktop outcome: continuous upward history loading reaches the stored prompt
without a misleading synthetic prompt or routine manual loader.
- Mobile entry point: the existing Chat tab in the full-height task layout.
- Nearest exemplar: `apps/web/components/task/task-layout.tsx` and the current
mobile pagination spec.
- Hierarchy and surface: no composition change; the transcript remains the
single vertical scroll owner.
- Shared logic: desktop and mobile use the same store, hooks, cursor
coordinator, sentinel, and recovery state.
- Mobile-specific detail: the recovery control keeps a 44-pixel coarse-pointer
hit area.
- Mobile proof: the `mobile-chrome` flow reaches the stored prompt with one
upward navigation and exercises recovery without horizontal or nested
scrolling.
## Work orders
- [x] [Task 01: Establish the true transcript start](task-01-establish-transcript-start.md) (`done`)
- [x] [Task 02: Continue pagination through the preload region](task-02-continue-preload-pagination.md) (`done`)
## Verification results
- Focused Task 01 Vitest suite: passed (5 files, 87 tests).
- Focused Task 02 Vitest suite: passed (4 files, 115 tests).
- `pnpm run typecheck`: passed.
- `make build-web`: passed; Vite emitted existing chunk-size and dynamic-import
warnings only.
- Desktop Chromium pagination: passed (6 tests).
- Mobile Chrome pagination: passed (6 tests).
- `git diff --check`: passed.
## Risks
- Default `hasMore: false` must not be mistaken for an authoritative exhausted
response before history initializes.
- Boot hydration, WebSocket-only rows, refetch reconciliation, and deletion
must not leave stale initialization metadata.
- Geometry checks must use committed layout and current scroll-root bounds so
stale observer entries cannot cascade through off-screen history.
- A zero-result response and a real request error currently both surface as no
progress; both require recovery without an automatic retry loop.
- The long-history browser seed must remain deterministic and fast enough for
desktop and mobile projects.
@@ -0,0 +1,108 @@
---
id: "01-establish-transcript-start"
title: "Establish the true transcript start"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001
acceptance_criteria:
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.1
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.2
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.3
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.4
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.10
system_design:
- ../../specs/ui/system-design/task-prompt-transcript-visibility.md
---
# Task 01: Establish the true transcript start
## Summary
Record when session message history has authoritative pagination metadata and
use that state to prevent a bounded tool-only window from synthesizing the task
description. Preserve bounded opening and prompt-`#1` behavior.
## In scope
- Add and maintain per-session message-history initialization state.
- Expose initialized and raw-history state through the session hook.
- Gate task-description fallback on initialized, exhausted history.
- Preserve stored user prompts as authoritative.
- Add the failing tool-only-window regression before implementation.
## Out of scope
- Sentinel continuation and retry-control behavior.
- Backend message APIs or persistence.
- Eager history loading.
## Acceptance
- An initialized window with older history and no user row renders no synthetic
task description.
- Exhausted legacy history with no user row renders one non-empty fallback.
- Uninitialized, refetching, prompt-`#1`, and empty-description cases do not
produce a misleading or duplicate fallback.
## Verification
```bash
cd apps/web
pnpm exec vitest run \
hooks/use-processed-messages-fallback.test.ts \
hooks/domains/session/use-session-messages.test.ts \
hooks/domains/session/use-session-message-fetch.test.ts \
lib/state/slices/session/session-slice.merge-messages.test.ts \
components/task/chat/message-list-shared.test.tsx
pnpm run typecheck
```
## Files likely touched
- `apps/web/lib/state/slices/session/types.ts`
- `apps/web/lib/state/slices/session/session-slice.ts`
- `apps/web/lib/state/slices/session/session-slice.merge-messages.test.ts`
- `apps/web/lib/state/hydration/merge-strategies.ts`
- `apps/web/hooks/domains/session/use-session-messages.ts`
- `apps/web/hooks/domains/session/use-session-message-fetch.test.ts`
- `apps/web/components/task/chat/use-chat-panel-state.ts`
- `apps/web/hooks/use-processed-messages.ts`
- `apps/web/hooks/use-processed-messages-fallback.test.ts`
- `apps/web/components/task/chat/message-list-shared.test.tsx`
## Dependencies
None.
## Risks
- Boot-hydrated and client-fetched sessions must set the same initialization
state.
- Live rows arriving before the newest snapshot must not claim that history is
initialized or exhausted.
- Purged sessions must not retain metadata that affects a later session.
## Parallelism
`sequential`
## Inputs
- `REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001` acceptance criteria `.1` to
`.4` and `.10`.
- History state and opening boundary sections of the system design.
- Existing message-window reconciliation and processed-message fallback tests.
## Results
- Added per-session `historyInitialized` metadata with safe defaults, live-row
isolation, newest-window fetch/boot hydration, and purge-compatible state.
- Gated the task-description fallback on initialized, exhausted history while
preserving stored user prompts and the prompt-`#1` visible boundary.
- Added regressions for older history, uninitialized history, live inserts, and
authoritative fetch metadata.
- The focused Task 01 Vitest suite passed (5 files, 87 tests).
- `pnpm run typecheck` passed.
@@ -0,0 +1,133 @@
---
id: "02-continue-preload-pagination"
title: "Continue pagination through the preload region"
status: done
wave: 2
depends_on:
- "01-establish-transcript-start"
plan: "plan.md"
requirements:
- REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001
acceptance_criteria:
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.5
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.6
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.7
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.8
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.9
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.11
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.12
system_design:
- ../../specs/ui/system-design/task-prompt-transcript-visibility.md
---
# Task 02: Continue pagination through the preload region
## Summary
Make positive older-page loads continue from committed sentinel geometry
instead of visible-row identity. Show the existing loader only for recoverable
error or no-progress state, then prove the combined flow on desktop and mobile.
## In scope
- Evaluate current sentinel geometry after layout and scroll restoration.
- Continue while the sentinel remains inside the configured preload region.
- Retain prompt `#1`, exhaustion, stale-session, and no-progress stops.
- Track recovery state and expose a managed retry action.
- Hide the manual loader during normal pagination.
- Preserve prepend anchoring and raw search backfill.
- Add desktop and mobile long-history regressions.
## Out of scope
- Changes to initial history-fetch size or older-page size.
- Backend cursors or message persistence.
- A new mobile surface or new localized copy.
## Acceptance
- One upward navigation crosses short standalone and collapsed pages while the
sentinel remains in preload, then stops when current geometry leaves it.
- Successful pagination never exposes the manual loader; failure or no progress
exposes one retry control and a successful retry clears it.
- Desktop and mobile reach a stored prompt more than twenty older pages away
without a click while retaining stable scroll position.
## Verification
```bash
cd apps/web
pnpm exec vitest run \
hooks/use-lazy-load-sentinel.test.ts \
hooks/use-lazy-load-messages.test.ts \
components/task/chat/message-list-native.test.tsx \
components/task/chat/message-list-shared.test.tsx
pnpm run typecheck
```
```bash
make build-web
cd apps/web
pnpm e2e:run --host --no-build --project chromium -- \
tests/chat/message-pagination.spec.ts
pnpm e2e:run --host --no-build --project mobile-chrome -- \
tests/chat/mobile-message-pagination.spec.ts
```
## Files likely touched
- `apps/web/hooks/use-lazy-load-sentinel.ts`
- `apps/web/hooks/use-lazy-load-sentinel.test.ts`
- `apps/web/components/task/chat/message-list-native-scroll.ts`
- `apps/web/components/task/chat/message-list-native.tsx`
- `apps/web/components/task/chat/message-list-native.test.tsx`
- `apps/web/components/task/chat/message-list-shared.tsx`
- `apps/web/components/task/chat/message-list-shared.test.tsx`
- `apps/web/e2e/tests/chat/message-pagination-helpers.ts`
- `apps/web/e2e/tests/chat/message-pagination.spec.ts`
- `apps/web/e2e/tests/chat/mobile-message-pagination.spec.ts`
## Dependencies
- Task 01 must provide authoritative transcript-start state before the combined
browser flow changes fallback expectations.
## Risks
- Geometry must be measured after prepend restoration, not from a stale
IntersectionObserver sample.
- Recovery retries must not loop automatically on the same failed cursor.
- The recovery control needs a 44-pixel coarse-pointer target without changing
fine-pointer desktop density.
- Long-history fixtures must not make focused E2E runs flaky or exceed their
existing timeout budget.
## Parallelism
`sequential`
## Inputs
- `REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001` acceptance criteria `.5` to
`.9`, `.11`, and `.12`.
- Upward pagination, failure and recovery, and responsive sections of the
system design.
- Existing lazy-sentinel, native-scroll, desktop, and mobile pagination tests.
## Results
- Replaced visible-boundary continuation with committed sentinel/root geometry,
retaining boundary keys for anchoring and diagnostics.
- Added transcript-local recovery state and an explicit retry path for rejected
or zero-progress requests; routine successful pagination stays button-free.
- Added committed-geometry continuation and session-epoch guards so stale
observer entries and prior-session settlements cannot stop or alter the
current transcript.
- Preserved the desktop fine-pointer density and added a coarse-pointer
minimum 44-pixel recovery target.
- Added long-history and short-boundary fixtures plus matching desktop/mobile
browser regressions.
- The focused Task 02 Vitest suite passed (4 files, 115 tests).
- `pnpm run typecheck` and `make build-web` passed.
- Chromium pagination passed (6 tests); mobile Chrome pagination passed (6
tests).
@@ -5,126 +5,50 @@ created: 2026-08-22
owners:
- kandev
---
# Task transcript history visibility Requirements
# Task transcript history visibility requirements
## Overview
The transcript can lose the original task prompt after a reload. Long activity groups can also make older history difficult to reach. An older page can add tool events only inside an existing collapsed row. The user then sees no new entry and must select **Load older messages** again.
Task transcripts open on a bounded newest window and load older history as the
user navigates upward. A bounded window is not the start of the conversation.
The transcript must not substitute the task description for an unloaded user
prompt, and upward navigation must not require routine use of a manual loader.
## Terms
- **Visible start:** The first stored user prompt, normally prompt `#1`.
- **Task-description fallback:** A synthetic user row used only for legacy
history that contains no stored user prompt.
- **Preload region:** The area near the oldest loaded edge where upward
pagination can continue without another user action.
## Requirements
### REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001: Task transcript history visibility
**Intent:** The transcript can lose the original task prompt after a reload. Long activity groups can also make older history difficult to reach. An older page can add tool events only inside an existing collapsed row. The user then sees no new entry and must select **Load older messages** again.
**Intent:** Users can navigate continuously from the newest response to the
first prompt without mistaking a bounded history window for the conversation
start.
#### Acceptance criteria
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.1:** When visible session history has no user-authored message, show the task description as the first user prompt.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.2:** Keep the task description visible while agent or environment messages load.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.3:** Treat a visible, stored user message as authoritative. Do not also show the task-description fallback in this case.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.4:** When the user scrolls to the oldest loaded point, load older history without a separate button action.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.5:** Continue automatic loading while older pages only extend a collapsed activity row.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.6:** Do not require another user action before a new standalone transcript entry appears.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.7:** Stop automatic loading in these cases:
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.8:** Older content moves the load boundary above the preload region.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.9:** When the first user prompt of a session is loaded, the transcript shall not show an older-page control.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.10:** When a previously opened session is revisited after more than one message page was persisted while it was inactive, the transcript shall reconcile to a contiguous newest window and upward pagination shall reach every persisted user prompt without gaps or duplicate rows.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.1:** When older session history remains and the loaded window contains no user-authored message, the transcript shall not show the task description as a user prompt.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.2:** The transcript shall show each stored user prompt at its chronological position after that prompt is loaded.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.3:** When prompt `#1` is loaded, the transcript shall treat it as the visible start and shall not expose older internal rows through transcript pagination or an older-page control.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.4:** When persisted history is exhausted without a stored user prompt, the transcript shall show a non-empty task description as the first user prompt and shall not add an empty fallback.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.5:** When the user reaches the oldest loaded edge, the transcript shall load older history without a separate button action.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.6:** After an older page commits, the transcript shall continue loading while the oldest-page sentinel remains in the preload region, whether the page extends a collapsed activity group or adds a standalone row.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.7:** Automatic older-history loading shall stop when the sentinel leaves the preload region, prompt `#1` is loaded, persisted history is exhausted, or a request fails to make progress.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.8:** When an older-page request fails or makes no progress while older history remains, the transcript shall show a retry control. Routine successful pagination shall not show this control.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.9:** The transcript shall keep the reader's current visual position stable while older content is inserted.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.10:** Opening a task shall request only the bounded newest window until the user navigates upward.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.11:** Desktop and mobile transcripts shall provide the same history boundary, continuous upward loading, recovery, and scroll-position behavior.
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.12:** When a previously opened session is revisited after more than one message page was persisted while it was inactive, the transcript shall reconcile to a contiguous newest window and upward pagination shall reach every persisted user prompt without gaps or duplicate rows.
## Migrated source detail
## Exclusions
## Why
The transcript can lose the original task prompt after a reload. Long activity
groups can also make older history difficult to reach. An older page can add
tool events only inside an existing collapsed row. The user then sees no new
entry and must select **Load older messages** again.
Users need continuous upward navigation from the latest response to the first
prompt. This requirement includes sessions with more than 100 tool events.
## What
- When visible session history has no user-authored message, show the task
description as the first user prompt.
- Keep the task description visible while agent or environment messages load.
- Treat a visible, stored user message as authoritative. Do not also show the
task-description fallback in this case.
- When the user scrolls to the oldest loaded point, load older history without
a separate button action.
- Continue automatic loading while older pages only extend a collapsed activity
row.
- Do not require another user action before a new standalone transcript entry
appears.
- Stop automatic loading in these cases:
- Older content moves the load boundary above the preload region.
- The session start is reached.
- A request makes no progress.
- Keep the current reading position stable as older content appears above it.
- Keep the explicit load action as a fallback for an error or a no-progress
response.
- Show the first prompt at the start after all older history is loaded.
- Apply the same transcript rule on desktop and mobile.
- Reconcile a revisited session to one contiguous newest window before older
pagination resumes. Stale cached rows must not create an unreachable gap.
## Scenarios
### Agent-only history
- **GIVEN** a task has a description and visible agent or environment messages.
- **GIVEN** the session has no visible user message.
- **WHEN** the transcript loads or reloads.
- **THEN** the task description remains the first message.
- **THEN** the other visible messages follow it.
### Stored user prompt
- **GIVEN** a task has a description and a visible stored user message.
- **WHEN** the transcript loads.
- **THEN** the stored user message represents the prompt.
- **THEN** the transcript does not show a duplicate task-description fallback.
### Empty task description
- **GIVEN** a task has no description and has agent-only history.
- **WHEN** the transcript loads.
- **THEN** the transcript does not add an empty fallback message.
### Collapsed activity spans older pages
- **GIVEN** a transcript has more than 100 tool events in one collapsed activity
row.
- **GIVEN** older pages contain no standalone transcript entry.
- **WHEN** the user scrolls to the oldest loaded point.
- **THEN** the transcript loads additional pages without repeated button
actions.
- **THEN** the current reading position remains stable.
### First prompt after complete pagination
- **GIVEN** the first prompt is older than the initial message window.
- **WHEN** the user continues to scroll upward until the session start.
- **THEN** the first prompt is visible at the start of the transcript.
- **THEN** no older-page control remains.
### Revisit after inactive-session activity
- **GIVEN** a session was opened and its older rows remain cached.
- **GIVEN** more than one newest-page window is persisted while that session is
inactive.
- **WHEN** the user revisits the session and navigates upward.
- **THEN** the transcript exposes every persisted user prompt in chronological
order without a skipped middle range or duplicate row.
## Out of scope
- Backfill or repair missing message records in the database.
- Change message persistence, API contracts, or transcript ordering.
- Expand activity groups by default.
- Remove the explicit older-page fallback action.
- Load the complete transcript before the user navigates upward.
## Implementation plan
- [Hide redundant older-message controls](../../../plans/hide-redundant-older-messages-control/plan.md)
- [Reconcile inactive-session transcript windows](../../../plans/inactive-session-transcript-reconciliation/plan.md)
- Backfill or repair of missing persisted message records.
- Changes to backend message ordering or cursor contracts.
- Loading the complete transcript before the user navigates upward.
- Rendering internal rows that precede stored prompt `#1`.
@@ -8,161 +8,162 @@ owners:
- kandev
---
# Task Transcript History Visibility System Design
# Task transcript history visibility system design
## Purpose and boundaries
This design defines the visible start of a task transcript. The first user prompt is the visible start, even when internal rows exist before it.
This design defines how the task transcript distinguishes a bounded newest
window from the visible conversation start. It keeps task opening bounded,
loads older history only after upward navigation, and preserves prompt `#1` as
the visible start even when older internal rows remain on the backend.
The design changes no backend query, message order, persistence rule, or API field. It uses the existing `prompt_index` message field.
The design changes no backend query, persistence rule, message order, or API
field. It uses existing cursor metadata and the existing `prompt_index` field.
## Requirement mapping
| Requirement | Design section |
| --- | --- |
| `REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001` | [Opening boundary](#opening-boundary), [Latest-window reconciliation](#latest-window-reconciliation), [Pagination boundary](#pagination-boundary), [Failure and compatibility](#failure-and-compatibility) |
| Requirement | Design sections |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001` | [History state](#history-state), [Opening boundary](#opening-boundary), [Upward pagination](#upward-pagination), [Failure and recovery](#failure-and-recovery), [Responsive behavior](#responsive-behavior) |
## Components and responsibilities
- `useLazyLoadMessages` owns the visible pagination boundary for transcript consumers.
- The session message fetch owns one bounded initial request for the newest message window.
- `messages.metaBySession[sessionId].hasMore` keeps the raw backend `has_more` value.
- `messages.metaBySession[sessionId].oldestCursor` names the oldest row in the
contiguous loaded window, never an older row separated from the newest
snapshot by an unloaded gap.
- `messages.bySession[sessionId]` supplies the loaded messages and their prompt ordinals.
- The native transcript and Prompt History panel consume the shared hook result.
- The native transcript owns the upward-navigation intent and the visible top-boundary key.
- The session message fetch owns one bounded newest-window request and records
when authoritative pagination metadata has initialized.
- `messages.metaBySession[sessionId]` owns raw `hasMore`, `oldestCursor`,
initial/refetch loading, older-page loading, and history initialization.
- `useSessionMessages` exposes the raw history state to chat composition.
- `useProcessedMessages` filters and groups stored messages. It may synthesize
the task-description fallback only after the session start is known.
- `useLazyLoadMessages` owns the prompt-`#1` visible boundary and older-page
requests. It keeps raw pagination available to explicit recovery consumers.
- The native transcript owns upward intent, committed sentinel geometry,
scroll restoration, and retry-control visibility.
- `useLazyLoadSentinel` owns observer lifecycle and request serialization.
- Transcript navigation uses only the messages that the transcript already loaded.
- The hook also exposes an explicit raw-pagination loader for direct recovery consumers, such as session search.
- `requestOlderMessages` keeps request coordination and raw cursor metadata unchanged.
The Prompt History panel already uses prompt `#1` as its terminal boundary. The transcript uses the same boundary through the shared hook.
## History state
The frontend distinguishes these facts:
- **History initialized:** An authoritative newest-window response or boot
payload supplied pagination metadata for the session.
- **Raw history remains:** The backend reported `has_more: true`.
- **Visible start loaded:** A loaded user message has `prompt_index === 1`.
- **History exhausted:** History is initialized and raw history does not remain.
Default store values are not proof that history is exhausted. The session
message metadata therefore records initialization separately from `hasMore`.
Session deletion purges this state with the rest of the session transcript.
The task-description fallback is eligible only when all of these conditions
are true:
1. History is initialized.
2. Raw history is exhausted.
3. No visible stored user message exists.
4. The task description is non-empty.
A tool-only newest window with `has_more: true` does not satisfy this contract.
It renders only the stored rows in that window until the user navigates upward.
## Opening boundary
The session message fetch requests only the newest bounded window when a task opens. A tool-only window does not start an automatic backfill.
The session message fetch requests only the newest bounded window when a task
opens. It does not paginate backward to locate a prompt. A live WebSocket row
can join that contiguous newest window through the existing reconciliation
rules.
`TaskChatPanel` does not load older pages to find the last prompt. The last-prompt action becomes available after the prompt enters the loaded window.
The latest-window reconciliation contract remains unchanged:
If the newest window has no user message, the transcript shows the task-description fallback. Upward navigation then loads older pages through visible pagination.
- An overlapping fetched suffix joins the cached contiguous window.
- A disjoint cached prefix is removed before the fetched suffix becomes the
new authoritative window.
- The oldest cursor always names the oldest row in the contiguous window.
## Latest-window reconciliation
The absence of a user row in the newest window neither starts background
pagination nor authorizes the task-description fallback.
The frontend represents each session transcript as one contiguous loaded
window. A latest-message fetch reconciles its bounded newest suffix with the
rows already cached for that session:
## Visible pagination boundary
- If the fetched suffix overlaps the cached window, deduplicate and retain the
complete joined window. The oldest cursor remains the oldest row in that
joined window.
- If the fetched suffix does not overlap the cached window, the older cached
rows cannot be joined under one pagination cursor. Replace that disjoint
cache with the fetched suffix. Retain only live rows that arrived after the
fetch started and therefore follow the response snapshot.
- Set the oldest cursor from the actual contiguous boundary. A disjoint cached
row must never become the cursor for the newest fetched suffix.
Transcript pagination remains available while raw history remains and loaded
messages do not contain user prompt `#1`. Loading prompt `#1` immediately
removes the transcript sentinel and retry control, even if raw backend history
contains internal rows before that prompt.
The dropped browser cache is not data loss. Persisted messages remain
authoritative and are loaded again through normal upward pagination. This rule
also preserves the bounded opening behavior: revisiting a session does not
subscribe to inactive siblings or eagerly load its complete transcript.
Payloads without prompt ordinals use raw exhaustion as the compatibility
boundary. Session search can continue through the explicit raw loader when a
backend search hit precedes the visible transcript start.
## Pagination boundary
## Upward pagination
The frontend derives a visible `hasMore` value from two inputs:
The transcript starts a load cycle when the user reaches the oldest loaded
edge. Before each request it captures a stable rendered-row anchor. After the
page commits, scroll restoration keeps that anchor at the same visual position.
1. The raw backend value is true.
2. No loaded user message has `prompt_index` equal to `1`.
Continuation uses committed sentinel geometry, not the identity of the oldest
standalone row:
If both conditions are true, transcript consumers can request another page. If prompt `#1` is loaded, the shared hook reports no visible older history.
1. Re-evaluate the sentinel against the transcript's preload region after
React layout and scroll restoration commit.
2. Continue when the sentinel remains in that region and visible pagination
still has more history.
3. Stop when inserted content moves the sentinel outside the region. A later
upward reach starts the next cycle through the normal observer path.
4. Stop at prompt `#1`, raw exhaustion, a stale session, or no progress.
The hook applies this rule to its reactive return value. It also applies the rule after each joined or completed request.
This rule crosses both collapsed activity pages and short standalone pages. It
also avoids cascading through content that has already moved above the user's
current preload region. A stale IntersectionObserver entry is not sufficient
to continue; the decision uses geometry from the current sentinel and current
scroll root after commit.
This immediate update stops one multi-page load operation at prompt `#1`. It prevents an extra request for pre-prompt internal rows.
## Failure and recovery
The store keeps the raw backend value. Direct recovery code can use the hook's explicit raw-pagination loader when its contract requires the complete message stream. Session search uses this path because backend search can return a hit from before prompt `#1`. Transcript rendering and navigation continue to use visible pagination, so this recovery path does not restore the older-page control.
A rejected request or a zero-row response with visible history still remaining
sets a transcript-local recovery state. While that state is active, the normal
automatic cycle is disarmed and the explicit older-page retry control is
visible. A successful retry clears recovery state and resumes the geometry
rule. Session changes, prompt `#1`, and raw exhaustion also clear it.
## Upward load cycle
An upward user action starts one transcript load cycle. The cycle starts when the reader reaches the oldest loaded boundary.
The transcript records the oldest standalone message key before each request. This key excludes the task-description fallback, transient status rows, and collapsed activity-group keys that can change when older tools join the group.
After React commits the prepended page, the transcript compares the current key with the recorded key:
- If the key changes, the page added a new visible top entry. The cycle stops until the reader reaches the new boundary.
- If the key does not change, the page only extended the current collapsed activity group. The cycle can request the next page.
- If the request fails, returns no rows, reaches prompt `#1`, or exhausts raw history, the cycle stops.
The shared sentinel must not continue from a stale intersection value. A completed request must use the committed render boundary before it starts another request.
Scroll restoration remains part of the same cycle. The transcript restores one stable row after each prepend. The restoration does not create new upward-navigation intent.
## Control flow
1. The initial message request stores one newest suffix and raw pagination metadata.
2. The fetch reconciles that suffix with any cached rows as one contiguous
window and records its true oldest cursor.
3. The shared hook reports visible older history while prompt `#1` is absent.
4. The user reaches the oldest loaded point.
5. An older-page request prepends messages through the existing coordinator.
6. The native transcript preserves a stable message-row position across the complete request.
7. The transcript compares the committed visible top boundary with the request baseline.
8. If the boundary changed, the current load cycle stops.
9. If only a collapsed activity group changed, the same cycle can request another page.
10. If the page contains prompt `#1`, the shared hook changes its visible value to false.
11. The transcript removes its sentinel, loading state, and older-page control.
12. Explicit reverse search uses raw pagination when it must backfill a backend search hit.
## Failure and compatibility
If a request fails before prompt `#1` is known, the explicit older-page control remains available. A zero-result response keeps the existing retry behavior.
If a latest fetch is disjoint from a stale cache, the UI temporarily stops
rendering the stale prefix rather than presenting a false contiguous window.
The older-page control remains available from the fetched suffix and reloads
that durable history from the correct cursor.
An initial tool-only window completes without an older-page request. The task-description fallback remains visible until upward pagination loads a stored user prompt.
Older payloads can omit `prompt_index`. In this case, the shared hook uses raw `has_more` exhaustion as the compatibility fallback.
Routine successful pagination does not render the retry control. The control
keeps the existing localized label and has a coarse-pointer hit area of at
least 44 pixels without increasing fine-pointer desktop density.
## Observability
The `messages:pagination` debug namespace records one start event and one settle event for each older-page request.
The events include the session ID, trigger, page count, visible boundary keys, scroll geometry, and the continuation reason. The events do not include message content.
The settle reason distinguishes collapsed-group continuation from visible-boundary stop, exhaustion, no progress, and request error.
The `messages:pagination` namespace records page start and settle events
without message content. Settle events include the session, trigger, count,
raw and visible boundaries, committed sentinel geometry, continuation, and
stop reason. Recovery entry and exit use distinct reasons so a real request
failure is distinguishable from leaving the preload region.
## Responsive behavior
Desktop and mobile use the same native transcript and one vertical scroll owner. This change adds no mobile surface, control, or touch behavior.
Desktop and mobile continue to use the existing full-height task Chat surface,
shared store, shared hooks, and one vertical transcript scroll owner. No new
mobile composition or navigation is introduced. The recovery button uses the
same placement on both surfaces with a coarse-pointer touch target.
The existing full-height mobile task layout remains the nearest mobile exemplar. The mobile pagination scenario proves the same load-cycle boundary.
The nearest mobile exemplar is `apps/web/components/task/task-layout.tsx` and
the existing `mobile-message-pagination.spec.ts` flow. The mobile scenario
must prove the same continuous loading, true-start fallback, recovery, and
anchor behavior as desktop.
## Test boundaries
- A hook test covers raw `has_more: true` with loaded prompt `#1`.
- A hook test covers the compatibility path when the ordinal is absent.
- A hook test proves that a multi-page load stops when a response adds prompt `#1`.
- Hook and drain tests prove that explicit search backfill can continue through the raw boundary.
- Desktop and mobile browser tests seed hidden pre-prompt rows and prove that no older-page control remains.
- Desktop and mobile browser tests prove that task opening makes no request with an older-page cursor.
- A message-fetch test proves that a tool-only initial window completes without automatic backfill.
- Latest-window reconciliation tests cover overlapping windows, a disjoint
stale cache, and live rows received while the fetch is in flight.
- A same-task sibling-session browser test caches an older receiver window,
persists a peer prompt plus more than one page while the receiver is
inactive, revisits it, and reaches the attributed prompt through upward
pagination.
- Separate desktop and mobile browser tests preserve the prepend anchor while loading older pages.
- Desktop and mobile browser tests prove that one upward action loads only one page when that page adds visible entries.
- A collapsed-activity browser scenario proves that the same load cycle continues until a new visible top entry appears.
- Sentinel unit tests prove that stale intersection state cannot start a second visible-page request.
## Related design
- [Prompt History Panel](prompt-history-panel.md) defines the `prompt_index` contract and its compatibility behavior.
- Processed-message tests cover an uninitialized window, a tool-only window
with older history, exhausted legacy history, an empty description, and a
loaded stored prompt.
- Session-state tests cover initialization through boot hydration, newest
fetch, purge, and refetch without inferring exhaustion from defaults.
- Sentinel tests cover committed in-region continuation, out-of-region stop,
stale observer entries, no-progress recovery, successful retry, and session
reset.
- Native transcript tests cover recovery-control visibility and prepend anchor
preservation.
- Desktop and mobile browser tests seed more than twenty older pages between
the newest window and the latest user prompt. They prove that no synthetic
initial prompt or routine retry control appears and that one upward
navigation reaches the stored prompt without a click.
- Existing prompt-`#1`, hidden pre-prompt, and inactive-session reconciliation
scenarios remain covered.