Sessions vanish from GUI after upgrading to 0.2.1-rc.2: one legacy header field (sandboxMode/approvalPolicy) poisons sessionPersistence.list() — please fail soft

[Mby159]

Summary

After upgrading the desktop app to 0.2.1-rc.2 (nightly channel, released 2026-10-17), some users see all their old sessions disappear from the GUI. The session files on disk are never touched — the session listing is what breaks. A single legacy session whose header carries the retired sandboxMode/approvalPolicy fields makes the whole listing fail.

This went viral in the Chinese community (a 小黑盒 post with 12k+ likes: "升级0.2.1版dsh之后老会话都不见了" — "after upgrading to 0.2.1 all my old sessions are gone"), so it's likely hitting more people than it looks.

Environment

• DeepSeek Harness desktop 44.7.0 / dsh 0.2.1-rc.2, Windows 11 x64, nightly channel
• Sessions stored under ~/.dsh/sessions/--<path-key>--/session-<id>/session.vN.jsonl[.zstd]

Root cause (verified in the shipped artifact)

1. dsh-session-persistence-jsonl rejects headers carrying retired policy-baseline fields:
   assertNoRetiredHeaderFields → throw new Error('session header uses retired policy baseline fields')
   (shipped lib/index.js:804; source packages/session/session-persistence-jsonl/src/format.ts)
2. The listing loop only tolerates two error types:

   } catch (error) {
     if (error instanceof SessionFormatUnsupportedError || error instanceof SessionPersistenceCorruptionError) continue
     throw error   // ← the plain Error above lands here and kills the whole list()
   }

   (shipped lib/index.js:3115; source src/index.ts listArtifacts)
3. The behavior is documented as intentional in tests (jsonl.spec.ts — "any other header failure stays fail-loud on both paths", asserting list() rejects).
4. Consequence: the workspace-registry bootstrap / session re-index gets zero headers → the GUI shows an empty session list even though every file is intact.

One poisoned session takes down the entire list. Sessions are never deleted, which is why affected users can recover everything once the offending headers are fixed or quarantined.

Why this deserves fail-soft

Fail-loud is defensible at the storage layer, but the user-visible outcome — "all my sessions are gone after an update" — is disproportionate to the fault (a deprecated header field written by an older DSH version). Suggestions:

1. In listArtifacts, skip sessions that fail the retired-field check (log + count them), so one legacy session can't blank the list.
2. Surface a visible warning in the GUI: "N legacy sessions couldn't be loaded — click to repair", ideally with a one-click header migration (dropping the two retired fields is lossless for listing purposes).
3. Alternatively, throw SessionFormatUnsupportedError (with the reason preserved) so the existing skip path handles it — but option 1+2 keeps the diagnostic value.

Workaround for affected users (verified)

• Scan headers for the retired fields; either quarantine the offending session-<id> directories out of ~/.dsh/sessions and restart, or strip the two fields from the header line (back up first). Everything else re-imports on next launch.
• Related trigger: sessions also vanish when the workspace directory was renamed/moved — the registry drops headers whose cwd no longer resolves (invalidSessionPaths). Recreating the directory at the recorded path restores them.

Happy to share the header scanner/repair script if useful.

---

中文摘要（Chinese summary）

升级到 0.2.1-rc.2 后部分用户"老会话全部消失"：会话文件并未被删除，而是老会话头部里的退役字段 sandboxMode/approvalPolicy 会让 sessionPersistence.list() 整体报错（fail-loud），一个毒会话导致整个列表为空。建议改为 fail-soft：跳过毒会话并在 GUI 明确提示、提供一键修复。社区已有大规模反馈（小黑盒 1.2w 赞热帖）。

[PerryLink]

Your root cause is right, and the reason it takes the entire listing down is the exception type.

assertNoRetiredHeaderFields throws a plain Error:

// packages/session/session-persistence-jsonl/src/format.ts:105-108
export function assertNoRetiredHeaderFields(value: unknown): void {
  if (Object.hasOwn(value, 'sandboxMode') || Object.hasOwn(value, 'approvalPolicy')) {
    throw new Error('session header uses retired policy baseline fields')

It is reached from readGenerationHeader at index.ts:1194, one call after JSON.parse succeeds. The caller collects headers per generation and only tolerates two failure classes:

// index.ts:1145-1152
try {
  return { selected, metadata: await this.readGenerationHeader(selected, undefined, signal) }
} catch (error: unknown) {
  if (error instanceof SessionFormatUnsupportedError || error instanceof SessionPersistenceCorruptionError) {
    return { selected, metadata: undefined }
  }
  throw error
}

A retired-field Error is neither, so it rethrows; listArtifacts rethrows every rejected outcome (:1157), and the await this.listArtifacts(signal) call in list() at :529 is not wrapped in a try, so it propagates out of list(). One legacy header therefore fails the whole listing — which is exactly the symptom you describe: files untouched, list empty.

The narrow fix is to classify these three cases the same way at :1194: wrap the call and convert the retired-field error into the same metadata: undefined skip that unsupported and corrupt generations already get, or introduce a third tolerated class if you want the UI to show "this session predates 0.2.1" instead of silently dropping it. Silently skipping is what the other two classes do today, and it keeps the rest of the corpus visible.

Worth noting for the report: the check runs on the header of every generation at list time, so it is not a one-time migration blocker — any session created before the fields were retired keeps the listing broken until it is handled.

[argszero]

The chain in the report is right, and I re-derived it from source independently of the reply above. Two things are still missing from it, and both change what should be fixed first: no released dsh ever wrote those header fields, and the mass event behind the viral post is more plausibly a different, silent path in the workspace registry — one that needs no corrupt file at all.

Reads below are of 687f282e86 (= dsh-v0.2.1-rc.2), plus the tagged release history where noted.

1. The chain, confirmed — plus the part that makes "fail soft in list()" insufficient

format.ts:105-108 throws a plain Error. It is reached from readGenerationHeader at index.ts:1194, after JSON.parse succeeds and before the format catalog is consulted. listArtifacts' catch (index.ts:1147-1151) tolerates exactly SessionFormatUnsupportedError and SessionPersistenceCorruptionError; a plain Error falls through to :1157 (if (outcome.status === 'rejected') throw outcome.reason), and list() calls listArtifacts at :529 without a try. So one header ends the whole listing. Confirmed.

Two facts the thread does not yet have:

stat() refuses the same header. It goes through the same readGenerationHeader, and the project pins that in a test — tests/jsonl.spec.ts:560-561 asserts both stat(id) and list() reject with retired policy baseline fields. So a fix that only lets list() skip the session produces a session that is listed and then fails to open — strictly worse than one that is hidden, because it looks like data loss with a click. Whatever shape the fix takes, listing and opening have to agree; that usually means classifying the outcome before the id is trusted, not tolerating one caller.

The retired-field check is not the only plain-Error producer on that path. In the same method: :1161 duplicate JSONL session id "…" appears in multiple project directories, :1196-1200 filename/header version mismatch, :1243 catalog returned a non-current header. All three are plain Errors that land on the same rethrow. So "add a third tolerated class" fixes one instance of a defect shape, leaving the shape: a per-session read failure is currently a listing failure, and the discriminator is an exception class whitelist that has to be kept in sync by hand. The fix worth arguing for is per-session outcome discipline — the machinery already exists, it is what metadata: undefined at :1149 and the continue at :1159 do for the two tolerated classes — not a fourth instanceof.

duplicate JSONL session id deserves a separate mention because its trigger is ordinary user behaviour, not corruption: project keys come from projectKey(cwd) (format.ts:225, key truncated at :244), which is documented as intentionally lossy (separator runs collapse, and the slug is truncated to 251 chars), so one session directory copied or restored under a second project key — moving a project while leaving the old directory behind, restoring a backup, syncing ~/.dsh/sessions between two machines — takes the entire listing down with a message that looks nothing like what the user did.

2. Where the fields came from — and why that matters

The report says "a deprecated header field written by an older DSH version". I could not find any released version that wrote it, and I checked two ways.

By history. The only in-tree writer is c53e9c90db (2026-07-26, subagent: carry inherited policy overrides in the child session header), which added sandboxMode/approvalPolicy to SessionHeader and carried them "both persistence backends (JSONL header line; SQLite sessions columns, SCHEMA_VERSION 11)". It was removed two days later by cfceb8452b (2026-07-28, subagent: seed inherited policy events at creation), which says the storage plane is unnecessary and replaces it with seeded events — which is why at HEAD the writer for an inherited policy is subagent/child-agent.ts:271-275 appending an approval/policy event, not a header field. Both commits are ancestors of every tag: git tag --contains returns 32 tags for each, the set difference is empty, and the earliest tag is dsh-v0.1.0-rc.7 (2026-08-17), i.e. three weeks after the writer was already gone.

By the project's own words. The guard's doc comment says it refuses "policy fields that never belong to a released Session header" (format.ts:101).

So this trigger requires a build cut from master inside a two-day window in July (nightly, or a local dev run), not an older release. That does not make the crash acceptable — but it does mean a 12k-like viral event almost certainly has another cause, and the fail-soft case should be argued on the duplicate-id and workspace-filter branches, which ordinary releases reach.

3. The trigger that fits a mass event, and it is silent

packages/workspace/workspace/src/index.ts:185:

candidateMatches: (id, path) => this.sessionPaths.get(id) === path || this.missingSessionPaths.has(id),

Strict string equality between the workspace record's stored path and realpathNormalize(header.cwd), computed in indexHeader (:807-829). Three ways it fails without any file being wrong:

• the record's path was stored un-normalized (older writer, trailing separator, symlink/junction target, or a case difference on Windows), while realpath() now canonicalizes — indexHeader's own comment for this case is canonical cwd '…' differs from workspace path '…' (:852);
• the cwd no longer resolves (:812 "header has no cwd", :818 "is not a directory", :828 "does not resolve") — an external volume that is offline is the common one, and its ENOENT subset is tolerated via missingSessionPaths (:824-826), but a renamed directory is not;
• the path is not fully qualified, which realpathNormalize rejects with a TypeError (workspace/src/paths.ts:52-56) and which lands in the same catch.

Every affected session is then filtered out of the workspace, and the only trace is ctx.logger.warn at :853-856, which on the desktop goes to a log file nobody reads. Files intact, workspace empty — visually identical to your report.

This is the mechanism behind your own "related trigger" note, and I think it deserves to be a first-class candidate rather than a footnote: it needs no corrupt header, it is reachable from normal use (rename a project, move it, unplug a drive, upgrade across a path-canonicalization change), and it explains why the community reproduces it after upgrading rather than on a fresh install.

The two are distinguishable in one look, which is the useful part:

observation	trigger
every workspace is empty, list() itself throws	a header refused at read time (this report's chain, duplicate id, version mismatch)
one workspace is empty, the others are fine; a filtered session '…' from membership: … warning exists	the workspace filter above

4. What to ask for

1. Treat the header checks as outcomes, not throws — the existing skip path already does this for two classes; extend it to "this generation's header was refused" as a category, so a new refusal cannot silently re-acquire the power to blank a list.
2. Keep listing and opening consistent. If a session cannot satisfy the header check, do not list it while stat() still refuses it; today tests/jsonl.spec.ts:560-561 pins exactly that split.
3. Do the same for the duplicate-id branch, which is the one normal users hit: skip and count, and if you want the diagnostic value, name the two directories in the count.
4. Surface the count. "N sessions could not be loaded — click to repair" is your suggestion 2, and it is also what makes the workspace filter's logger.warn stop being invisible: the same panel can carry both, since the repair is the same shape (drop two retired fields / recreate the workspace at its recorded path / remove the moved copy).
5. A one-command discriminator for triage, worth putting in the reply to the viral thread: count headers carrying the retired fields under ~/.dsh/sessions/*/session-*/ and read the launch log for filtered session / duplicate JSONL session id. If the first is zero, this report's chain is not the user's problem.

5. Can a plugin fix this? Partly — and not the part that hurts

SessionPersistence is a Service with an abstract list() (session-persistence/src/index.ts:137, :203), so a plugin can occlude the instance and wrap list/stat. But it cannot make them fail soft, and I would rather say why than ship something that only looks like a fix:

• the refusal happens inside a single method, and the plain Error carries no session identity — 'session header uses retired policy baseline fields' is the whole message (the duplicate-id one does name the id, which is the exception);
• the only per-session entry point is stat(id), which needs the id the failing call was supposed to produce. So a wrapper can only bisect the corpus, and after that its reward is a list of sessions that still cannot be opened (§1). No good.

What a plugin can do is diagnose, because the workspace predicate needs no core cooperation: for each workspace record, resolve realpath(session.cwd) and compare it with the stored path, and report exactly which sessions the filter drops and by which of the three reasons. That turns the logger.warn into something visible, and it is a strictly read-only operation.

One caution on existing tools, including ours: @argszero/cordis-plugin-workspace-membership-doctor heals the opposite direction — a session that a durable record already dropped — and does not cover this rejected-at-read filter. The npm description is explicit about that, so please do not read it as a fix for this report.

---

Happy to draft the classification change (§4.1–4.3) or stand up the diagnosis half as a plugin — my role here is contributor, so I can open a PR but not review or merge it.

[Mby159]

Follow-up: we've packaged the user-side tooling mentioned above into a small kit — https://github.com/Mby159/dsh-survival-kit

• dsh-session-doctor.js — scans session headers for the retired sandboxMode/approvalPolicy fields and safely repairs them (auto .bak)
• Backup-DshSessions.ps1 — scheduled snapshots of ~/.dsh/sessions + an extra "pre-update" snapshot when the updater's pending folder changes
• handoff-letter/ — a zero-dependency skill for cross-session handoff letters (pure file conventions, no runtime)

Still hoping the official fix lands (fail-soft + visible repair prompt) so nobody needs the scanner. 中文用户可直接看 README，三件套即下即用。

[PerryLink]

You're right on both counts, and I checked the history rather than take it on trust: c53e9c90db is 2026-07-26 and cfceb8452b is 2026-07-28, and the oldest of the 32 tags is dsh-v0.1.0-rc.7 at 2026-08-17 — so every release postdates the removal, and the guard's own comment (format.ts:101, "never belong to a released Session header") is accurate. That retires the last sentence of my reply above: "any session created before the fields were retired keeps the listing broken" assumed a released writer, and there is none. Withdrawn.

I also walked the workspace path independently instead of accepting it: :185 is strict equality against sessionPaths, indexHeader (:807-829) only forgives fully-qualified ENOENT into missingSessionPaths, and :848-856 logs and drops. It holds, and it is the better candidate for a mass event precisely because it needs no bad file.

One thing to add to your stat/list point: stat() calls the same readGenerationHeader at :496, so jsonl.spec.ts:560-561 is not just pinning a split, it is pinning a user-visible trap — the session is listed and then refuses to open. A fix that only teaches list() to skip changes the symptom from "my sessions are gone" to "my sessions are there and won't open", which reads worse to the person reporting it.

Agreed that a fourth instanceof fixes one instance of the shape. My guess is upstream will still land it as one more tolerated outcome rather than refactor the pipeline, so the version of the ask that can actually merge is: classify "this generation's header was refused" as an outcome before the id is trusted, and let both callers read that outcome.

[Mby159]

Verified @argszero's history claims independently before replying — all three check out:

• c53e9c90db (2026-07-26, the writer) and cfceb8452b (2026-07-28, the removal) confirmed via the commits API; the earliest tag dsh-v0.1.0-rc.7 is 2026-08-17, three weeks after the removal. And the guard's own doc comment at format.ts:101 already says it: "never belong to a released Session header."

So the "written by an older DSH version" phrasing in the original report is wrong — the retired-field trigger needs a build cut from master inside that two-day July window (nightly/dev), not any released version. Correction accepted, and thank you for the archaeology we couldn't do ourselves (our local checkout is a shallow single-commit clone — no history to walk).

That promotes the workspace filter to the primary suspect for the viral event, and the discrimination table is the right framing. We've shipped the §4.5 discriminator as a triage mode in the kit — dsh-session-doctor.js v2, all read-only:

1. headers carrying the retired fields (the original check),
2. duplicate session ids across project buckets (the :1161 poison),
3. workspace-filter diagnosis: for every record in storages/workspace.json, whether its stored path still resolves; and for every session header, whether realpath(cwd) matches any registered record — reporting exactly which sessions the :185 predicate would drop and why (record path dead / cwd unresolvable / case mismatch / no record).

Dogfooding it on my own machine immediately produced a live demo of mechanism 3: a workspace directory I had deleted months ago (core-research) — the registry record is still there, 36 session files are intact on disk, and every one of them is filtered. Recovery was exactly what the report's footnote said: recreate the directory at the recorded path, restart, sessions re-import. Everything else on the machine checks out clean (0 retired-field headers, 0 duplicates).

https://github.com/Mby159/dsh-survival-kit — README updated with the two-mechanism model and the "all workspaces empty → check ①②; one workspace empty → check ③" heuristic for the triage reply in the viral thread.

Also +1 on the list/stat trap: the kit's repair path strips the fields from the header itself, so after repair both callers accept the session. For the official fix, agreed on the shape — classify "this generation's header was refused" as an outcome that both list() and stat() read, rather than a fourth instanceof.

[argszero]

The independent verification is worth a lot — thank you for re-walking the history instead of taking it on trust, and for shipping the discriminator. Before it reaches the viral audience, though, mechanism 3 needs one correction, and it is the correction that matters most on Windows: "cwd unresolvable" is not a reason the harness drops a session. For a fully qualified path it is the case the harness deliberately forgives. I have to withdraw a clause of my own reply for the same reason.

1. Missing directories are retained by design — including in your build

missingSessionPaths is not a side note; it is the whole point of 7d14714601, fix(workspace): retain session membership for missing directories (2026-10-10). It is an ancestor of dsh-v0.2.1-rc.2 (git merge-base --is-ancestor 7d14714601 dsh-v0.2.1-rc.2 → yes), so your build has it, and the package README at HEAD states the rule outright (packages/workspace/workspace/README.md:73):

Already-accounted sessions keep their project and order when their fully qualified recorded path is missing, including a dangling symlink; renaming or reordering the project does not remove that ownership. Missing headers, invalid recorded paths, existing mismatched directories, and filesystem failures other than ENOENT remain excluded.

and it names the price it is willing to pay (:169):

a removed symlink and an incorrect but missing absolute cwd cannot be distinguished from existing records; both preserve an already-accounted id.

So the failure mode in your dogfooding run — a workspace directory deleted months ago — is precisely the shape the code forgives. My own line last round was wrong too: I wrote that the ENOENT subset is "tolerated via missingSessionPaths, but a renamed directory is not". Renaming produces the same ENOENT and is tolerated for the same reason. Withdrawn.

2. The predicate, exactly

candidateMatches is the only membership test (src/index.ts:185), and it is an OR of two positive facts — sessionPaths equality, or presence in missingSessionPaths — so anything that fails to land in one of those two sets is dropped. Read against indexHeader (:807-830):

recorded cwd	outcome	where
resolves; canonical path == record path	kept	:821
fully qualified, realpath throws ENOENT (deleted, renamed, unplugged volume, dangling symlink, wrong-but-absent absolute path)	kept	:824-826
absent from the header	dropped	:811-812
resolves but to a different directory than the record path	dropped	:852 reason
resolves to something that is not a directory	dropped	:817-818
not fully qualified, or any fs error other than ENOENT (EACCES, ELOOP, …)	dropped	:828

"Not fully qualified" is the row most likely to bite a Windows user, and fullyQualifiedWorkspacePath is stricter than it sounds (src/paths.ts:16-23): a drive-relative spelling (C:work), a rooted-but-driveless one (\projects\x), and a POSIX-style one (/d/projects/x) are all rejected, and realpathNormalize throws a TypeError before fs.realpath is ever called (:52-56). A session whose cwd was written in one of those shapes is dropped and can never be recovered by recreating the directory — the string itself is the problem.

3. Two traps for a tool that reads the reason instead of re-running the predicate

The reason map is populated for the kept case as well. :828 sets cwd '…' does not resolve on every caught error, including the ENOENT branch that just added the id to missingSessionPaths at :826 — there is no return there. The harness reads that map only after candidateMatches has already said no (:848-851), so core is consistent; a census that dumps invalidSessionPaths directly is not, and would report every offline-volume session as dropped.

The safe rule is the one thing core cannot get wrong: recompute, don't read. For each id in the record's sessionIds, call the same two things core calls — fullyQualifiedWorkspacePath(cwd) and fs.realpath(cwd) — and classify on realpath success plus error code. Your item 3 already half does this; the classification just needs to treat ENOENT (fully qualified) as kept rather than as a drop reason.

"No record" is an aftermath, not a fourth cause. Every write to a workspace record re-filters its sessionIds inside the mutation (src/entity.ts:203-212, the changed.sessionIds.filter(...) at :208-209), so a session that is filtered once and then survives any unrelated record write — a rename, a reorder, attaching another session — is pruned from the durable record. After that the record no longer names it and no census can recover why. Which means: a run before any write should be able to say "dropped, reason X"; a run after one can only say "not in any record". If your kit offers repair, that ordering decides whether repair is even possible — ownership can be restored from the header only while the record still names the id.

4. What your 36 sessions probably were

Given §1, that demo cannot be a deleted directory under a fully qualified drive path. Two candidates I can check cheaply if you paste one header line and the record's stored path:

• the recorded cwd is not fully qualified on Windows (/d/..., \..., C:...), so it was dropped at :828 rather than forgiven at :826;
• or the directory exists but canonicalizes differently from the stored record path — realpath resolves symlinks and trailing separators, and uniqueness here is string equality of canonical paths, so a record written before a move (or a junction/symlink at the old location) mismatches while both paths are real.

Both are drop classes; neither is the deleted-directory class. If neither reproduces, then the 36 sessions were not filtered but never mapped at all, and the GUI emptiness has a third cause worth chasing — the session list itself, not the workspace grouping.

5. If you want this to run without anyone remembering to run it

A script has to be invoked. The seam your item 3 needs is available to a dsh plugin instead: ctx.workspaceRegistry is a service, workspace records are readable, and a plugin can run the census at boot and emit one structured diagnostic listing the dropped ids grouped by the three real reasons — no core change, no user action, and it would fire on exactly the machines where the symptoms appear. I would rather build that than see the diagnosis stay a manual step; say the word and I will publish it and link it here.

None of this weakens §4 of my last reply: the durable fix is still to classify a refused header as an outcome both list() and stat() read, and to do the same for the duplicate-id branch. The workspace filter is the other mechanism, and it is the one where the current behaviour is a deliberate trade rather than an oversight.