[Bug]: Claude Read images stay inline as base64 in both event and projection rows (1.4 GB, 46% of statev2.sqlite, in one week) #26591

Before submitting

• I searched existing issues and did not find a duplicate. [Bug]: V2 stores tool-result image bytes twice per item, and no client reads them #16647 and fix(server): stop storing tool image bytes no client reads #16652 fixed the unserved copies (tool_use_result.file.base64). This report is about the served image block that fix(server): stop storing tool image bytes no client reads #16652 deliberately keeps, which for Read is the entire file.
• I included enough detail to reproduce or investigate the problem.

Area

apps/server

Steps to reproduce

1. Start a Claude thread on current main, or on any nightly after 2026-10-07, and ask it to Read a PNG of a few hundred KB. Repeat a few times, or let an agent work on screenshots for a day.

2. Open statev2.sqlite read-only and measure the stored item:

   SELECT length(payload_json), json_extract(payload_json, '$.output[0].type'),
          json_extract(payload_json, '$.output[0].source.type'),
          length(json_extract(payload_json, '$.output[0].source.data'))
   FROM orchestration_v2_projection_turn_items
   WHERE type = 'dynamic_tool' AND json_extract(payload_json, '$.toolName') = 'Read'
   ORDER BY length(payload_json) DESC LIMIT 3;

3. Run the same measurement on the matching turn-item.updated row in orchestration_events.

Expected behavior

Reading an image adds a small row to each table, and the image bytes exist once on disk in the attachments directory, like user uploads and MCP app snapshots. The Read row already carries viewedImagePath for its preview.

Actual behavior

The Read item's output is [{ type: "image", source: { type: "base64", media_type: "image/png", data: "<whole file>" } }]. The server writes that payload unchanged to both orchestration_events and orchestration_v2_projection_turn_items. Reading the same file five times stores it ten times, and event compaction never removes the event copy.

I measured one install read-only with dbstat. It is a macOS desktop install, the rows come from nightlies between 2026-10-19 and 2026-10-25, and the behavior is the same on 0.1.4-nightly.20261028.3824 and on main @ d07c0a7.

The server wrote every one of those rows after #16652 merged. This install has no Codex inputImage rows and no sizeBytes-marker rows above 20 KB, so the bloat comes only from the Claude Read path.

SQLite rewrites pages across the whole file, so every file-level backup (Time Machine, iCloud, Dropbox) copies the full multi-GB statev2.sqlite after each session. Attachment files never change after the server writes them.

Impact

Major degradation or frequent failure. Anyone whose agents read screenshots sees the database grow by hundreds of MB per image-heavy day, and it never shrinks.

Version or commit

main @ d07c0a7. Nightlies from 2026-10-19 to 2026-10-25 produced the rows, and 0.1.4-nightly.20261028.3824 reproduces it.

Environment

macOS 26, T3 Code desktop (Nightly) as host, Claude Code provider.

Where the bytes come from

All references are to main @ d07c0a7.

• outputFromClaudeToolResult (apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts:3074) returns toolResult.content for tool_result. An image Read therefore becomes a dynamic_tool item whose output is the raw content array, image block included.
• ProviderEventIngestor.ts:658 runs stripUnservedToolOutputImageBytes from fix(server): stop storing tool image bytes no client reads #16652. That helper returns served blocks untouched: if (record.type === "image" && isServed(context, record)) return record; in apps/server/src/orchestration-v2/toolOutputImageBytes.ts.
• A block counts as served when three conditions hold. readToolOutputImage recognises it (packages/shared/src/toolOutput.ts:217), it is among the first MAX_TOOL_OUTPUT_IMAGES = 8 blocks, and its base64 is under MAX_TOOL_OUTPUT_IMAGE_BASE64_LENGTH (10 MiB raw). A Claude tool_result image block meets all three, so the helper keeps the whole file.
• The helper keeps it because the tool-output-image asset route reads the bytes back out of the projection row. AssetAccess.readToolOutputImage calls orchestrator.getTurnItem and returns toolOutputImages(item.output)[index] (apps/server/src/assets/AssetAccess.ts:240-252).
• The turn-item.updated event carries the same payload, so the bytes also land in orchestration_events. According to the maintainer triage on [Bug]: V2 stores tool-result image bytes twice per item, and no client reads them #16647, event compaction skips turn-item.updated.

#16652 removed the copies that no client reads. It kept the copy the asset route reads, because the row is the only place that copy exists, and the event log holds a second one.

Proposed fix

The fix is small and server-only. Write served tool-output images to the attachments directory and store a reference in the row. MCP app snapshots already work this way: apps/server/src/mcpApps/McpAppSnapshot.ts:67 writes the HTML to the attachments directory and stores the attachment id in the item output.

1. Where stripUnservedToolOutputImageBytes runs today, write each served block's bytes to the attachments directory and replace the block with { type: "image", mimeType, attachmentId, sizeBytes }. Ids come from createDeterministicAttachmentId(threadId, sha256(bytes)) (apps/server/src/attachmentStore.ts:91). Rereading the same file in a thread then writes nothing new, and a replayed event keeps its id.
2. AssetAccess.readToolOutputImage resolves the block by attachmentId with resolveAttachmentPathById when the id is present, and by inline data otherwise. Rows written before the change keep working.
3. ProjectionStore.getThreadAttachmentIds (ProjectionStore.ts:5196) already collects attachment ids from dynamic_tool rows for the attachment.cleanup effect on thread delete. Adding the new key to that query makes thread deletion remove its images.

Clients do not change. They already request tool-output-image by item and index, and omitToolOutputImageData already keeps the bytes off the wire. After the fix, a Read of any image stores a row under 4 KB in each table. An image-heavy day adds the size of the distinct images read to the attachments directory, instead of about 400 MB to the database.

These are out of scope:

• Rewriting existing rows. A migration plus VACUUM would recover about 1.4 GB on this install, but it rewrites immutable events and deserves its own decision.
• Codex inputImage outputs ([Bug]: Codex image generation returned through functions.exec is invisible on Windows desktop and Android #19059, fix(server): show Codex tool-output images inline #23284).
• Codex imageGeneration items ([Bug]: Codex generated images are missing from V2 output unless the reply embeds them #15420, fix(server): Codex generated images show in chat, including on Android with a Windows host #19066).
• OpenCode image results ([Bug]: OpenCode V2 image-generation results are reduced to empty text and not displayed #21746, fix(opencode): keep image file blocks in V2 tool results #21796).
• Thread-level retention ([Bug]: Deleting a thread says it permanently clears its history, but V2 keeps every event and projection row #17845).

Related

• [Bug]: V2 stores tool-result image bytes twice per item, and no client reads them #16647 and fix(server): stop storing tool image bytes no client reads #16652: the previous fix, which this report extends.
• fix: tool screenshots show as images, not base64 text #16199: added the tool-output-image asset route, which this fix keeps.
• [Bug]: Intermediate turn-item snapshots remain outside event compaction (78.5 MB on one install) #19780, [Bug]: Deleting a thread says it permanently clears its history, but V2 keeps every event and projection row #17845, idx_orch_events_correlation_id has no query user: 44 MB and about 9% of insert cost on a real 19.8 GB database #20534, [Bug]: Thread-shell and recovery queries take 2–22 s on a 26.5 GB V2 database; six proposed indexes (follow-up to #22659) #23000: other database-growth reports. On this install, this one is the largest single source.
• fix(clients): later image reads show updated file contents #23510 and fix(clients): chat images show the new file after an agent rewrites it #14943: Read previews go stale when the agent rewrites the file. Taking an immutable copy at read time could also fix that, but I have not tested it.

Workaround

No workaround keeps the history. Deleting threads does not free the rows (#17845).

I can submit the PR

I would like to send this as one PR, fix(server): store served tool-output images as attachments. It covers the write at ingest, the read in the asset route, the cleanup query, and these tests:

• A Claude Read fixture stores a row under 4 KB in both tables.
• The asset route serves the same bytes back.
• Reading the same image twice writes one attachment.
• Deleting the thread deletes the attachment.

The PR changes no contracts and no client code, so the before/after row sizes are the only evidence it needs.

I have one design question before I start. Should the file write live in ProviderEventIngestor, next to the existing strip, where it covers every adapter that emits a served block? Or should it live in ClaudeAdapterV2, where the tool_result first arrives, the way the Codex adapter handles MCP app snapshots? The ingestor is the smaller diff, but I will follow whichever you prefer.