fix(agent): unify atomic hydration and material progress

[timigod]

Summary

• combine the accepted fix(server): hydrate provider history atomically #2763 and feat: expose provider-neutral material progress snapshots #2765 heads on current main
• preserve atomic provider-history hydration, admission ordering, occurrence-aware reconciliation, and terminal provider-child state
• preserve durable timeline epochs and provider-neutral material-progress checkpoints across refresh, rewind, restart, and successor hydration
• prevent timestamp-less stale Codex child history from reverting a terminal child to running

This draft is intended to supersede #2763 and #2765 only after independent acceptance of this replacement. The original PRs remain open.

Verification

• agent manager and file timeline store: 172 passed
• seven focused server files: 177 passed, 4 skipped
• protocol schema and CLI inspect: 4 passed
• npm run build:protocol
• npm run build:server
• npm run typecheck
• npm run lint
• npm run format and npm run format:check
• git diff --check 048b82f2a7b3ecc9b62bc5b817729f4ca2741863..HEAD

[timigod]

Exact-head independent rereview: READY.

Accepted commit: 2d1c4bdec65baa5b8844e3d448f4fa991b8bb226
Tree: 55914c338f4f2882594327637d1a4194bc5efa8c
Base: 048b82f2a7b3ecc9b62bc5b817729f4ca2741863

The full base-to-head conflict audit retained both original invariant sets from #2763 and #2765: atomic hydration and durable tail replacement, reserved-occurrence matching, admission-terminal child retention including timestamp-less stale history, provider-neutral material-progress persistence/projection/rewind, explicit refresh ordering, and exactly-once terminal carry-forward.

Independent gates: overlap suite 209/209, protocol/CLI/E2E 5/5, server typecheck, zero-finding lint, format, and diff check. Worktree remained clean; no live mutation.

[greptile-apps]

Greptile Summary

This PR unifies atomic provider-history hydration with durable, epoch-bound material-progress tracking.

• Adds persisted per-agent timeline files and incarnation epochs.
• Reconciles provider history with concurrently admitted timeline and child-agent events.
• Tracks and exposes material-progress checkpoints through server snapshots, protocol schemas, and CLI inspection.
• Preserves or resets checkpoints across restart, replacement, rewind, and hydration according to timeline continuity.

Confidence Score: 4/5

The final timeline append must be drained before agent closure completes, otherwise an immediate shutdown or reopen can restore incomplete history.

Timeline rows are committed to memory before their durable append finishes, and the close path can return while that append remains outstanding, leaving the final rows unavailable to a restart or successor store.

Files Needing Attention: packages/server/src/server/agent/agent-manager.ts

Important Files Changed

Filename	Overview
packages/server/src/server/agent/agent-manager.ts	Integrates atomic hydration, event admission, epoch-bound checkpoints, and asynchronous persistence; closure can outpace the final durable append.
packages/server/src/server/agent/file-agent-timeline-store.ts	Adds atomic per-agent timeline persistence with serialized mutations and durable epochs.
packages/server/src/server/agent/material-progress.ts	Implements incremental classification, deduplication, compaction counting, continuation settlement, and payload projection.
packages/protocol/src/messages.ts	Adds an optional, validated material-progress snapshot and server feature advertisement.
packages/server/src/server/agent/agent-projections.ts	Projects the manager's checkpoint into agent snapshot payloads.
packages/server/src/server/agent/agent-storage.ts	Persists the optional material-progress checkpoint with existing agent records.

Sequence Diagram

sequenceDiagram
  participant Provider
  participant Manager as AgentManager
  participant Memory as In-memory timeline
  participant Disk as File timeline store
  participant Progress as Material progress

  Provider->>Manager: Timeline event
  Manager->>Memory: Append canonical row
  Manager->>Progress: Advance checkpoint
  Manager-->>Disk: Queue durable append
  Note over Manager,Disk: Close currently does not await this write
  Manager->>Manager: Close agent
  Manager-->>Provider: Closure complete

Loading

_{Reviews (1): Last reviewed commit: "fix(agent): unify atomic hydration and m..." | Re-trigger Greptile}

[greptile-apps]

Closure leaves timeline writes pending

When a timeline row is recorded immediately before agent closure and the daemon exits, recordTimeline queues the durable append without awaiting it while closeAgentRuntime returns without draining that task, causing the next startup to restore an incomplete timeline and material-progress checkpoint.