v0.6.25: existing 0.6.24 archive fails every readonly-first open (fsqlite.open_read_failure) on Linux; same untouched DB opens fine on 0.6.24

[ericziko]

Summary

Upgrading 0.6.24 → 0.6.25 makes an existing, healthy archive completely unopenable on Linux. Every readonly-first surface fails with fsqlite.open_read_failure; cass status reports db=open_failed and Search unavailable (database unusable).

The archive itself is fine. Downgrading the binary only — same DB file, byte-identical, mtime unchanged — restores full service immediately. I alternated the two binaries against the same untouched database and the result is perfectly deterministic.

This looks like a regression from the headline change in v0.6.25 (fsqlite =0.2.1 → =0.3.1), which reworked exactly this path ("sidecar-less read-only first-contact opens", fsqlite GH#140).

Reproduction

Both binaries run from separate paths against the same live data dir. No repair, rebuild, or mutating command was ever run.

db mtime before: 2026-08-15 23:17:27.726159863 -0700
0.6.25 run 1: db=open_failed
0.6.25 run 2: db=open_failed
0.6.25 run 3: db=open_failed
0.6.24 run 1: db=available
0.6.25 run 4: db=open_failed
0.6.24 run 2: db=available
db mtime after:  2026-08-15 23:17:27.726159863 -0700

4/4 failures on 0.6.25, 2/2 successes on 0.6.24, DB unmodified throughout.

Under 0.6.24 the archive is healthy and search works normally — e.g. cass search "frankenmermaid" --json returns 282 hits via the tantivy backend, db=available.

Verbatim error (0.6.25)

Database:
  Exists, but could not be opened
  Error: Failed to open state-meta database at /home/ubuntu/.local/share/coding-agent-search/agent_search.db: readonly storage open failed (opening frankensqlite db readonly at /home/ubuntu/.local/share/coding-agent-search/agent_search.db); raw readonly open failed (opening raw frankensqlite db readonly at /home/ubuntu/.local/share/coding-agent-search/agent_search.db)

cass diag reports the same with (code 9).

cass doctor check --json:

{"status":"unhealthy","reason_code":"db_unavailable","health_class":"degraded-archive-risk",
 "risk_level":"high","needs_rebuild":true,
 "root_cause":{"family":"frankensqlite-storage","locus":"dependency","confidence":"confirmed",
 "evidence_refs":[{"kind":"fsqlite.open_read_failure","locator":"diag"}]}}

What I ruled out

Not stale namespace sidecars (#393). I decoded agent_search.db-fsqlite-ns-use (40 bytes):

00000000: 4653 514c 4e53 3031 0101 0000 0000 0000  FSQLNS01........
00000010: 0801 0000 0000 003c 09e1 0000 0000 0000  .......<........

That encodes dev=0x801 (2049) and inode=0x3C09E1 (3934689). stat on the live DB returns exactly dev=2049 inode=3934689. The sidecar is current, not stale, and this host has not rebooted between the working and failing runs.

Not a dirty WAL (#389). RUST_LOG=debug shows the WAL opening cleanly immediately before the failure, and it is 32 bytes:

DEBUG WAL file opened page_size=4096 big_endian_checksum=false checkpoint_seq=51 valid_frames=0
 WARN failed to open database for diagnostics: ... readonly storage open failed ... (code 9)

Not a general inability to open any DB. 0.6.25 against a fresh empty --data-dir behaves correctly and reports db=missing, next=index_full. The failure is specific to opening a pre-existing 0.6.24-era archive.

Impact / workaround

cass upgrade --yes --force installs 0.6.25 and leaves the archive unusable with no in-product path back — cass upgrade only moves forward. Recovery required a manually retained copy of the previous binary. Anyone upgrading without one loses search until they re-download 0.6.24 from Releases.

Workaround: reinstall the 0.6.24 binary (the DB needs no repair), and set skipped_version in ~/.local/share/coding-agent-search/update_state.json to avoid the TUI re-prompting.

Worth noting: doctor check sets needs_rebuild: true and risk_level: high on an archive that is provably intact. Acting on that recommendation would trigger a reconstruct of a 9.4 GB data dir to fix a problem that is entirely in the binary. Related in spirit to #374 and #396.

Environment

• cass 0.6.24 (working) vs 0.6.25 (failing), official cass-linux-amd64.tar.gz, checksum verified
• Ubuntu 26.04 LTS, kernel 7.0.0-29-generic, x86_64
• ext4, rw,relatime,errors=remount-ro,commit=30, 205 GB free
• Data dir 9.44 GB total; canonical DB 1.63 GB; WAL 32 B; lexical index 387 MB; raw mirror 6.07 GB
• Archive state at time of failure: lexical stale-but-searchable, semantic backfill in progress
• This archive has pre-existing FTS5 %_data shadow damage (long-standing, benign — search runs on tantivy). It does not prevent 0.6.24 from opening the DB.

[ericziko]

Expanding on the last bullet of the report, since "that archive is just corrupt" is the obvious way to dismiss this. It is not the explanation, and here is the measurement rather than the assertion.

The archive has a pre-existing, derived-index flaw: the canonical FTS5 shadow (fts_messages, contentless — content='', porter) has malformed %_data segments, previously surfaced as fts5: corrupt %_data record: segment leaf term offset exceeds u16 and filed as frankensqlite#328.

Probed read-only against a byte copy of the same DB, with stock sqlite3 3.46.1:

Probe	Result
SELECT count(*) FROM fts_messages_docsize	249,890
SELECT count(*) FROM fts_messages_data	246
SELECT max(length(block)) FROM fts_messages_data	57,625
MATCH 'the'	1,397
MATCH 'agent'	3,405
MATCH 'error'	115
MATCH 'claude'	0
MATCH 'tailscale'	0

Zero hits for claude across ~250k messages of Claude Code sessions is not a stale index — whole regions of the term dictionary are unreachable. (Largest segment block at 57,625 bytes sits just under the 65,535 u16 ceiling, which is consistent with the #328 overflow hypothesis.)

None of that is what search uses. cass queries the Tantivy lexical index (search_start backend="tantivy"). Same term, same moment, two indexes:

• FTS5 shadow, MATCH 'tailscale' → 0
• cass search "tailscale" → 345 hits

So on 0.6.24 this archive is fully functional: db=available, search returns correct and current results, am-style parity intact. The FTS5 shadow is a derived artifact nothing on the read path consults, and cass index rebuilds Tantivy without touching it.

The point for this issue: a broken derived index cannot explain a refusal to open the file. 0.6.24 opens this exact DB — with that FTS5 damage present and unchanged — on every attempt. 0.6.25 refuses to open the same bytes. The delta is the binary.

One caveat so nobody over-reads doctor output here: on 0.6.24 cass doctor check --json returns status: healthy with storage_state: unchecked, because the deep probe is skipped — frankensqlite_full_page_integrity_probe_deferred: archive bundle is 1756598304 bytes, above the bounded doctor limit of 268435456 bytes. Doctor neither confirms nor denies the FTS5 state at this archive size; the numbers above come from direct probing, not from doctor.

[ericziko]

Re-verified today on Linux, and with one addition that affects how this should be prioritised: the obvious workaround does not exist.

Still reproduces on 0.6.25

Tested against a copy of the 0.6.24-created archive (never the live one), with XDG_DATA_HOME isolated so nothing touched the real install:

$ XDG_DATA_HOME=/data/tmp/iso ./cass-0.6.25 --db /data/tmp/copy/archive.db status --json
{
  "healthy": false,
  "status": "degraded",
  "database": {
    "exists": true,
    "open_error": "Failed to open state-meta database at …/archive.db:
       readonly storage open failed (opening frankensqlite db readonly at …/archive.db);
       raw readonly open failed (opening raw frankensqlite db readonly at …/archive.db)"
  }
}

The same file opens normally under 0.6.24.

"Just rebuild from scratch" is not available

The natural response to "this binary can't open your old archive" is to build a new one. On this host that also fails, deterministically: 0.6.25 index --full against an empty, isolated, single-writer data dir aborts with exit 7 inside 30 seconds on a snapshot conflict — reproduced twice, details in #401. A 0.6.24 control over the same corpus and same isolation ingested 1,338 conversations in 120s with zero conflicts.

So on this host 0.6.25 has no working path: it cannot open an existing archive, and it cannot create a usable new one.

Context on the risk framing

This host had pinned 0.6.24 partly because cass was the only surviving copy of a large share of its conversations, which made needs_rebuild: true a potential data-loss event. That is no longer true here — the underlying transcripts have since been restored from backups, and a from-disk rebuild was verified to reproduce the full corpus (1,373 conversations) using 0.6.24.

Worth stating because it separates the two concerns: the data-loss risk was ours and is now resolved; the binary regression is upstream and remains. The pin stays purely because 0.6.25 does not work here, not because a rebuild would be dangerous.

Environment

• Linux 7.0.0-29-generic x86_64
• 0.6.25 from cass-linux-amd64.tar.gz (sha256 verified); 0.6.24 installed from release tarball
• Archive: 1,373 conversations / 270,632 messages, 1.7 GB

---

Filed by an AI coding agent (Claude) working on the reporter's infrastructure; all commands and outputs above were executed on the host as shown.

[Dicklesworthstone]

Status: confirmed and tracked as a 0.6.25 regression of the engine's new sidecar-less read-only first-contact open (fsqlite GH#140, part of the 0.3.1 pin) — cass's own error taxonomy already attributes fsqlite.open_read_failure to the engine dependency. Being triaged on the frankensqlite side in parallel; cass will also grow a sidecar-open fallback so a readonly-first failure degrades instead of hard-failing. Staying on 0.6.24 on that host is the right call for now.

[Dicklesworthstone]

This is an unusually well-controlled report — alternating binaries against a byte-identical DB with the mtime pinned before and after is exactly the right experiment, and 4/4 vs 2/2 is not ambiguous. Thank you.

It does not reproduce here, which is informative rather than dismissive. On Linux x86_64, cass 0.6.25 (the same release, which pins frankensqlite =0.3.1), against a 9.6 GB / ~442k-message archive last written by an earlier version:

$ cass health
✗ Unhealthy (19455ms)
  - index stale
Readiness:
  Search usable now: yes

db opens fine, search is usable, no fsqlite.open_read_failure. So 0.6.25 does not universally break readonly-first opens on Linux — something about the state of your specific archive is the trigger, not the version alone.

Working hypothesis. frankensqlite has unreleased work (f32ce2aa6) adding a one-time, idempotent first-open repair pass aimed specifically at upgraders, described as:

Databases created by a version predating the issue-#70 recovery work may carry latent corruption (e.g. the 'Page N: never used' orphan-page class) that the old code kept writing over.

That shape fits your symptom well: the older engine tolerated (and kept overwriting) a latent condition, and the newer engine refuses the image outright. It would explain why the DB is "healthy" under 0.6.24 and unopenable under 0.6.25 while being byte-identical — the bytes didn't change, the strictness did. It is a hypothesis, not a diagnosis; I can't confirm it without your archive's structure.

The one datum that would settle it. Against the untouched DB, with stock SQLite (not cass):

sqlite3 /path/to/agent_search.db 'PRAGMA integrity_check;'

• If that reports ok, my hypothesis is wrong and this is a genuine open-path regression to hunt directly.
• If it reports Page N: never used (or similar orphan-page output), that confirms the latent-corruption class, and the fix is the upgrader repair pass above — which I should note is not in any tagged frankensqlite release yet, so I won't pretend an upgrade fixes you today.

Related: #390 tracks the "page N is never used" reporting class specifically.

Also useful if you have it: the last cass version that wrote to this archive (not just the last that read it). The repair pass keys off which engine generation created the image.

Keeping this open. Your 0.6.24 binary is a legitimate workaround in the meantime — and per your own evidence it is not mutating the archive, so you are not accruing damage by staying there.

[Dicklesworthstone]

Status: still engine-rooted. I swept fsqlite v0.3.1..v0.3.5 (0.3.5 published yesterday) for readonly-open/sidecar fixes in this class — nothing relevant is in any tagged release, so bumping cass's pin doesn't resolve it yet. The candidate fix is upstream's unreleased one-time first-open repair pass for archives written by pre-recovery-fix engines (frankensqlite f32ce2aa6), which matches the state-dependence here (a comparable 9.6 GB 0.6.24-written Linux archive does NOT reproduce, so this is latent-damage-dependent, not universal). The cass-side mitigation — a sidecar-open fallback that degrades instead of hard-failing every readonly-first surface — remains planned. The PRAGMA integrity_check output requested above would still help confirm the latent-damage hypothesis.

[Dicklesworthstone]

Update with a better candidate than the one I offered before, and a request that may be more useful than the one I made.

Retracting my earlier hypothesis' priority. I suggested this was latent "'Page N: never used' orphan-page" corruption that the newer engine refuses where the older one tolerated it, and asked you for stock PRAGMA integrity_check output. That is still worth having, but I no longer think it is the most likely explanation — partly because the integrity-checker defect behind that theory (#390) turned out to be a false positive in FrankenSQLite's own checker, fixed upstream, which weakens the corruption reading considerably.

The better candidate: Dicklesworthstone/frankensqlite#366. It is open, and its signature is strikingly close to yours:

	your #402	frankensqlite#366
symptom	fresh readonly open fails, unable to open database file	fresh open_file fails, unable to open database file
canonical sqlite3 on same file	opens fine	opens fine
a working path exists	0.6.24 binary opens it	already-open connections keep serving
DB mutated?	no — byte-identical, mtime pinned	no — external DELETEs only

Their trigger is DELETEs that grow the freelist of a database, after which any new connection fails to open it while existing ones are unaffected. That fits an archive like yours better than corruption does: a long-lived cass archive accumulates deletions (quarantine, compaction, refresh churn), so a substantially grown freelist is ordinary rather than exceptional — and it explains why the file is structurally fine to every other reader.

Why this matters for getting it fixed: the upstream investigation is currently repro-blocked — the tracking note says it is stuck waiting on an external reconstruct fixture. You have something they do not: a deterministic reproduction on an untouched file, 4/4 failing on one binary and 2/2 succeeding on another, with the mtime pinned before and after. That is a better fixture than the one they are waiting for.

The datum I would now ask for, which is cheap and does not require sharing the archive:

sqlite3 "file:/path/to/agent_search.db?mode=ro&immutable=1" \
  "PRAGMA freelist_count; PRAGMA page_count; PRAGMA page_size;"

If freelist_count is a large fraction of page_count, that is strong support for #366 being your issue, and it would unblock their investigation at the same time. The stock integrity_check I asked for earlier is still useful as the discriminator against the corruption reading — running both together settles which of the two it is.

Your 0.6.24 pin remains the correct workaround, and by your own evidence it is not mutating the archive, so nothing is accruing damage while this is sorted out.

[Dicklesworthstone]

Update: the fix candidate for your signature has now shipped end-to-end.

FrankenSQLite 0.3.8 landed the frankensqlite#366 fix — a coherent, populated database reopened through the ReservedEmpty path is now opened instead of being falsely rejected — and cass v0.6.26 (released 2026-08-23) pins fsqlite =0.3.8, so it's the first cass release carrying it. Your case was the strongest external match for that bug: fresh opens fail, canonical sqlite3 opens the same file fine, an existing path keeps working, file unmutated.

Could you try v0.6.26 against the same untouched 0.6.24 archive?

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.sh | bash
cass --version   # expect: cass 0.6.26 (aa2023301a02 2026-08-23)
cass status --json

If the readonly-first open now succeeds, that confirms the #366 attribution and this can close. If it still fails on 0.3.8, that's an important negative — it would mean your deterministic fixture reproduces something adjacent that the upstream fix didn't cover, and the freelist_count/page_count numbers from your earlier reply become the next discriminator.