dsh-session-recall 0.7.3 → 0.7.5

package/README.md

@@ -125,8 +125,22 @@ Plugin row config (all optional):
     cjkHint: true           # explain CJK zero-hit results
     cjkFallback: true       # CJK zero-hit → exact substring scan over session text
     cjkFallbackScanMax: 50  # max sessions scanned per cross-session fallback (1..500)
+    rawScanFallback: true     # degraded mode: when the index itself fails, scan logs directly
+    rawScanMaxSessions: 200   # degraded scan budget: sessions visited (1..2000)
+    rawScanMaxDurationMs: 20000  # degraded scan wall-clock ceiling (1000..120000)
+    rawScanMaxSessionBytes: 8388608  # per-log compressed-size cap in the degraded scan
 ```
 
+## Degraded mode (v0.7.5)
+
+When the session index itself fails — most notably `SESSION_QUERY_PERSISTENCE_FAILED`, where a single un-migratable session artifact fails *every* indexed search (the v0→v1 migration gate rejecting `subagent/descriptor` version 2, [deepseek-harness discussion #7995](https://github.com/deepseek-ai/deepseek-harness/discussions/7995)) — the `recall` tool degrades to scanning the persisted session logs directly (`$DSH_HOME/sessions`) instead of failing the call:
+
+- **Tolerant by construction**: each log is decompressed with a bundled pure-JS zstd decoder and parsed line by line; a corrupt line or unreadable log is skipped and counted, never fatal. The exact session shape that bricks the upstream migration is searchable here.
+- **Affordable**: session headers are read through a streaming decompressor (milliseconds each) so cwd/time/session_id scope filters run before any full decompression; a byte-level term prefilter avoids line parsing for non-matching logs; a wall-clock budget (default 20s) and a per-log size cap (default 8 MiB compressed — pure-JS zstd decompresses ~2 MB/s) keep the tool responsive. Sessions are visited newest-first, and when the budget trips, the result says which portion of the store was covered.
+- **Honest**: results carry `diagnostics.source: "raw-scan"` and a hint explaining the degraded provenance, unreadable/oversized skips, and partial coverage. Live (not yet persisted) sessions are not included.
+
+Disable with `rawScanFallback: false` to restore the pre-v0.7.5 fail-fast behavior.
+
 ## Failure behavior
 
 Every failure returns a friendly `hint` instead of a raw exception: a disabled index explains the two config keys needed, a stale cursor tells the model to restart without one, an unknown `session_id` suggests discovering sessions first. Title enrichment is best-effort — a failed title batch degrades to untitled rows, never a failed search.
@@ -184,6 +198,16 @@ npm test            # vitest run
 npm run bundle      # tsdown → lib/
 ```
 
+## Session toolchain
+
+This plugin is one of three layers over the same trusted `ctx.sessionQuery` seam:
+
+| Plugin | Layer | Answers |
+|---|---|---|
+| [`dsh-session-export`](https://www.npmjs.com/package/dsh-session-export) | Evidence | "What exactly happened in this session?" |
+| `dsh-session-recall` | Memory | "What did I do before, and where is it?" |
+| [`dsh-session-eval`](https://www.npmjs.com/package/dsh-session-eval) | Measurement | "Was that session good? Is the trend improving?" |
+
 ## License
 
 [MIT](https://github.com/kittimzhe/dsh-session-recall/blob/main/LICENSE)

package/README.zh.md

@@ -124,8 +124,22 @@ dsh plugin --profile web add github:kittimzhe/dsh-session-recall
     cjkHint: true           # CJK 零命中的提示开关
     cjkFallback: true       # CJK 零命中 → 对会话文本做精确子串扫描
     cjkFallbackScanMax: 50  # 跨会话回退时最多扫描的会话数（1..500）
+    rawScanFallback: true        # 降级模式：索引整体故障时直扫会话日志
+    rawScanMaxSessions: 200      # 降级扫描预算：访问会话数（1..2000）
+    rawScanMaxDurationMs: 20000  # 降级扫描墙钟上限（1000..120000）
+    rawScanMaxSessionBytes: 8388608  # 降级扫描单日志压缩体积上限（字节）
 ```
 
+## 降级模式（v0.7.5）
+
+当会话索引本身故障——最典型的是 `SESSION_QUERY_PERSISTENCE_FAILED`：一个无法迁移的会话工件让**所有**索引查询全部失败（v0→v1 迁移闸门拒绝 `subagent/descriptor` version 2，见 [deepseek-harness 讨论 #7995](https://github.com/deepseek-ai/deepseek-harness/discussions/7995)）——`recall` 工具降级为直接扫描持久化会话日志（`$DSH_HOME/sessions`），而不是让整个调用失败：
+
+- **天生容错**：日志用内置的纯 JS zstd 解码器解压、逐行解析；坏行或不可读日志跳过并计数，绝不致命。上游迁移器认不了的那个会话形状，在这里照样可搜。
+- **算得起**：会话 header 走流式解压（毫秒级），cwd/时间/session_id 过滤先于任何全量解压；字节级关键词预过滤让不含关键词的日志免去逐行解析；墙钟预算（默认 20 秒）与单日志体积上限（默认压缩后 8 MiB——纯 JS zstd 解压约 2 MB/s）保证工具响应性。会话按最新优先访问，预算用尽时结果会说明覆盖了哪部分。
+- **诚实**：结果带 `diagnostics.source: "raw-scan"` 和降级来源提示（不可读/超限跳过数、部分覆盖说明）。未落盘的活跃会话不包含在内。
+
+设 `rawScanFallback: false` 可恢复 v0.7.5 之前的快速失败行为。
+
 ## 失败行为
 
 所有失败都返回友好的 `hint` 而不是裸异常：索引未开启会说明需要哪两个配置键；游标失效会告诉模型不带游标重开一次；`session_id` 不存在会建议先做跨会话搜索。标题补全是尽力而为——标题批量读取失败只降级为"无标题"行，绝不让搜索失败。