Session search fails entirely when any session contains a released subagent/descriptor v2 event (two v0→v1 migration gates + no per-session tolerance)

[lumla]

Bug report — session search fails entirely when any session contains a released subagent/descriptor v2 event. (Issues are disabled on this repo, so filing here.)

Environment

• dsh 0.1.5-rc.2 (checkout dsh-v0.1.5-rc.2-139-gc291e7961a), macOS
• session-persistence-jsonl backend + persistent session-query-sqlite index (openAt: startup)

Symptom

session_search / session_event_search fail with the model-safe message session history storage is unavailable (code SESSION_QUERY_PERSISTENCE_FAILED), while session_trace / session_event_trace work on the same session. The Web sidebar search degrades to "content search unavailable, showing name matches" — same cause. persisted_sessions stays at 0 rows, because indexing requires a successful cold read.

Root cause — two independent gates

1. packages/session/session-format-v0-to-v1/src/validation.ts (L198):

if (event.type === 'subagent/descriptor' && data['version'] !== 3) {
  ...
  if (version === 0) throw new SessionFormatUnsupportedMigrationError(
    `${event.type} ${event.seq} uses unsupported descriptor version ${descriptorVersion}`)

2. packages/session/session-format-v0-to-v1/src/payload-validation.ts (L956, subagentDescriptorValue):

literalValue(data['version'], [3], `${label} version`)

Relaxing only gate 1 surfaces gate 2's error (version must be one of 3).

A real v2 event carries {version:2, mode:"continuable", provider:"spawn", label, agentProvider, agentModel} — required ['mode','version','provider'] plus optional keys all drawn from RELEASED_V0_EVENT_DISPOSITIONS['subagent/descriptor']. So the payload validates correctly once admitted; the remaining field checks are version-independent.

Amplifier (the more consequential defect)

packages/session-query/session-query/src/corpus.ts inspectPersisted (~L272-293) only special-cases SessionPersistenceCorruptionError and rethrows everything else as SESSION_QUERY_PERSISTENCE_FAILED. There is no per-session skip or partial-result path, and session-query-sqlite's _observeStable behaves the same way. Net effect: one unreadable artifact fails the whole search. In our workspace, 34 of 323 sessions (10.5%) were unreadable due to this single format issue, and that cost 100% of search.

Cold-read sweep evidence (323 sessions): 289 readable / 34 failing, all with signature SessionFormatUnsupportedError: subagent/descriptor {seq} uses unsupported descriptor version 2 (23x seq 6, 10x seq 0, 1x seq 50393).

Questions

1. Is descriptor v2 meant to be migratable? If yes, would you accept admitting released descriptor versions whose key set is a subset of the current released inventory (or an explicit version→inventory mapping), instead of hard-failing in the v0 path?
2. For the query layer: should an unreadable session degrade to "skipped/not searchable" rather than failing the entire search? That seems like the higher-value fix — partial data should still be searchable.

Local workaround we are running (for reference, not a patch submission)

Accepting v2 in both gates (2 files, +13/-2): the previously failing session cold-reads with all 157 events and header intact, descriptor data preserved verbatim (version: 2 intact — the source v0 artifact remains unchanged contract holds, originals are not rewritten); full sweep becomes 323/323 readable, 0 failures; session-format-v0-to-v1 + session-query suites pass 443/443. Happy to open a PR if a maintainer prefers that over a local downstream patch.

[PerryLink]

Verified against the checkout: both descriptor gates exist exactly as reported
(validation.ts:198-206, payload-validation.ts:956), and the descriptor-version admission gate is
the same root cause covered in #6559 (item ② there) — that thread now carries a verified repair
recipe and a read-only scanner, so please follow it for the migration fix. The query-layer
question (one unreadable session failing all search instead of degrading to "skipped") is the
same per-session-tolerance issue tracked alongside #6564; thanks for the 34/323 cold-read sweep
data.

[483218131]

Corroborating your amplifier from a different population, plus one thing I don't see reported in this thread or in #6559 / #6614 — why the cause has been so hard to see.

Environment: Windows 11 / Node v22.22.2, dsh 0.1.5-rc.1 with core packages 0.1.5-rc.2, upgraded from 0.1.1-rc.2. Corpus: 372 format-v0 artifacts (session.jsonl.zstd, header version: 0).

1. Same two gates, same amplifier, different corpus

Before repair, my refusals fell into four classes (counts are sessions; one session can hit more than one, so they do not sum): unregistered source.kind 22, known kind carrying a whitelist-extra member 20, subagent/descriptor version: 2 231, unknown event type with ignorable: true 17.

Descriptor v2 is by far the largest class on my machine too (231 of 372), which matches your 34/323 — so this is not an edge case, and it is the class where a relaxed admission gate buys the most. Your second gate (payload-validation.ts L956, subagentDescriptorValue) reproduced exactly as you described: admitting v2 at gate 1 only surfaces gate 2, and the payload then validates because the field checks are version-independent.

2. Not reported yet: the Web banner throws the error object away

Every reporter in this cluster had to re-derive the cause from disk, because the UI cannot show it. In dsh-client-ui-workspace/lib/client.js, the search-failure path is a .catch((error) => { ... }) whose body never reads error — it only sets state to "error", and the panel then renders the constant t("search.unavailable") ("Content search is temporarily unavailable. Showing name matches."). No cause, no code, no console line.

I only obtained SessionQueryError: session-search persistence observation failed: cannot safely transform unclassified message source ... after patching the client to stash error on window and console.error it. Your point from #6614 — that a plugin's ctx.logger.warn reaches neither stdout nor stderr in a stock dsh web run — makes this worse on the server side too: the fail-soft path that would announce a refused log may itself be writing nowhere.

Worth noting the asymmetry: session_trace / session_event_trace still work on the same session (as you found), so the failure is confined to the query/index path — but from the UI, that difference is invisible.

Ask: could the banner (or at least the console) carry a short reason and code? That alone would turn this class from archaeology into a one-line bug report, and it is independent of the migration decision.

3. On your ask 2 — a working containment patch is small

In session-query-sqlite/lib/index.js, wrapping the per-session cold read (const loaded = await readColdSessionLog(...)) in try/catch, warning with the session id, and continue-ing the sweep keeps search usable with the unreadable session simply absent from the index. That is the shape we run locally, and it is a few lines.

The upstream trade-off is exactly the one #6614 raised in the other direction: a loud refusal is visible, a silent skip is not. If this is made fail-soft, it probably wants a counter or a surfaced warning — otherwise "one bad log costs 100% of search" becomes "some sessions are quietly missing from search", which is harder to notice and to report.

Cross-reference: I added the unregistered-source.kind half of the census (two third-party plugins inventing their own kind, with the write sites) to #6559, since that thread already carries the migration-gate inventory.