[Bug] One unmigratable v0 artifact (subagent/descriptor v2) disables all content search

[christianschmidt]

Disclosure
This report was written by a DSH agent session with the operator.

Environment

• @deepseek-ai/dsh 0.1.5-rc.2,
• harness commit c291e7961a (2026-09-10)
• Node v26.8.1, macOS, profile web with session-query-sqlite configured as openAt: first-search plus a durable path (the shipped default is openAt: never, which keeps this failure dormant).
• Session store: append-only JSONL with zstd under ~/.dsh/sessions.

Summary
Enabling content search (session-query-sqlite, openAt: first-search) fails for the whole session store: every search returns SESSION_QUERY_PERSISTENCE_FAILED and the derived index stays empty. A single format-generation-0 artifact containing a subagent/descriptor event with version: 2 is enough to cause this. The frozen v0 to v1 migration refuses that combination, and the search observation turns one unreadable entry into a failure of the entire corpus.

Two findings, separable:

1. Data. A subagent/descriptor with version 2 inside a v0 artifact is DSH's own output: the writer stamped version 2 until 2026-08-24, and the migration that refuses it was added on 2026-09-01. The payload satisfies every version 3 validation rule and differs only in the version stamp.
2. Consumer. The corpus observation has no per-artifact containment, so one unreadable artifact disables full-text session search completely. The UI then reports only "Content search is temporarily unavailable. Showing name matches."

The migration policy itself is not what this report challenges; the section below lists what we understand to be intentional. What we are asking for is (a) a decision or documentation for this specific combination and (b) per-artifact containment plus a cause that reaches the user.

No existing report
We searched the discussion archive for these error strings and behaviours (SESSION_QUERY_PERSISTENCE_FAILED, unsupported descriptor version, session-search persistence observation failed, content search, session-query, openAt, format migration, descriptor version) and found no duplicate. The closest threads, #496 and #501, describe unrelated causes of unreadable session history.

What we understand is by design, and are not asking to change

• Refusing rather than guessing. The frozen migration refuses payload shapes it does not know instead of interpreting them speculatively, because a wrong guess could silently gut a session.
• Reads never mutate the source. For an artifact older than the reader: "every event-body operation first runs the complete adjacent chain in memory and leaves the source path, bytes, and inode unchanged. ... a write open exclusively publishes the final current generation under its canonical versioned filename before append" (.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md:17). Migration is therefore lazy and write-triggered, and there is no upgrade-time pass over the store.
• Header-only listing. Listing reads and validates only the header frame, so a session can be listed while its body is unreadable.
• Old generations are retained and are explicitly not an automatic fallback or a downgrade compatibility promise.
• Consequence accepted: an artifact that no chain can reach stays unreadable. We are not arguing that every historical artifact must always be readable.

We also did not modify any artifact; see Workaround.

Environment

• harness commit c291e7961a (2026-09-10), @deepseek-ai/dsh 0.1.5-rc.2
• Node v26.8.1, macOS
• profile web; session-query-sqlite configured with openAt: first-search and a durable path. The shipped default is openAt: never, which keeps this failure dormant and is a plausible reason it went unnoticed.
• session store: append-only JSONL with zstd under ~/.dsh/sessions

Reproduction

1. Have one format-generation-0 artifact (session.jsonl.zstd, header "version":0) containing a subagent/descriptor event with data.version: 2. Minimal shape:

   {"type":"session","version":0,"id":"<id>","createdAt":0,"cwd":"/tmp"}
   {"type":"subagent/descriptor","seq":0,"time":0,"data":{"version":2,"mode":"continuable","provider":"spawn","label":"x","agentProvider":"p","agentModel":"m"}}

   The descriptor is not necessarily among the first events. In our store it sits at seq 0 in some artifacts and at seq 5 in others, so a scan that only inspects the first lines finds a subset. See the appendix.

2. Trigger a whole-corpus observation: content search in the Web sidebar, or ctx.sessionQuery.searchSessions({ query: 'x' }).

3. The search fails, and the derived index database is created but stays empty.

Observed

SessionQueryError
  message: session-search persistence observation failed:
           subagent/descriptor 5 uses unsupported descriptor version 2;
           source v0 artifact remains unchanged
           (raw log: <root>/<slug>/<uuid>/session.jsonl.zstd)
  code:    SESSION_QUERY_PERSISTENCE_FAILED

The reconcile commits everything in a single transaction, so the failure lands before the first commit:

derived index after the failed search:
  persisted_sessions 0 | persisted_docs 0 | global_generation 0 | -wal unchanged (schema only)

Retrying cannot make progress. The Web sidebar degrades to "Content search is temporarily unavailable. Showing name matches.", which is title and workspace matching only.

Root cause

A1. The frozen chain has no rule for this combination

packages/session/session-format-v0-to-v1/src/validation.ts:198-202:

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
}

version is the source artifact's format generation. For a v0 artifact the descriptor must therefore already be version 3, so a v0 artifact written by a build that stamped version 2 is permanently unreadable: neither converted nor degradable. For source generations 1 and above the same condition is explicitly tolerated via return, which means this strictness is specific to the v0 chain.

A2. The combination is DSH's own output, written before the chain existed

SUBAGENT_DESCRIPTOR_VERSION was 2 until commit f76a225a7d (2026-08-24, PR #2663 "feat/subagent-provider") raised it to 3:

$ git show f76a225a7d^:packages/subagent/subagent/src/descriptor.ts | grep -n DESCRIPTOR_VERSION
47:export const SUBAGENT_DESCRIPTOR_VERSION = 2
$ grep -n 'SUBAGENT_DESCRIPTOR_VERSION =' packages/subagent/subagent/src/descriptor.ts   # current
48:export const SUBAGENT_DESCRIPTOR_VERSION = 3

The v0 to v1 chain itself was added later, in d1521ea783 (2026-09-01, "feat(session)!: add released format migration"). Artifacts written before both changes were valid when written and are refused today. In our store the affected artifacts were all written between 2026-08-23 and 2026-08-26, that is, inside exactly that window.

This is not a one-off. The format generation stayed at 0 while the descriptor payload version changed from 2 to 3, so v0 artifacts exist with both descriptor versions. A payload shape changed under a stable format generation, and the frozen inventory pinned only the newer shape. The same pattern can produce the same class of unreadable artifact again.

A3. The payloads are field-compatible, so the gap looks convertible

subagentDescriptorValue() (packages/session/session-format-v0-to-v1/src/payload-validation.ts:955-979) requires, for mode: "continuable": version === 3, a non-empty provider, mode === "continuable", a non-empty label, and optional agentProvider / agentModel (which must be paired). The disposition table (dispositions.ts:92) permits exactly:

['mode','version','provider'] + ['label','agentProvider','agentModel','agentReasoningEffort','persona','toolFilter']

Every affected payload we inspected is shape-identical and satisfies all of that with no unknown key:

{"version":2,"mode":"continuable","provider":"spawn","label":"...","agentProvider":"p","agentModel":"..."}

The only difference from an accepted artifact is the value of version. That is the basis for the question in Suggested fixes, not a claim that the refusal is wrong as such.

B1. One artifact fails the whole observation

SqliteSessionQueryEngine._observeStable() (packages/session-query/session-query-sqlite/src/index.ts:495-562) reads the cold logs of all non-live persisted sessions inside one try block. Any throw, including the typed migration refusal for a single artifact, is converted into a store-level error:

if (error instanceof SessionQueryError) throw error
throw new SessionQueryError(
  `session-search persistence observation failed: ${errorMessage(error)}`,
  'SESSION_QUERY_PERSISTENCE_FAILED',
  { cause: error },
)

There is no per-entry containment. The loop aborts at the first unreadable artifact, and because the write phase never starts, the derived index stays empty. Both searchSessions and searchEvents use this path.

B2. The specific cause is flattened before the user sees anything

1. SessionFormatUnsupportedMigrationError (packages/session/session-format/src/error.ts:7), a precise and typed migration error.
2. It is wrapped into a SessionQueryError carrying the store-level code SESSION_QUERY_PERSISTENCE_FAILED, with the message preserved and the cause attached.
3. The host wraps that again into RemoteError('gateway/internal', 'session search failed: ...') (packages/api/session-controller/src/list.ts:259-265).
4. The Web sidebar shows only the generic notice (packages/client/ui-workspace/src/client/rows/WorkspaceBrowser.tsx:815); the artifact path that the message does carry never reaches the UI.

Note that SESSION_QUERY_PERSISTENCE_FAILED is also the code used for genuine store-level conditions such as "persistence observation did not stabilize after one retry", so a single-artifact migration refusal and a store-wide outage are indistinguishable to callers.

B3. Per-artifact containment already exists elsewhere in the product

The subagent control listing defines containment semantics for exactly this kind of data damage (packages/subagent/subagent/src/control-types.ts:66-77): a candidate whose log makes a registered unit's fold throw is reported as reason: 'corrupt', covering "a missing, malformed, or unrecognized-version descriptor, deliberately undistinguished", and that damage is "contained per child". The unavailable member covers an absent or transiently unreadable observation, and the unsupported member is retained in the union but never produced.

Relatedly, the subagent layer's own fold treats an unknown descriptor version as merely unclassifiable rather than fatal: parseSubagentDescriptor() returns undefined when version !== SUBAGENT_DESCRIPTOR_VERSION (packages/subagent/subagent/src/descriptor.ts:210, contract at :306-314, "the child cannot be classified by this runtime"), and the identity projection projects null with "the causes deliberately undistinguished" (projection.ts:165-180).

So the principle that an artifact we cannot interpret yields no row rather than a crash does exist in the codebase. We are not aware of an equivalent on the corpus observation path.

Impact

• Full-text session search is unavailable for the whole store while one such artifact is present. It is deterministic, not transient, not fixable by retrying, and the derived index is never populated.
• The scope is precise rather than general. Other ctx.sessionQuery operations are not affected by the corpus observation: listing, filterSessions and lineage traces work from headers. What fails is any body read of that artifact, because the query service's observation reader uses the same cold read (packages/session-query/session-query/src/observation.ts:14,188-195). We verified that path in code but did not separately reproduce the per-session UI symptom.
• It presents as "search is broken" rather than "one session is broken", because the artifact itself stays visible in the sidebar.
• There is no documented remedy. The migration policy describes refusal behaviour and states that nothing is damaged, but does not say what an operator should do with an artifact that no chain can reach, and the message naming the raw log never reaches the UI.

Workaround

Quarantine the affected session directories out of the persistence root: move them from ~/.dsh/sessions to a directory outside the store, keeping the directory structure. After that the corpus observation succeeds and search works. We deliberately did not rewrite any artifact, and the move is fully reversible.

Suggested fixes

1. (A) Is this combination intentionally unconvertible? If not, the v0 chain could accept a subagent/descriptor with version: 2 by validating the payload with the version 3 rules and stamping version: 3, or by adding an explicit and documented v2 to v3 step. The payload evidence in A3 suggests the conversion is lossless. If the refusal is intentional, a sentence in the migration documentation or the release notes stating that such artifacts are permanently unreadable, together with a concrete remedy, would remove the silent-outage aspect.
2. (B) Contain failures per artifact in the corpus observation. Skip an entry that cannot be read or migrated, emit a typed diagnostic naming the artifact, and keep the rest of the corpus searchable. This mirrors the posture the subagent control listing already takes for data damage it can attribute to one child (B3). At minimum, one unreadable entry should not fail the whole search.
3. (B) Stop flattening the cause. Let the specific migration error, or at least its raw log: location, reach the host error and the UI instead of a generic "Content search is temporarily unavailable", and consider a code that distinguishes "one artifact is unreadable" from "the store is unreachable".
4. (B) Make it observable. A per-artifact skip should be visible somewhere (log line, diagnostic surface, or a notice on the search result) rather than silently reducing the corpus.

Appendix: how to find affected artifacts

The descriptor is not necessarily among the first events, so check every line rather than a head window:

cd ~/.dsh/sessions
find . -name 'session.jsonl.zstd' -print0 | while IFS= read -r -d '' f; do
  # header generation: only v0 artifacts are subject to this strictness
  gen=$(zstd -dc "$f" | head -1 | grep -o '"version":[0-9]*' | head -1 | grep -o '[0-9]*$')
  [ "$gen" = "0" ] || continue
  zstd -dc "$f" | grep '"type":"subagent/descriptor"' | while IFS= read -r line; do
    v=$(printf '%s' "$line" | grep -o '"data":{"version":[0-9]*' | grep -o '[0-9]*$')
    [ "$v" = "3" ] && continue
    echo "descriptor v$v  $f"
  done
done

All artifacts this finds are unmigratable by the current build. In our store they belong to subagent sessions only, which is consistent with the descriptor being the trigger.

Closing note. This is early-stage software, and the artifacts involved are subagent logs from a pre-release period, so this may well be an acceptable edge case, and losing those particular sessions is not something we consider critical. We still think it is worth reporting, for reasons that go beyond this one store. Three of them: the error that reaches the user names no artifact, so the cause is not traceable from the UI; one unreadable entry disables a whole feature instead of degrading, which turns a local data problem into a global outage; and the underlying pattern is not limited to very old versions or early adopters, because a payload shape changed here while the format generation stayed the same. Any migration that freezes its inventory after such a change can produce the same class of artifact again, so containing it per artifact seems more valuable than converting this single case. Happy to re-test either change on a build that carries it.

[christianschmidt]

Follow-up with an empirical result. We converted the version stamp on all affected artifacts (81 of them) and put them back: the only byte changed in each file is the descriptor version, and DSH's own v0 to v1 chain then read every one of them without complaint. All 81 are now in the full-text index, together with the rest of the store, and search works. So the payload really is v3-compatible in practice, not just by the validator rules, and the conversion in suggestion 1 would recover such artifacts losslessly. The containment gap in suggestion 2 is still the part that matters going forward, since a future inventory-tightening can produce the same class again.