From the Inside Claude Code: The Claude Code Ecosystem architecture map

A failed SessionStore append is retried, then dropped; mirror_error is the only signal

observation · medium · verified

The CLI streams transcript_mirror frames on stdout. The read loop in Control Protocol Query hides them from callers and hands them to the Transcript Mirror Batcher, which flushes to SessionStore.append before each result is yielded. A failed append is retried up to 3 times; a 60s timeout is not retried. Then the batch is dropped, and the only signal is a system message with subtype mirror_error. 7 parts of the system depend on Session Store, none with an alternative.

Impact: A custom store that fails persistently loses transcript entries silently unless the caller watches for mirror_error; the local-disk transcript stays intact and the session carries on.

Recommendation (small effort): Handle system messages with subtype mirror_error in your consumer and alert on them. Make custom SessionStore.append idempotent by deduplicating on entry uuid, since a retried batch may overlap an earlier partial write.

The trail

  1. ClaudeSDKClient
  2. Session Store
  3. Internal Client
  4. Package Exports
  5. Session Mutations
  6. Session Resume
Open on the map

More from this board

© 2026 Syntaxia App Platform Ltd.

Syntaxia App Platform Ltd. Registered in England and Wales, company no. 15272701 Registered office: 3rd Floor, 86–90 Paul Street, London EC2A 4NE, United Kingdom contact@provenmap.com