Session projection cache: one non-JSON unit state stops title caching for every session

[kkutysllb]

Session projection cache: one non-JSON unit state currently stops title caching for every session

TL;DR — SessionProjectionCache.put() serializes the whole checkpoint through a single snapshotJsonValue(rows) pass, so one unit whose state violates the plain-JSON contract (e.g. a third-party plugin's contextTimeline initial state containing undefined fields) makes the entire record unwritable. The write path is fail-soft (flushSoft logs and keeps the cache stale), so the failure is silent: every session's cache row stops updating, and after an environment restart the sidebar history shows each session's workspace title (cwd basename) instead of its task title — the title only appears after clicking the session, when the host's live registry snapshot supplies it.

I prepared a small fix and would like to contribute it back. Since pull requests are currently disabled on this repository, I'm posting it here per the CONTRIBUTING guide.

Root cause chain

1. A third-party plugin (dsh-context 0.12.x) registers contextTimeline/contextHeaders projection units. Its createTimelineState() returns an initial state containing undefined fields (model, provider, lastModel, contextWindow, pendingShadowedSeqs).
2. SessionProjectionCache.put() passes the whole checkpoint record to snapshotJsonValue() once; a unit state containing undefined violates the plain-JSON contract → TypeError: projection checkpoint is not losslessly JSON-serializable → the record cannot be cached.
3. put() is wrapped by fail-soft flushSoft/putSoft, so the failure is silent — the projection cache file simply stops updating. All sessions created after that point have no cached row.
4. On cold start (environment restart), session.list's cold path reads projections from the cache; with no row there is no title projection, so the client falls back to the workspace title (cwd basename). Attaching the session (clicking it) reads the live registry snapshot, and the title appears — matching the reported "title only shows after I click it" behavior.

Proposed fix

put() serializes per unit instead of per record:

• Each (key → row) passes snapshotJsonValue independently.
• A row that fails is dropped with a warning (session projection cache: unit "<key>" state for "<id>" violates the plain-JSON contract; persisting without it); the remaining rows still land.
• A dropped key reads as not-yet-available and refolds from the log on the next fuller read — the same degradation a lost write already costs, now bounded to the broken unit instead of evicting the whole session's cache (titles etc. persist).
• When every unit fails the pass, the previous record is kept rather than replaced with an empty one.

The fail-loud contract (throw on any non-JSON unit) was deliberately changed: it never actually failed loud in production (both flushSoft and putSoft wrap put), and its blast radius — one third-party bug erasing title caching for every session — outweighed its diagnostic value, which the per-unit warning preserves.

Verification

• Cache suite: 20 tests pass, 100% coverage on the package (two new cases: a bad unit's row is dropped while a good unit's value still lands and is served by cachedSnapshot; a checkpoint where every unit fails keeps the previous record).
• Session group: 919 tests pass; host/client: 718 tests pass.
• doc-sync: all 28 gates pass (doc-typecheck, translation pairing, etc.).
• End-to-end probe reproduced the original failure (dsh-context mounted: put threw, cold cachedSnapshot empty) and confirmed the fix (write succeeds, title survives in the cold snapshot, contextTimeline isolated out), including the full host session.list cold path serving the title.

Where to find it

• Branch: fix/session-projection-cache-per-unit-isolation on my fork — https://github.com/kkutysllb/deepseek-harness/tree/fix/session-projection-cache-per-unit-isolation
• Commit: 5bef8cf — fix(session): isolate non-JSON projection units instead of failing the record
• Patch: generated from that commit, ready to apply with git am

Happy to rebase, adjust, or walk through anything. Thanks for considering it!

[zoahdev]

对照当前 main HEAD 99f6f02（2026-08-17）核验，你的根因链完全成立：

• packages/session/session-projection-cache/src/index.ts:266-271 — put() 对整条 checkpoint record 走一次 snapshotJsonValue(rows)（第 267 行），任一 unit 的 state 违反 plain-JSON 契约就会 throw；
• flushSoft（246 行）/ putSoft（275 行）确实包裹了 put，fail-soft 吞掉错误，缓存静默停更；
• session.list 冷路径读缓存回填标题，缓存空则退回 workspace title——与你描述的"点击后才出现标题"一致。

一个补充观察：put() 的 fail-loud 契约在 flushSoft/putSoft 双层包裹下实际上从不对外暴露，所以它的"诊断价值"是纸面的——你说的"它从未真正 fail loud"我可以从代码路径确认：flushSoft 捕获并只 log，putSoft 同理（try/catch 后 await this.put 直接抛）。per-unit 隔离 + 单 key 警告的方案既保留了可诊断性，又不会让一个第三方插件拖垮全部会话的标题缓存，方向正确。

另外你的补丁提到的"全部 unit 都失败时保留旧记录"这点很关键——建议在缓存套件里同时断言"旧记录不被空记录覆盖"的持久化层面（不只是 cachedSnapshot 返回值），防止将来有人在序列化层加默认值导致覆盖。20 tests + 100% coverage + 918 组测试跑绿，采纳风险很低，值得合并。