Store chats in per-chat cache files instead of one workspace blob

Every history append serialized the entire workspace chat cache
(hundreds of MiB for heavy users), causing CPU spikes between messages
and slow startup. Chats now live in chats/<chat-id>.transit.json plus a
small index that drives listings and lazy loading, so saving a message
costs O(that chat) and startup only reads the index.

- migrate the legacy db.transit.json on load, keeping it as .bak so
  rolling back to an older ECA loses nothing
- keep the global auth cache at version 6 so downgrades stay logged in
- index merge-on-write keeps the worktree sharing semantics from #558,
  chat files are recency guarded against stale peer overwrites
- hooks db_cache_path now points at the workspace cache dir and
  read-chat accepts both the new layout and legacy files
- isolate unit tests cache dir, they were polluting the real user
  cache for the eca workspace

Closes #557

Author: ericdallo

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Store chats in per-chat cache files with a lazy-loaded index instead of one whole-workspace blob, fixing CPU spikes and slow startup as history grows; legacy caches migrate automatically. #557
+- Hooks `db_cache_path` now points at the workspace cache dir instead of `db.transit.json`; `read-chat --db-cache-path` accepts the dir or a legacy file. #557
 - Keep `compact_chat` in the tool schema across normal and compact requests, preserving prompt-cache prefixes while rejecting calls outside active compaction.
 
 - Provide token metrics for ollama provider. #567.

docs/config/hooks.md

@@ -166,7 +166,8 @@ Every hook receives these fields on stdin:
 
 - `hook_name`, `hook_type`, `workspaces`, `cwd`, `db_cache_path`, `session_id`, `eca_executable`
   - `cwd` — the first workspace folder, matching the working directory ECA uses for hook commands.
-  - `session_id` — the cache session key derived from the `db_cache_path` parent directory.
+  - `db_cache_path` — the workspace chat cache dir (holding `chats/index.transit.json` and per-chat files); pass it to `eca read-chat --db-cache-path`.
+  - `session_id` — the cache session key: the `db_cache_path` dir name.
   - `eca_executable` — the launch command of the running ECA process (executable path for native binaries; the full `java ... -jar` invocation for JVM launches).
 
 **Chat-scoped hooks** (everything except `sessionStart`/`sessionEnd`) additionally receive `chat_id`, `agent`, `behavior` (deprecated alias of `agent`), `full_model`, and `variant`.
@@ -377,7 +378,7 @@ eca_executable=$(echo "$input" | jq -r '.eca_executable')
 $eca_executable read-chat --db-cache-path "$db_cache_path" --chat-id "$chat_id"
 ```
 
-Keep the query focused and fast — the hook runs synchronously with a 30s timeout. `read-chat` needs no running server and reads directly from `db.transit.json`. See [`read-chat`](../read-chat.md) for full options and scripting examples.
+Keep the query focused and fast — the hook runs synchronously with a 30s timeout. `read-chat` needs no running server and reads directly from the chat cache files. See [`read-chat`](../read-chat.md) for full options and scripting examples.
 
 ## `/hooks` command
 

docs/read-chat.md

@@ -4,24 +4,26 @@ description: "Stream raw ECA chat history from the DB cache as JSONL: list chats
 
 # read-chat
 
-Inspect ECA's chat database offline by reading `db.transit.json` directly. No running server is required.
+Inspect ECA's chat database offline by reading the workspace chat cache directly. No running server is required.
+
+`--db-cache-path` takes the workspace cache dir (e.g. `~/.cache/eca/myproj_a1b2C3d4`, holding `chats/index.transit.json` plus one `chats/<chat-id>.transit.json` per chat) and also accepts a legacy `db.transit.json` file written by older ECA versions.
 
 Output is always **raw JSONL** (one JSON object per line) in the persisted internal shape, making it suitable for debugging, export, and programmatic processing.
 
 ## Quick start
 
 ```bash
 # List all chats (newest first)
-eca read-chat --db-cache-path ~/.cache/eca/db.transit.json
+eca read-chat --db-cache-path ~/.cache/eca/myproj_a1b2C3d4
 
 # Resolve the cache from the session's workspace folders
 eca read-chat --workspace ~/Code/Clojure/eca --workspace ~/Code/Clojure/eca-worktrees/add-read-chat-command
 
 # Stream raw messages from a specific chat
-eca read-chat --db-cache-path ~/.cache/eca/db.transit.json --chat-id <chat-id>
+eca read-chat --db-cache-path ~/.cache/eca/myproj_a1b2C3d4 --chat-id <chat-id>
 
 # Last 10 user messages from the past hour
-eca read-chat --db-cache-path ~/.cache/eca/db.transit.json \
+eca read-chat --db-cache-path ~/.cache/eca/myproj_a1b2C3d4 \
   --chat-id <chat-id> --since 1h --role user | tail -n 10
 ```
 
@@ -47,7 +49,7 @@ Provide exactly one input source: `--db-cache-path` or one or more `--workspace`
 
 | Option | Description |
 |--------|-------------|
-| `--db-cache-path <PATH>` | Path to `db.transit.json`. |
+| `--db-cache-path <PATH>` | Workspace cache dir (or a legacy `db.transit.json` file). |
 | `--workspace <PATH>` | Workspace folder; repeat in the original session order. |
 | `--chat-id <ID>` | Focus on a chat; omit to list all chats. |
 | `--role <ROLE>` | Filter messages by exact `role` string (requires `--chat-id`). |
@@ -85,21 +87,21 @@ Messages created before `:created-at` tracking was added lack timestamps. When f
 === "Last 10 messages"
 
     ```bash
-    eca read-chat --db-cache-path ~/.cache/eca/db.transit.json \
+    eca read-chat --db-cache-path ~/.cache/eca/myproj_a1b2C3d4 \
       --chat-id abc | tail -n 10
     ```
 
 === "Count messages"
 
     ```bash
-    eca read-chat --db-cache-path ~/.cache/eca/db.transit.json \
+    eca read-chat --db-cache-path ~/.cache/eca/myproj_a1b2C3d4 \
       --chat-id abc | wc -l
     ```
 
 === "Extract user text"
 
     ```bash
-    eca read-chat --db-cache-path ~/.cache/eca/db.transit.json \
+    eca read-chat --db-cache-path ~/.cache/eca/myproj_a1b2C3d4 \
       --chat-id abc --role user | \
       jq -r '
         def content_text:
@@ -120,23 +122,23 @@ Messages created before `:created-at` tracking was added lack timestamps. When f
 === "Extract assistant text"
 
     ```bash
-    eca read-chat --db-cache-path ~/.cache/eca/db.transit.json \
+    eca read-chat --db-cache-path ~/.cache/eca/myproj_a1b2C3d4 \
       --chat-id abc --role assistant | \
       jq -r '.content[]? | select(.type == "text") | .text'
     ```
 
 === "List tool calls"
 
     ```bash
-    eca read-chat --db-cache-path ~/.cache/eca/db.transit.json \
+    eca read-chat --db-cache-path ~/.cache/eca/myproj_a1b2C3d4 \
       --chat-id abc --role tool_call | \
       jq -c '.content | {id, name, input: .arguments, summary, server, full_name: ."full-name"}'
     ```
 
 === "List tool outputs"
 
     ```bash
-    eca read-chat --db-cache-path ~/.cache/eca/db.transit.json \
+    eca read-chat --db-cache-path ~/.cache/eca/myproj_a1b2C3d4 \
       --chat-id abc --role tool_call_output | \
       jq -c '
         .content
@@ -153,28 +155,28 @@ Messages created before `:created-at` tracking was added lack timestamps. When f
 === "Find chats by model"
 
     ```bash
-    eca read-chat --db-cache-path ~/.cache/eca/db.transit.json | \
+    eca read-chat --db-cache-path ~/.cache/eca/myproj_a1b2C3d4 | \
       jq -c 'select(.model | contains("claude"))'
     ```
 
 === "Count user prompts"
 
     ```bash
-    eca read-chat --db-cache-path ~/.cache/eca/db.transit.json | \
+    eca read-chat --db-cache-path ~/.cache/eca/myproj_a1b2C3d4 | \
       jq '{id: .id, count: .["user-prompt-count"]}'
     ```
 
 === "Export a chat"
 
     ```bash
-    eca read-chat --db-cache-path ~/.cache/eca/db.transit.json \
+    eca read-chat --db-cache-path ~/.cache/eca/myproj_a1b2C3d4 \
       --chat-id abc > chat-export.jsonl
     ```
 
 === "Recent chats, pretty-printed"
 
     ```bash
-    eca read-chat --db-cache-path ~/.cache/eca/db.transit.json --since 1d | \
+    eca read-chat --db-cache-path ~/.cache/eca/myproj_a1b2C3d4 --since 1d | \
       jq '{title, model, updated_at: .["updated-at"]}'
     ```
 

src/eca/cache.clj

@@ -75,7 +75,7 @@
 
 (def ^:private linked-worktree-root
   "Memoized `linked-worktree-root*`: resolved on nearly every chat mutation via
-   `eca.db/update-workspaces-cache!`, and a worktree's gitdir pointer does not
+   `eca.db/save-chat!`, and a worktree's gitdir pointer does not
    change during a server's lifetime."
   (memoize linked-worktree-root*))
 
@@ -142,13 +142,19 @@
       (str sanitized "_" hash)
       hash)))
 
-(defn workspace-cache-file
-  "Returns a File object for a workspace-specific cache file.
+(defn workspace-cache-dir
+  "Returns a File object for the workspace-specific cache directory.
    The directory identity is the order-independent <hash>; the human-readable
    prefix is cosmetic. Healing of caches fragmented across differently-named
-   dirs for the same workspace is handled by eca.db/consolidate-workspace-cache!."
+   dirs for the same workspace is handled by eca.db/migrate-legacy-workspace-caches!."
+  ^File [workspaces uri->filename-fn]
+  (io/file (global-dir) (workspace-dir-name workspaces uri->filename-fn)))
+
+(defn workspace-cache-file
+  "Returns a File object for a workspace-specific cache file inside
+   `workspace-cache-dir`."
   [workspaces filename uri->filename-fn]
-  (io/file (global-dir) (workspace-dir-name workspaces uri->filename-fn) filename))
+  (io/file (workspace-cache-dir workspaces uri->filename-fn) filename))
 
 (defn redundant-workspace-cache-files
   "Returns the cache files named `filename` that live in directories belonging to