[kitlangton]

What it does

Adds an offline script that moves inline base64 media in existing session rows into the blob table, so databases written before the blob write path shrink too. It's experimental and something you run by hand. Nothing runs it automatically, and the experimental.media_blob flag (off by default) still decides only how new writes are stored.

Stack, built on the merged #58656: write (#58741, merged) → wire (#59103) → app (#59104) → backfill (this PR).

Optional offline cleanup: last in the stack, and it can land later. Clients don't need it.

bun packages/core/script/backfill-blobs.ts <path/to/opencode.db> [--vacuum-into <out.db>]

Why

Every image or file a user attached, and every tool screenshot, is stored as base64 inside its message row, a third larger than the raw bytes. The same image is copied again into the inbox row and into each update of a tool result. #58741 stops that for new writes. This handles the rows that already exist. Before → after database size has not been measured yet.

How it works

1. It refuses to run unless the blob migration is recorded in the database, so start OpenCode once on it first. It never creates tables.
2. For each session_message and session_inbox row that has inline media, it stores the decoded bytes once in blob, swaps in a media:<hash> ref and records a blob_ref row, using SessionBlob.split from the wire PR. It's byte-preserving: nothing is resized or re-encoded, so reads return the same data as before.
3. Rows are decoded and hashed outside the lock, then written in small batches under BEGIN IMMEDIATE with a 1s busy timeout, so it fails fast when a server holds the lock. A row that changed after it was read is skipped. Re-running is safe: rows that already hold refs only get their missing blob_ref rows.
4. --vacuum-into <out.db> writes a compacted copy. The database path is read correctly whether it comes before or after the flag.

Risk

It's an offline tool that rewrites rows in the database you point it at, so back it up first. Running it against a database a server is writing to fails fast instead of waiting. --vacuum-into needs free disk space about the size of the database. Reads already understand ref rows (from #58656), so backfilled rows read the same whether the flag is on or off.

Proof

• bun test test/session-blob-backfill.test.ts (packages/core): 3 pass. They cover byte-for-byte storage, recorded refs and an idempotent re-run; refusal before the migration with the database untouched; skipping a row that changed mid-batch; and failing fast when another writer holds the lock. They ran with the core prompt, owned, projector and store tests at this head (95 pass).
• bun run typecheck (core): clean. oxlint on changed files: 0 errors.