[Bug] session search fails on any store that ever spawned a subagent — v0→v1 migration rejects subagent/descriptor version 2, the only version the writer emits

[kittimzhe]

TL;DR

Every session-search call on this machine fails with SESSION_QUERY_PERSISTENCE_FAILED. The persistence observer feeds each stored v0 session through the v0→v1 migration, and dsh-session-format-v0-to-v1 throws on any subagent/descriptor event whose data.version !== 3. The problem: every real subagent/descriptor event I can find — 27 sessions spanning 2026-08-23 → 2026-09-26, including sessions created under the current 0.1.5-rc.3 — carries version: 2. None carries 3. So every session that ever spawned a subagent is unindexable, and one such session fails all searches, not just its own.

Environment

DSH	0.1.5-rc.3 (npx install)
OS	macOS (Apple Silicon), Node v25.9.0
Store	~/.dsh/sessions/<workspace>/<session-id>/session.jsonl.zstd
Entry	session-query full-text search (the recall tool surface)

The failure

session search failed (SESSION_QUERY_PERSISTENCE_FAILED):
session-search persistence observation failed:
subagent/descriptor 6 uses unsupported descriptor version 2;
source v0 artifact remains unchanged
(raw log: ~/.dsh/sessions/<workspace>/006dc8ff-…/session.jsonl.zstd)

Deterministic; repeats for every query until the offending session leaves the store.

The offending event

From the raw log of the session named in the error (created 2026-08-23):

{"type":"subagent/descriptor","seq":6,"time":1787489897542,"data":{"version":2,"mode":"one-shot","provider":"spawn","label":"扫描Python仓库文档机会"}}

Root cause

dsh-session-format-v0-to-v1, inside assertReleasedEventPayload (the payload gate for the frozen v0 event inventory):

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

Two observations:

1. The accepted version (3) does not match what the writer emits (2). I scanned every session on this machine: 27 contain subagent/descriptor events; all 27 carry version: 2; zero carry 3. The newest was created 2026-09-26 00:13 by the currently installed 0.1.5-rc.3. Unless some writer out there emits 3, this gate rejects 100% of real-world subagent sessions.
2. The same guard is lenient on the v1 side. When the artifact generation is v1, a non-3 descriptor version just returns — the event passes through unvalidated. Only the v0 arm throws. That asymmetry inside one function suggests the hard failure is an oversight rather than a deliberate policy; at minimum the two arms should agree.

Downstream, dsh-session-query wraps the observer failure as SESSION_QUERY_PERSISTENCE_FAILED and the whole call aborts. The message correctly notes the source artifact is left unchanged — but there is no per-session isolation: one unobservable session takes down every query against the store.

Blast radius

• Any deployment that ever spawned a subagent and then searched hits this. Quarantining affected sessions is not a workaround — here it would mean excluding the entire subagent history (27 sessions, i.e. most of the valuable work).
• The loss is total, not partial: search dies over all sessions, including perfectly migratable ones.

Fix directions

Either layer restores search here; both are worth having:

1. Migrator: teach the v0 arm about descriptor version 2 (map to the v3 shape if it is a superset, or treat unknown descriptor versions as opaque the way the v1 arm already does). The asymmetry makes this look like a one-arm bug fix, not a policy change.
2. Observer / session-query: isolate per-session failures — a session that fails observation should be quarantined (logged, skipped, reported) while the rest of the store stays searchable. One bad artifact should not be a global outage for the search feature. This is the same "no recovery seam" shape as the v1→v2 migration family in Session unloadable: v1→v2 migration rejects `assistant/message` 4060703 — declared 874 source refs vs 873 reconstructed (range starts on a `session/end-seed`) #7824 — and sharper, because the record here is not even damaged: it is a legitimate historical format the migrator was never taught.

Auditing your own store

find ~/.dsh/sessions -name session.jsonl.zstd -print0 |
  while IFS= read -r -d '' f; do
    zstd -dc "$f" 2>/dev/null | grep -q '"type":"subagent/descriptor".*"version":2' && echo "affected: $f"
  done

A single affected session is enough to fail all searches in that store on 0.1.5-rc.3.

---

Verified against the 0.1.5-rc.3 runtime; happy to re-check against master if this gate has moved. I can prepare a fork patch with regression tests (a v0 artifact with a v2 descriptor migrates cleanly; the observer quarantines an unparseable session without failing the query) if the direction sounds right — the analysis stands on its own either way.

[xiaoshenming]

Root cause confirmed, and I can add two measured things.

The gate is identical in 0.1.5-rc.3 and 0.1.7-rc.2. From the published tarballs of dsh-session-format-v0-to-v1: literalValue(data["version"], [3], …) at lib/index.js:1290, if (event.type === "subagent/descriptor" && data["version"] !== 3) at :1584, throw at :1586 — the same lines in both versions. So this is not something 0.1.5 introduced: the writer has been emitting a shape the released v0 inventory never accepted.

The offline fix exists today, and I measured it against that same gate. session-surgeon normalizes subagent/descriptor data.version 2 → 3. The two shapes carry the same members (mode / provider / label) and nothing else is touched — the action log reads "set … data.version to 3 on 1 event(s)". On the real v0→v1 payload gate, constructed sample:

before: SessionFormatUnsupportedMigrationError: subagent/descriptor 0 uses unsupported descriptor version 2
after : accepted

On the blast radius — agreed, and it is worth naming: because the persistence observer feeds every stored v0 session through the gate, one offending artifact fails every query (SESSION_QUERY_PERSISTENCE_FAILED), not just its own. The offline stand-in for the per-artifact report mode is to enumerate the store before the observer trips:

dsh plugin --profile web add "github:xiaoshenming/dsh-session-surgeon#main"

node bin/dsh-session-surgeon.mjs index                  # read-only: per-session health code for the whole store
node bin/dsh-session-surgeon.mjs inspect <id>           # the exact seqs + which rule refuses
node bin/dsh-session-surgeon.mjs repair <id>            # dry-run plan, writes nothing
node bin/dsh-session-surgeon.mjs repair <id> --apply    # writes .bak.<utc> first

index lists each session with its refusal code (v0-descriptor-version for this arm), so you can find every session that will refuse in one pass instead of bisecting the store. Nothing is invented and no event is deleted — this repair only rewrites a literal the released inventory already fixed at 3.

We have not touched your files; every measurement above is on constructed samples.

[kittimzhe]

Verified against freshly packed tarballs of both versions — exact match: literalValue(data["version"], [3], …) and the !== 3 throw are line-for-line identical in 0.1.5-rc.3 and 0.1.7-rc.2 (lib/index.js:1290/:1584/:1586). Your measurement holds, and it sharpens the picture:

This is a day-one contract gap, not a regression. The released inventory has only ever accepted descriptor version 3, while the writer has only ever emitted 2 — on my machine, 27/27 sessions back to 2026-08-23 carry version: 2 and none carry 3. So every store that ever spawned a subagent has always been one observer run away from SESSION_QUERY_PERSISTENCE_FAILED, which also means the severity argument gets stronger, not weaker: nothing "drifted"; the two sides never agreed.

On the two remediation paths, I'd order them:

• Upstream migrator fix first in principle: a v0 gate that rejects the only shape the writer has ever emitted isn't guarding history — it's guarding a spec that never shipped. Accepting 2 alongside 3 (same members, as you measured) fixes every store without touching any user file. The observer-quarantine half then covers unknown-future shapes.
• Your offline normalization is the right relief for today, and the index → inspect → repair --apply flow with health codes per session is exactly the per-artifact report mode this family keeps converging on (Session unloadable: v1→v2 migration rejects `assistant/message` 4060703 — declared 874 source refs vs 873 reconstructed (range starts on a `session/end-seed`) #7824 proposed the same shape for the relationship arm). One residual note for the record: rewrites claim version 3 the writer never emitted; harmless today since members match, but it's a reason the migrator fix should still land even with the repair path available.

Third path for affected users, no file edits at all: dsh-session-recall v0.7.5 (npm) ships a degraded mode — when the index outage fires, recall falls back to a direct raw-log scan of the store (streaming zstd headers, term prefilter, wall-clock budget, honest partial-coverage reporting). Search comes back without repairing anything, which is useful while deciding whether to normalize history. Config: rawScanFallback defaults on; nothing to enable.

Same conclusion on blast radius, from the other side: with the plugin bypassing the index and your surgeon enumerating it offline, the remaining gap is exactly the upstream gate — the one fix that helps every user without asking them to install or repair anything.

[xiaoshenming]

One measurement that bears on which fix upstream should ship — because "accept 2" and "normalize 2 to 3" are not equivalent, and the rest of the chain already has an opinion.

Downstream already believes versions 1, 2 and 3 are valid. In dsh-session-format-v3-to-v4, the only place that interprets a descriptor is the child-catalog path, and its admission test is a whitelist:

const known = isSessionFormatJsonObject(descriptor) && [1, 2, 3].includes(descriptor["version"]);
if (count !== 1 || !known) return void 0;
if (descriptor["version"] !== 1 && descriptor["mode"] !== "continuable" && descriptor["mode"] !== "one-shot") throw …

Version 1 even gets a special case (mode: descriptor["version"] === 1 ? "continuable" : descriptor["mode"]). So the later stages were written for a vocabulary that includes 2 — the v0 payload gate's !== 3 is the outlier, not the writer.

The intervening stages never look at descriptors at all. dsh-session-format-v1-to-v2 and dsh-session-format-v2-to-v3 contain no occurrence of subagent/descriptor; they pass the event through untouched. So a version-2 descriptor accepted at the v0 gate would reach v3→v4 as-is and be treated as known.

And 2 and 3 are indistinguishable there, which is what makes our normalization safe: both take the same branch in the two tests above (only version === 1 is special-cased). Our repair rewrites data.version 2 → 3 and touches nothing else, so the artifact we hand back is byte-equivalent for every downstream consumer to what relaxing the gate would have produced.

So the two proposals are compatible rather than competing: relaxing the v0 gate is consistent with the rest of the chain, and normalizing to 3 is lossless for the same reason. The one thing that would be wrong is relaxing the gate and passing 2 through to a consumer that assumes the writer's version field means what it says — which is the situation today.

Shipped our side of it in 4a0a156; the descriptor arm stays report-and-normalize, never invent.

[kittimzhe]

All three code claims verified against the published 0.1.7-rc.2 tarballs — the [1, 2, 3] whitelist (v3-to-v4 lib/index.js:905-908), the mode check at :911, and zero occurrences of subagent/descriptor in both v1-to-v2 and v2-to-v3.

And I can now close the loop with real-store data instead of constructed samples: I scanned the actual store that motivated this thread (89 session logs, 26 subagent/descriptor events). Every one is version: 2, and the mode distribution is exactly one-shot (16) and continuable (10) — both inside the :911 vocabulary. So for the data that actually breaks here, the full chain holds end-to-end under either fix: the v0 gate accepting 2, or your 2→3 normalization, land byte-equivalent at every downstream consumer, because every consumer in the shipped chain either ignores descriptors or whitelists 2.

That also sharpens your closing caution into something measurable: within the shipped chain there is no consumer today for which passing raw 2 through is wrong — the "assumes the version field means what it says" consumer is hypothetical. The caution still stands for forward-compat, and the same measurement points at where the next instance of this family would come from: the :911 mode check is another writer-vocabulary coupling one stage later (version 1 skips it entirely; 2 and 3 must be continuable/one-shot). Our writer happens to emit exactly those two values — but a future writer mode would re-create this exact family at v3-to-v4. So whichever fix ships, the mode vocabulary deserves a named home next to the version vocabulary, not a second hard-coded literal.

Compatible-not-competing is the right call, and the store data says both are safe today — the residual risk is entirely in future vocabulary drift, which is the argument for fixing the gate (or normalizing) and naming the vocabularies in one place.

[xiaoshenming]

Thanks for running it against the store that motivated the thread — 26 descriptors, every one version: 2, and both modes inside the :911 vocabulary is the part that decides this for real data rather than for constructed samples.

On the forward-compat point: the boundary you predict is already the boundary of our repair, and we have hit it. v0-descriptor-version rewrites data.version and nothing else, so a descriptor whose mode is outside continuable|one-shot stays refused after our write — our own probe fixture failed with mode must be one of continuable|one-shot before we corrected it, and we report that shape rather than guessing a mode. So a future writer mode re-creating this family at :911 produces a report from us, not a bad write.

One detail on where :911 is reached from, since it bounds how the next instance would show up: the mode test is guarded by descriptor["version"] !== 1, so a version-1 descriptor skips the mode vocabulary entirely. That is the same asymmetry that makes 2 and 3 indistinguishable downstream — and it means the next arrival of this family is a version: 2|3 descriptor carrying an unknown mode, not a version bump.

[kittimzhe]

Agreed on all three points, and the report-don't-guess stance at the mode boundary is the right one.

One concrete addition to "where the next instance would show up", from the same file: the vocabulary asymmetry has a sibling sixteen lines down. The catalog-fact check at :927 accepts continuable | one-shot | unknown (only version === 0 may not be unknown), while the descriptor check at :911 accepts continuable | one-shot only. So "unknown" is already a mode the format's own vocabulary uses — for the child-binding records — but a version: 2|3 descriptor carrying it stays refused, exactly the arrival shape you describe. If the writer ever reuses its existing unknown for descriptors the way it already uses it for catalog facts, that is the most likely first instance of the next family member: same file, same kind of vocabulary gap, one record type apart.

That also makes your framing measurable: when the next one lands, the refusal will name subagent descriptor mode with a version: 2|3 and a mode of unknown — and the offline index health code for it should be distinguishable from v0-descriptor-version today, so the report mode can stay honest about which vocabulary tripped.