Renaming a workspace folder makes its stored sessions fail the identity check, with no supported repair

[bolide737]

Packages: @deepseek-ai/dsh-session-persistence-jsonl (projectKey, assertStoredIdentity), @deepseek-ai/dsh-app-boot
Platform: all (the invariant is platform-independent)
Verified on: 0.1.5-rc.2, Windows 11 (10.0.26100)

Summary

Session logs are stored under a folder whose name is a pure function of the session header's own cwd:

<home>/sessions/<projectKey(cwd)>/<encodeSegment(id)>/session.v<N>.jsonl.zstd

projectKey (dsh-session-persistence-jsonl/lib/index.js:874-892) maps separators (/, \, :) to
-, keeps [A-Za-z0-9._-] literal, escapes everything else as ~XXXX, and wraps the result in
--…--. So a session recorded in D:\工作文件 lives in --D-~5DE5~4F5C~6587~4EF6--.

Renaming that folder — a legitimate, unremarkable user action — breaks the pairing for every
session ever recorded under it, and the store rejects those logs:

// dsh-session-persistence-jsonl/lib/index.js:3217-3227
/** Reject metadata that does not identify the selected physical log. */
async assertStoredIdentity(path, storedVersion, meta, expectedId, signal) {
    signal?.throwIfAborted();
    if (expectedId !== void 0 && meta.id !== expectedId) throw new Error(`corrupt session log "${path}": requested id "${expectedId}" does not match header id "${meta.id}"`);
    let expectedPath;
    try {
        expectedPath = generationLogPath(this.root, meta.cwd, meta.id, storedVersion, this.compression);
    } catch (error) {
        throw new Error(`corrupt session log "${path}": header id cannot name a storage path`, { cause: error });
    }
    if (path !== expectedPath && !await this.sameFile(path, expectedPath, signal)) throw new Error(`corrupt session log "${path}": header id "${meta.id}" and cwd identify "${expectedPath}"`);
    signal?.throwIfAborted();
}

The expected path is recomputed from the header's cwd, so once the folder moves, the physical
path and the header disagree and the log is reported as corrupt. There is no documented way to
rewrite a stored header, so the only repair available to us was to rewrite the compressed frame
directly.

The obvious repair is the wrong one

This is worth calling out because it is what a competent operator tries first, and it makes things
worse rather than better.

If you rename the bucket folder to match the new workspace path (--D-workspace--) but leave the
headers naming the old path, the two now disagree — whereas before the rename they agreed, and the
sessions merely sat in a bucket whose path no longer existed. Renaming the folder alone converts a
self-consistent-but-stale state into exactly the state the assertion above rejects.

The folder rename and the header rewrite have to happen together. Nothing in the product says so.

Steps to reproduce

1. Start the harness in a workspace, creating at least one session.
2. Stop it, rename the workspace folder.
3. Start it again and open the previous sessions.

Expected: history is still available (perhaps with a re-key).
Actual: the stored logs no longer satisfy assertStoredIdentity; the header's cwd names a path that
no longer exists.

Observed impact

On one machine, 25 sessions were affected at once. The workspace rename also produced a second,
louder failure (a link: dependency junction left dangling, so the harness refused to start), and
while diagnosing the two we had to repair all 25 logs by hand. The repair required:

• decompressing each log,
• rewriting header.cwd,
• recompressing only the header frame and copying the event frames byte for byte,
• keeping a per-file backup.

That is a reasonable amount of work for a user to be forced into by renaming a directory.

Why a byte-safe repair is possible

session.v<N>.jsonl.zstd on this version is a two-frame zstd stream: frame 1 is exactly the
header line, frame 2 holds every event row. That means a repair can recompress frame 1 and copy the
rest verbatim, and can prove afterwards that frame 2 is unchanged. Any repair API or documented
procedure should use that property rather than re-encoding the whole stream.

Suggested improvements (any one of these would have prevented the incident)

1. A supported repair/migration command. Something like
   dsh session repair --cwd <new-path> that rewrites the headers of every log whose folder no
   longer matches, using the frame-level technique above. The product knows the invariant; it is
   better placed to repair it than a user.
2. Tolerate and re-key on load. When the header cwd no longer exists but the log is otherwise
   intact, migrate it (move the folder and rewrite the header) instead of reporting it corrupt.
   sameFile already exists in the same function, so path-drift is evidently an anticipated
   condition.
3. Document the invariant. If neither of the above is wanted, the storage rule
   ("the folder name is derived from the header's cwd, and the two are asserted to agree; do not
   rename the bucket on its own") should be stated where a user can find it — because the natural
   fix is the destructive one.

Limitations of this report

• The assertion and projectKey are cited from the installed 0.1.5-rc.2 sources; the mismatch state
  was reproduced and measured directly (25 logs), but I did not separately measure the behaviour of
  session enumeration as opposed to session reading — the rejection is proven for the read path
  shown above.
• The repair tool used here is local; it is described rather than submitted.

Addendum: what a fix for this must verify (a note on verification)

This is offered because the failure mode above is unusually easy to reproduce in the repair tool
itself, and a repair that is not verified against the right predicate will look successful while
making the state worse.

During this incident the rename tool did exactly that. It moved the bucket folder to the new key,
counted the entries in it, saw 25 of 25, and reported the session history as preserved. It had in
fact created the very disagreement assertStoredIdentity rejects — the folder rename is only half of
the repair, and the half it performed is the destructive half. Nothing in the tool's output was
false about its own actions; the false part was the conclusion.

The generalisable rule:

A migration's success condition must be stated in terms of the consumer still working, not in
terms of the migration's own steps having run. "The steps completed" and "the goal was reached"
are different propositions, and a tool that reports the first as the second will hide its own
defects rather than surface them.

Two consequences that apply directly to this component:

1. Verify content, not containers. Counting entries in a bucket folder proves the folder exists
   and holds something. It says nothing about whether those entries satisfy the invariant. The check
   that would have caught this is cheap and exact:

   for every session log:  projectKey(header.cwd) == name of the containing folder
   

   — the same predicate assertStoredIdentity applies at read time. Any repair tool (or any built-in
   migration, if one is added) should assert this for every affected log, and refuse to report success
   otherwise.

2. A verifier is code, and needs the same scrutiny as the thing it verifies. The first version of
   our verification script died on malformed JSON instead of reporting a failure, and separately
   reported a sandbox permission error as a real defect — both of which would have turned a broken
   repair into a green light. A verification step that has not itself been exercised against a
   deliberately broken fixture is not evidence.

For this specific issue, a fix should therefore ship with at least one test that starts from a
mismatched fixture (folder re-keyed, header still stale) and asserts that the repair either
restores agreement or fails loudly — rather than a test that only covers the already-consistent case.

[bolide737]

Provenance, which I should have stated up front.

This report was drafted by an AI coding agent running on my machine, during the session in which we diagnosed and fixed the problem locally. The source citations come from reading the installed 0.1.5-rc.2 sources, and the measurements from running the checks described; the Limitations section states what was and was not measured.

I reviewed it and stand behind the technical content, but please weigh it knowing how it was produced. The repair tool described is local and has been reviewed by nobody other than the agent and me.