dsh-engram 0.3.4 → 0.3.6

package/README.md

@@ -2,6 +2,8 @@
 
 > **[English](README.md) · [中文](README.zh.md)**
 
+[![CI](https://github.com/skepsun/dsh-engram/actions/workflows/ci.yml/badge.svg)](https://github.com/skepsun/dsh-engram/actions/workflows/ci.yml)
+
 Minimalist long-term memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), distilled from the
 [symbolic-index](https://github.com/skepsun/symbolic-index) and [pi-esr](https://github.com/skepsun/pi-esr) ideas —
 with one goal: **save tokens**.
@@ -11,6 +13,16 @@ with one goal: **save tokens**.
   key files, repeated errors), plus an explicit `engram_store`. Nothing on the hot
   path calls a model, and pure plumbing — `git push` / `git stash` / silent
   commits — is deliberately never recorded (see *Auto-capture policy* below).
+  Every write is run through a deterministic **secret redactor** first — API
+  keys, JWTs, `Bearer` tokens, private keys, AWS/Stripe/Slack/GitHub tokens and
+  `key=value` secret shapes are replaced with `<REDACTED:…>` markers before the
+  dedup hash, the char cap, and storage, so sensitive text can never land on
+  disk. Failing **test runs** are recognized by pure patterns (`npm test`,
+  `node --test`, vitest/pytest/jest, failure lines) and captured as
+  `tags:["error","test"]` entries with a raised signal. DSH **goal-domain
+  integration**: a completed or blocked goal (`goal/change` session event)
+  auto-sediments as a `handoff`/`error` memory (`tag:goal`), so the outcome of
+  a goal survives its session (see the `GET /api/dsh-engram/goals` read surface).
 - **Symbolic index + progressive disclosure** — a compact `[ENGRAM]` block (default
   budget 700 chars ≈ 175 tokens; one line per memory) is injected at prompt
   assembly and **frozen per session**, keeping the request prefix byte-stable for
@@ -23,7 +35,36 @@ with one goal: **save tokens**.
   (repeat-failure revival: recency + hit climb toward promoteHits so the
   failure resurfaces instead of piling up), and on zero local hits falls back
   to DSH's own cross-session full-text index (`ctx.sessionQuery`, filtered by
-  cwd) instead of building a parallel SQLite index.
+  cwd) instead of building a parallel SQLite index; when the FTS fallback also
+  comes back empty and the query contains **CJK** characters (Chinese FTS5
+  tokenization), recall runs a bounded substring scan over the newest session
+  logs (zstd-decompressed, LRU-cached) and appends matched past sessions —
+  deterministic `# past sessions` lines, capped files and bytes.
+- **Session-start auto-recall (`autoRecallOnStart`, default on)** — the pull-only
+  design had a gap proven in real use: recall tools relied on model initiative,
+  and in practice the model almost never calls `engram_recall` on its own (19
+  real sessions, thousands of tool calls, ~5 recall calls total). So at the FIRST
+  assembly of a new session the host runs one deterministic BM25 recall keyed on
+  the session's first user message and injects the top ≤ `autoRecallLimit` hits
+  as a `[RECALL]` block (default 700-char budget, "few and precise" — agentmemory
+  candidate ①). Relevant memory is in context even without a single recall call.
+  Pure rule, zero LLM, pure read (never bumps `hits`); superseded stale truth does
+  not occupy an injection slot (still fetchable via `engram_detail`); frozen per
+  session together with `[ENGRAM]` for prefix stability.
+- **Memory-to-memory semantics** — `engram_store` accepts optional
+  `supersedes` / `contradicts` memory ids (validated against the same
+  workspace). A superseded ("stale truth") memory is demoted to the tail of
+  recall and **excluded from the `[ENGRAM]` block**, while the superseding
+  statement keeps the line; a contradicted memory stays ranked but is flagged
+  `· contradicted by <id>`. Old rows are never deleted — re-fetchable, just
+  honestly ranked. Opt-in `autoSupersede` config (default **off**) auto-marks
+  entity-anchored replacement updates ("改用 / no longer / switched…") as
+  superseding their matching older row; explicit `supersedes` always wins.
+- **Failure→fix closure (zero LLM)** — error memories carry a `cmd:` signature
+  tag; when that same command later succeeds, engram auto-sediments a
+  `procedure` memory (`fixed: <cmd> — N earlier failing runs now succeed`),
+  tags the earlier error rows `resolved` (never re-ranking them), and recall
+  then surfaces the fix instead of the stale failure.
 - **ESR-lite closure protocol** — `esr_task` / `esr_close` / `esr_link` give tasks
   a `draft → active → stable` lifecycle where `stable` requires real evidence
   (`artifact` / `evaluation` / `memory_ref`), surfacing closure gaps instead of
@@ -56,6 +97,18 @@ with one goal: **save tokens**.
   The `tools/result` recorder feeds the actionables' data sources; P4
   conversion metering stays (`#suggest-*` tags + 10-minute attribution +
   `GET /api/dsh-engram/triggerstats`). Pure rules, zero LLM.
+- **Session-end todo auto-sink (draft safety net, `autoSinkTodosOnEnd` default
+  on)** — during a session the native todo stays cheap, per-session working
+  memory that dies with the session. But when a session closes at its teardown
+  edge (`session/disposed`) while its plan still has pending todos, they are
+  **auto-landed as ESR `draft` tasks** (name = the todo text, description
+  marked 「源自会话计划」, deduped against existing task names, capped by
+  `maxTasksPerWorkspace`), so the plan never silently evaporates. Sinking to
+  **draft** — not active — keeps them out of the `[ESR]` active rows and creates
+  no evidence obligation; an explicit `esr_claim` / `esr_task` step is still
+  what promotes a draft to active. The "nothing auto-written during the
+  session" trade-off is unchanged; only the end-of-session data-loss gap is
+  closed. Disable via profile patch or the settings card.
 - **Memory GC (pi-esr constraints)** — a scheduled, mechanical, archive-only
   sweep: TTL-expired memories are archived, over-cap workspaces evict the
   lowest-value entries, stable tasks past their retention window leave the
@@ -86,14 +139,105 @@ LLM-distillation and vector/graph niches are already crowded. dsh-engram fills t
 three gaps that matter for token discipline:
 
 1. **No model in the write path** — capture is deterministic pattern matching.
-2. **No raw text in the prompt** — a bounded symbolic index is injected, retrieval
-   stays on demand ("retrieved ≠ injected").
+2. **No raw text in the prompt** — a bounded symbolic index is injected, plus the
+   top ≤ N memories auto-recalled for the session's first message (within budget);
+   deeper retrieval stays on demand ("retrieved ≠ full-text injected").
 3. **Honest task closure** — STABLE cannot be declared without evidence.
 
 DSH already provides cross-session FTS (`ctx.sessionQuery`), storage
 (`ctx.storageDomain`), prompt-injection hooks and settings slots; dsh-engram is a
 thin composition layer over them, not a re-implementation.
 
+## Security model
+
+The DSH plugin ecosystem is young and unvetted — there is no official directory,
+no signature check, and the harness's read/write permission tiers do **not**
+constrain what a plugin's own code can do. So the trust bar for a memory plugin
+is higher than for a tool: a memory plugin sits on your prompt prefix and writes
+to disk on your behalf. dsh-engram's model, stated plainly:
+
+- **No network, ever.** The plugin has no outbound socket, no telemetry, no
+  update pinger. Nothing here can leak your sessions off the machine.
+- **No shell, no filesystem access beyond one storage file.** It never executes
+  commands and never touches arbitrary paths. All data lives in the single
+  storage-domain unit `~/.dsh/storages/dsh_engram.json` (plus the session-log
+  reads it makes through DSH's own `ctx.sessionQuery`).
+- **Secrets are redacted before they can land on disk.** Every write path —
+  `engram_store`, auto-capture, and the import/restore route — runs text through
+  the deterministic `redactText` rule engine (API keys, JWTs, `Bearer` tokens,
+  private keys, `key=value` secret shapes) *before* the dedup hash, the char
+  cap, and storage. Nothing sensitive is ever persisted, so nothing sensitive
+  can be recalled later.
+- **Doing harm requires your harness's own permissions.** The plugin only *asks*
+  the host to do things via the same seams the tools you already trust use. It
+  does not widen sandbox policy or escalate to `danger-full-access` — if you
+  keep your profile's defaults, engram inherits exactly those bounds.
+- **Read-mostly web API, loopback-fenced.** The GUI routes under
+  `/api/dsh-engram` reject any non-loopback caller unless you explicitly
+  whitelist a hostname via `trustedHosts`; even then the same-origin fence holds.
+- **Verifiable.** `npm run dsh-engram -- doctor` (`/scripts/dsh-engram.mjs
+  doctor`) reports what the plugin is configured to touch; the whole store is
+  inspectable, nothing is opaque. If you ever doubt a claim in this section, the
+  code to check is `lib/redact.js`, `lib/store.js` and this plugin's
+  `cordis.patch.yml`.
+
+What this deliberately does **not** claim: it is not an air-gap. If your profile
+grants the agent `danger-full-access` or a shell, the agent can use those —
+engram is a memory layer, not a sandbox. The point above is that *dsh-engram
+itself* adds no surface of its own.
+
+## Data contract: export / import
+
+Memory should not be a hostage. The four tables (memories / tasks / links /
+entities) can be dumped and restored through a stable, versioned, machine-readable
+shape — so the corpus survives a reinstall, a machine move, or (when a thin
+adapter is written) a move to another harness, MCP end-point or Claude Code
+skill. The contract is plain JSON with a self-describing header:
+
+```http
+GET  /api/dsh-engram/export?workspace=/path/to/project   # one workspace
+GET  /api/dsh-engram/export                              # every workspace
+```
+
+```jsonc
+{
+  "meta": { "format": "dsh-engram/export", "version": 1, "exportedAt": 1724…, "workspace": "/path/to/project" },
+  "memories": [ /* all rows, archived included — a backup never loses provenance */ ],
+  "tasks":    [ /* draft/active/stable + archived */ ],
+  "links":    [ /* typed edges */ ],
+  "entities": [ /* graph nodes */ ]
+}
+```
+
+Restore is idempotent by default and gated when destructive:
+
+```http
+POST /api/dsh-engram/import          # body: { payload, mode, dryRun?, workspace?, confirm? }
+```
+
+- **`mode: "merge"`** (default) — writes only rows whose `id` is absent, so a
+  backup can be re-applied any number of times without duplicating anything. Each
+  row keeps its own `workspace`.
+- **`mode: "replace"`** — wipes the target `workspace` from all four tables, then
+  restores only its rows. Destructive, so it additionally requires
+  `confirm: "restore"` in the body.
+- **`dryRun: true`** — computes the identical plan (what would be written /
+  skipped) without writing a single row.
+- **Import honors the same invariants as `storeMemory`**: memory text passes the
+  secret redactor before touching disk, and rows that would break the contract
+  (missing id/workspace, empty text, over `maxMemoryChars`, id already present
+  in merge, over the workspace memory cap) are skipped and listed in the
+  response report instead of aborting the batch.
+
+A restore round-trip for one workspace is then:
+
+```sh
+curl -s "http://127.0.0.1:3080/api/dsh-engram/export?workspace=$PWD" -o engram-backup.json
+curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
+  -H "content-type: application/json" \
+  -d "{\"payload\": $(cat engram-backup.json), \"mode\": \"merge\"}"
+```
+
 ## Install
 
 ```sh
@@ -275,15 +419,20 @@ npm run build:client
 
 | Tool | Purpose | Kind |
 |---|---|---|
-| `engram_store` | Explicitly store one memory (kind, tags, optional entity anchor) | write |
-| `engram_recall` | Deterministic keyword recall over workspace memories; optional `search_sessions` FTS over past sessions | read |
+| `engram_store` | Explicitly store one memory (kind, tags, optional entity anchor, optional supersedes/contradicts ids, optional `source`/`conditions`) | write |
+| `engram_recall` | Deterministic keyword recall over workspace memories; optional `search_sessions` FTS over past sessions; opt-in `scope=global`/`recallScope` cross-workspace recall with `[W:<ws>]` origin markers | read |
 | `engram_detail` | Full record of one memory id (provenance, tags, hits) | read |
 | `esr_task` | Create a task entity (draft → active) | write |
 | `esr_close` | Close a task via the evidence protocol (artifact + evaluation + memory_ref) | write |
 | `esr_link` | Add a typed relation between two entities (mini graph) | write |
+| `esr_dep` | Add a dependency edge (blocks / relates-to / parent-of) between tasks | write |
+| `esr_claim` | Atomically claim a task (assignee + claimedAt, draft → active) | write |
+| `esr_unclaim` | Release a claimed task's assignee | write |
 | `esr_ready` | List claimable tasks (no open blocker, unclaimed) | read |
 | `esr_status` | Pull live ESR state + derived hints (`since_revision` short "unchanged" response) | read |
+| `esr_node` | Create/update an entity node (stable symbol) | write |
 | `esr_gc` | Run the memory GC for the workspace (`dry_run:true` previews) | write |
+| `esr_model` | Precomputed mental model of the workspace (`brief`/`full`, `max_chars`) | read |
 
 The `[ESR]` block is a frozen per-session snapshot and never auto-refreshes —
 call `esr_status` for the live truth.
@@ -331,24 +480,74 @@ Triggers follow DSH's own compaction timing (step pressure / context-overflow /
 `/compact`); the lock, replay validation, tool-call/result pairing and token
 pricing are all reused from the basic engine. Any error falls back to the
 default compressor — compaction is never broken; with `gcReplacesCompaction:
-false` (or a host without `dsh-compaction-basic`) the engine never mounts.
-Mounting registers the `compaction` service on the plugin's fiber, so
-unloading/reloading engram restores the default engine.
-
-**Mounting semantics (verified against cordis source)**: cordis refuses a second
-provider of the same service in the same realm (`provide()` throws
-`service "compaction" has been registered` — not "last write wins"). Hence:
-
-- **Host plane**: the plugin patch disables the base `compaction-basic` row
-  (re-armed automatically when engram is uninstalled); dsh-engram is then the
-  sole `compaction` provider, mounting a bare `BasicCompactionEngine` under
-  `gcReplacesCompaction:false` so the service never disappears. Headless / TUI /
-  base-style profiles work out of the box.
-- **Preset plane (web profile)**: web keeps compaction inside each agent
-  preset's isolated realm (the shipped `standard` preset mounts its own
-  `compaction-basic`), unreachable from a host-plane row. Swap that row for the
-  mountable entry dsh-engram ships (`dsh-engram/compaction`, package subpath
-  export) to activate per session:
+false` (or a host without `dsh-compaction-basic`) a bare `BasicCompactionEngine`
+is mounted instead, so the `compaction` service never disappears while
+dsh-engram is installed. Mounting registers the `compaction` service on the
+plugin's fiber, so unloading/reloading engram restores the default engine.
+
+> **Shrink gate**: the harness refuses any checkpoint that is not strictly
+> smaller than the evicted span (`summary is not smaller than the shadowed
+> content`) and rolls the compaction back — otherwise the context never shrinks
+> and the session eventually hits the model-side overflow. Context GC
+> self-predicts that gate: it mirrors the harness framing with the host
+> `tokenMeter` (verified token-for-token identical) and truncates the
+> pointer/narrative body to the evicted span's token budget (the pointer head
+> and working set survive; the trimmed tail stays recoverable in the session
+> log), so compactions actually commit. Full from-scratch usage:
+> [`docs/CONTEXT-GC-GUIDE.zh.md`](docs/CONTEXT-GC-GUIDE.zh.md).
+
+#### Where it is enabled (the entry point)
+
+Assembly happens on **two planes** — and web is now fully automatic, zero config:
+
+- **Host plane (headless / TUI / base profiles) — on by default, zero config**:
+  the main plugin (`lib/index.js`) mounts the engine inside `ctx.effect` via
+  `mountCompactionEngine(ctx, resolved, { readWorkspace }) → new Engine()`,
+  registering the `compaction` service on its own fiber; the plugin patch
+  disables the base `compaction-basic` row, making engram the sole host-plane
+  provider. `gcReplacesCompaction: true` (default) → `ContextGcEngine`;
+  `false` → a bare `BasicCompactionEngine`. Tune via profile patch
+  (`config: { gcReplacesCompaction: false }`) or the settings card's
+  `gcNarrative` knob (narrative off = fully mechanical).
+- **Preset plane (web profile) — fully automatic, zero config, covers every
+  preset**: web keeps compaction inside each agent preset's isolated realm
+  (the shipped presets mount their own `compaction-basic`), unreachable from a
+  host-plane row — and unreachable from a profile patch too (`mountPreset`
+  builds its `Include.Config` with no patches; verified against the harness
+  source). So on boot, once the `agentPresets` service is ready, the plugin
+  **auto-edits every preset that still has the stock layout** — the default
+  preset plus the whole roster (shipped root + `~/.dsh/.agent-presets` user
+  root: `standard`, `code`, `cordis`, and your own presets): it swaps the
+  `compaction-basic` row inside the `compaction` group for
+  `dsh-engram/compaction`. That auto-wiring is:
+  - **on by default** (`autoWebCompaction: true`, toggle in the settings card's
+    memory-GC section), idempotent — an already-wired preset is left alone;
+    **what "off" means**: the plugin stops auto-wiring on later boots (the
+    headless/TUI/base host plane is unaffected) — it does NOT un-wire presets
+    that were already wired; use `npm run web-compaction:revert` for that;
+  - **per-preset**: only stock-layout presets are touched — a preset with a
+    custom compaction group, or none at all (e.g. the shipped `minimal`
+    preset), is never written, only logged;
+  - **backed up + validated**: a create-only `agent.cordis.yml.engram.bak`
+    holds each original next to its file, every result is re-read and verified
+    after writing, and any doubt rolls that file back; a failure only warns and
+    that session keeps DSH's default summarizer — the host plane is never
+    affected.
+  - **config actually propagates**: the engine config written into each row
+    comes from the live settings (`gcReplacesCompaction` / `gcNarrative`) — with
+    "already wired but with a different config" treated as a refresh, so
+    changing the settings knobs re-provisions the web rows on the next boot
+    instead of being silently ignored.
+  - A fully equivalent manual CLI, shipped in the npm package
+    (scans both the shipped and the user root; `--file <path>` targets one):
+    ```bash
+    npx dsh-engram status     # stock = untouched · wired = active · custom = hands-off
+    npx dsh-engram doctor     # status + ranked next steps for every gap found
+    npx dsh-engram enable     # same as the boot-time auto-wiring (usually a no-op)
+    npx dsh-engram revert     # restore the stock row everywhere — run BEFORE uninstalling
+    ```
+    (in the repo, `npm run web-compaction:*` is an alias of the same CLI.)
+    Either way the `compaction` group becomes:
   ```yaml
   - id: compaction
     name: cordis:group
@@ -360,14 +559,51 @@ provider of the same service in the same realm (`provide()` throws
       - id: engram-compaction       # replaces the original compaction-basic
         name: dsh-engram/compaction
         config:
-          gcReplacesCompaction: true   # optional; false = default LLM summary for this session
-          gcNarrative: true
+          gcReplacesCompaction: true   # from settings; false = default LLM summary for this session
+          gcNarrative: true            # from settings; false = fully mechanical
       - id: command-compact
         name: '@deepseek-ai/dsh-command-compact'
       - id: tool-result-pruner
         name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
         # keep the original config
   ```
+  ⚠️ **Uninstall = revert first**: once a preset references
+  `dsh-engram/compaction`, removing dsh-engram leaves every such row dangling
+  and web sessions hang on load — so run `npx dsh-engram revert`
+  (restores every preset) BEFORE uninstalling. A harness upgrade that ships a
+  fresh standard preset overwrites the swap and self-heals the dangling
+  reference.
+
+#### First impressions after an npm install (perceive / guide / configure)
+
+- **Automatic**: install into a profile and boot once — the host plane is taken
+  over by `mountCompactionEngine`, and the web plane by `autoWebCompaction`
+  (default on) rewriting every stock preset at boot. **Zero manual setup.**
+- **Perceivable**: at boot the plugin writes an authoritative snapshot to
+  `$DSH_HOME/engram/context-gc.status.json` (`host` plane mode + the per-preset
+  `web` results + effective config). At any time run `npx dsh-engram status` or
+  `npx dsh-engram doctor`; the web memory board (ESR kanban) also shows a
+  header chip ("Context GC·主机 ·N 预设") fed by the overview API. Two startup
+  log lines confirm it too: `engram context-gc: compaction = Context GC …` and
+  `engram web-provision: wired Context GC into preset …`.
+- **Configurable**: one settings card (memory-GC section) governs everything:
+  `autoWebCompaction` (web auto-wiring on/off), `gcReplacesCompaction`
+  (Context GC vs default summarizer), `gcNarrative` (narrative safety net).
+  Changes take effect after restarting `dsh web`, and the web rows are
+  refreshed to match automatically.
+
+**Verify it took**: after restarting `dsh web` (or the profile) —
+- host plane (headless/TUI/base): the startup log shows
+`engram context-gc: compaction = Context GC (mechanical eviction + re-fetch pointers)`;
+- web plane: the log shows one line per wired preset —
+`engram web-provision: wired Context GC into preset "standard" (…); restart dsh web so sessions pick it up`,
+or `npx dsh-engram status` reports `wired` for each; sessions composed
+from ANY preset then compact via mechanical eviction + re-fetch pointers.
+A line like `… keeping the existing compaction service` means another provider
+already owns `compaction` in that realm (the swap didn't take); `web-provision … skipped (custom)`
+means that preset was customized (or has no compaction group) and was left untouched;
+`dsh-compaction-basic unavailable` means the backend is missing and everything
+falls back to the default compressor.
 
 ## Auto-capture policy
 
@@ -408,7 +644,11 @@ ESR operating protocol (static, byte-identical every turn)
 [ENGRAM] workspace: symbolic-index · 2 memories · 1 task(s) active · 0 links
 [D] 06-18 Decided: use sqlite-vec for retrieval #a2331d87
 [T] 06-18 Retrieval upgrade — ACTIVE · gap: artifact, evaluation, memory_ref #tsk_8b26
-drill: engram_store (user asks to remember) | engram_recall <query> | engram_detail <id> | esr_task / esr_close / esr_link
+drill: use [RECALL] below · engram_detail <id> (full record) · engram_recall <query> (more) · esr_task/esr_node/esr_link (work)
+
+[RECALL] recall · 1 hit(s) · first msg: retrieval
+- [D] 06-18 Decided: use sqlite-vec for retrieval upgrade #a2331d87 ×2
+context: use above · engram_detail <id> · engram_recall <query>
 
 [ESR] tasks: 1 active / 1 stable
 - tsk_0d: Retrieval upgrade — ACTIVE · gap: artifact, evaluation, memory_ref
@@ -430,6 +670,14 @@ records via `engram_detail`. When a workspace has no tasks, `[ESR]` still render
 one line naming `esr_task`/`esr_close` so the mechanism stays visible to the
 model instead of vanishing.
 
+`[RECALL]` (session-start auto recall, `autoRecallOnStart`) runs one deterministic
+BM25 pass over the workspace keyed on the session's first user message and injects
+the top `autoRecallLimit` hits, bounded by the `autoRecallMaxChars` character
+budget; nothing renders on zero hits or an empty workspace. It is a *pointer* — the
+model should treat it as "this is relevant; `engram_detail` for the full record" —
+rather than full-text dumping. It is a pure read (never bumps `hits`), superseded
+stale truth never occupies a slot, and it freezes per session with `[ENGRAM]`.
+
 ## Config
 
 Defaults are token-conscious; override any key via the profile patch
@@ -440,6 +688,10 @@ Defaults are token-conscious; override any key via the profile patch
   config:
     autoCapture: true        # zero-LLM tool-result capture
     sessionSearch: true      # engram_recall may also FTS past sessions
+    recallScope: workspace   # recall scope: "workspace" (strict isolation, default) | "global" (opt-in cross-workspace recall with [W:<ws>] origin markers)
+    autoRecallOnStart: true  # session-start auto recall (false = back to pure pull)
+    autoRecallLimit: 3       # [RECALL] max injected hits (few and precise)
+    autoRecallMaxChars: 700  # [RECALL] char budget
     autoCapturePerSession: 40
     indexMaxLines: 12        # [ENGRAM] line cap
     indexMaxChars: 700       # [ENGRAM] char cap (token budget)
@@ -482,7 +734,11 @@ dedup 1.0.
 **/api/dsh-engram/stats + the observability panel** is the real-session layer —
 it answers how the model actually uses the memory in production (ESR
 proactivity ratio, recall hit rate, detail conversion), while the eval
-answers how good the retrieval layer itself is.
+answers how good the retrieval layer itself is. The stats read the
+concatenated multi-frame `session.jsonl.zstd` logs with Node's built-in
+`node:zlib` (frame scan + one reused decoder handle) — **no system `zstd` CLI
+is required**, so the telemetry works out-of-the-box on Windows and other
+hosts without an external codec.
 
 Repo layout: `lib/` (host half: store / capture / index-block / tools / api /
 settings), `client/` (browser half, TSX + `build.mjs`), `test/` (node:test).