@r1z4x/tezgah 1.2.0 → 1.4.0

package/docs/operations.md

@@ -202,8 +202,8 @@ fetch, the flip and the re-arm and runs none of the three
 
 The status line says when a newer release is out. A `↑X.Y.Z` chip sits beside
 the logo, in the version's own group, on every surface (`notice_segments()`,
-`hooks/tezgah_update.py`). A redraw only reads `~/.cache/tezgah/update.json`.
-When that file is a day old, the redraw stamps it and starts one detached
+`hooks/tezgah_update.py`). A redraw only reads the `update_check` row of
+`~/.cache/tezgah/tezgah.db`. When that row is a day old, the redraw stamps it and starts one detached
 check against the GitHub releases endpoint. An offline check writes nothing,
 and the next day asks again. `tezgah update` is the command the chip points
 at, and it is the only thing that moves the install. The
@@ -225,7 +225,7 @@ After a change to the contract text (`hooks/tezgah_policy.py`,
 - `--refresh` does that without a reinstall, for every armed host's static
   block and not only opencode's (`refresh_contract`). opencode has no
   session-start hook, so its plugin runs it once per session
-  (`hosts/opencode/plugins/tezgah.js:2633-2637`). Until 2026-10-02 it
+  (`hosts/opencode/plugins/tezgah.js:2666-2670`). Until 2026-10-02 it
   re-rendered opencode's files alone and reset the one shared hash, so a rule
   edit left the other static files stale while `--report` went green (audit
   M-5).
@@ -370,7 +370,8 @@ does not hold.
 | Invocation | What it does |
 |---|---|
 | `tezgah-doctor` | nothing: sizes, session and event counts, whether opencode is running, the two context-hygiene settings, the `.codegraph` bytes and index presence per repository, and the three host state dirs (`bin/tezgah-doctor::collect`, `bin/tezgah-doctor::report`) |
-| `tezgah-doctor --clean` | vacuums opencode's database, and only when opencode is not running (`bin/tezgah-doctor::vacuum_db`, `bin/tezgah-doctor::main`); and deletes tezgah's own hook state not modified for `--retention-days` (default 30) - the ledgers under `evidence/`, `turns/`, `sessions/`, `classify.log`, `context-drops.log` and `debug.log`, in the cache and its sandbox fallback - keeping the current session's (`$TEZGAH_SESSION`) files whatever their age (`sweep_state`) |
+| `tezgah-doctor --clean` | vacuums opencode's database, and only when opencode is not running (`bin/tezgah-doctor::vacuum_db`, `bin/tezgah-doctor::main`); deletes every evidence ledger whose newest row is older than `--retention-days` (default 30), rows, import offsets and old JSONL file together (`hooks/tezgah_store.py::sweep_evidence`), and the turn stamps and used-tool marks last written before then (`hooks/tezgah_store.py::sweep_cache`); and deletes the files not modified for that long - `classify.log`, `context-drops.log`, `debug.log` and the `turns/` and `sessions/` files a running older release still writes - in the cache and its sandbox fallback, keeping the current session's (`$TEZGAH_SESSION`) ledger, stamp and marks whatever their age (`sweep_state`) |
+| `tezgah-doctor --import-evidence` | imports every old `evidence/*.jsonl` file into the cache's `tezgah.db` now, in the cache and its sandbox fallback (`bin/tezgah-doctor::import_evidence`); session start runs the same import detached at most once a day (`hooks/tezgah_store.py::import_later`) |
 | `tezgah-doctor --coverage` | every tracked file the codegraph index does not hold, in two classes — a supported extension the index is missing, and a shebang-only script with no `.py` twin — with the file counts it read, so an empty result cannot read as "everything is covered" |
 | `tezgah-doctor --stack` | per host: the context files in load order, the skill dirs and which copy wins, the hook rows per event with their owner, the MCP servers, and every conflict; exits 1 on one ([hosts](hosts.md#precedence-what-each-host-loads-and-in-which-order), `hooks/tezgah_stack.py::report`) |
 | `tezgah-doctor --prune-sessions DAYS` | deletes sessions idle longer than DAYS through `opencode session delete`, then vacuums; skipped when opencode is running or its CLI is missing (`bin/tezgah-doctor::prune_sessions`, `bin/tezgah-doctor::main`) |
@@ -398,7 +399,7 @@ writes only into a repository that already has a `.tezgah/` directory. A
 (`hooks/tezgah_context.py::repo_marks`). A workspace of repo-provided data gets
 nothing.
 
-Rows go to `<repo>/.tezgah/taste/signals.jsonl` through the ledger's own writer
+Rows go to the `signals` table of `<repo>/.tezgah/taste/taste.db`
 (`_write`, `hooks/tezgah_taste.py::_write`). A user turn adds a `prompt` row,
 redacted and cut to 2000 characters (`hooks/tezgah_taste.py::note_prompt`).
 A landed write adds an `edit` row with its redacted old and new text, cut to
@@ -412,7 +413,7 @@ ledger row. A rollback therefore never reads it as a pre-state (`capture_after`,
 `hooks/tezgah_snapshot.py::capture_after`). A file outside the repository gets no
 after blob.
 opencode reaches the same call through a process (`noteTaste`,
-`hosts/opencode/plugins/tezgah.js:2380-2390`).
+`hosts/opencode/plugins/tezgah.js:2413-2423`).
 
 ```sh
 touch ~/.config/tezgah/taste-on               # arm; rm it to disarm
@@ -438,13 +439,21 @@ write's pre-state, or with the file on disk (`user_diff`,
 signal (`decide`, `bin/tezgah-taste::decide`, [judge](judge.md)). The decision
 names preference, defect or none. It picks one of eleven fixed categories and a
 scope. It also says how the signal relates to each learning held: supports,
-contradicts, narrows or unrelated. When another provider answers, `learn` writes
-the decision to `decisions.jsonl` as `unverified` and never applies it. A defect
-goes to `defects.jsonl` and never into the ledger.
-
-The ledger is `<repo>/.tezgah/taste/ledger.json`, plus
-`~/.config/tezgah/taste/ledger.json` for user-scope learnings
-(`hooks/tezgah_taste_ledger.py`). Confidence is (r+1)/(r+s+2) over supporting
+contradicts, narrows or unrelated. When another provider answers, `learn` records
+the decision in the `decisions` table as `unverified` and never applies it. A
+defect goes to the `defects` table and never into the ledger.
+
+Armed taste also learns by itself. At session start, `learn` starts in the
+background when new signals arrived since the last start. It starts at most
+once an hour per repository (`learn_later`, `hooks/tezgah_taste.py::learn_later`). It runs
+with `--no-fallback` and only when a TypeSafe key resolves, so it never pays a
+generative provider for a decision it could not apply. It does not run on
+Windows, which has no ledger lock yet. The stamp is a `taste_learn` row of the
+cache's `tezgah.db`. The log lives under the cache dir, in `taste-learn/`.
+
+The repository's learnings live in the same `taste.db`. User-scope learnings live in
+`~/.config/tezgah/taste/taste.db` (`hooks/tezgah_taste_ledger.py`). Confidence is
+(r+1)/(r+s+2) over supporting
 and contradicting evidence. Each piece counts at its decision probability, and
 the ledger forgets it per day at its scope's rate (`confidence`,
 `hooks/tezgah_taste_ledger.py::confidence`). A learning turns active in its
@@ -457,8 +466,34 @@ ledgers. `learn`, `accept`, `reject` and `edit` rewrite them one at a time on
 this machine, under a lock on `~/.config/tezgah/taste/ledger.lock` (`locked`,
 `hooks/tezgah_taste_ledger.py::locked`). The lock spans every repository,
 because each command also rewrites the user ledger. A second one exits 2 and
-names the holder. Every taste row goes through the evidence ledger's locked
-writer (`append`, `hooks/tezgah_taste_ledger.py::append`).
+names the holder.
+
+One module owns both databases (`taste`, `hooks/tezgah_store.py::taste`). Each
+runs SQLite in WAL mode with a 5-second busy timeout. The directory is 0700 and
+the database file 0600. A row keeps its JSON fields as before. A hook drops a
+row it cannot write, and the CLI's decision, defect and label rows raise
+instead (`append`, `hooks/tezgah_taste_ledger.py::append`). An open of a
+database imports the files it replaces (`_import`,
+`hooks/tezgah_store.py::_import`). `ledger.json` and `gate.json` import only
+into empty tables. The `.jsonl` row files (`signals`, `decisions`, `defects`,
+`labels`, `injected`) import on every open that finds one, so rows an older
+install wrote later still land. The import holds the old writer's flock on the
+file. The `imported` table records how many bytes of each file went in, in the
+same transaction as the rows. The next open therefore takes only the bytes a
+writer added since, and a torn last line waits for its newline. After the commit
+the import renames a fully read file to `<name>.imported`, or `.imported.N`
+beside an earlier one, and never deletes one. A process killed before that
+rename imports nothing twice. A file that does not read or parse stays in
+place. The import retries it only once its size or mtime changes. The old
+per-session `taste-notes/` files under the cache dir are not carried over: they
+never named their repository. A session open during the upgrade can see one
+write note again.
+
+Every command that opens the store exits 2 when the repository's `.tezgah`
+came with the clone (`store_or_exit`, `bin/tezgah-taste::store_or_exit`). It
+then reads, imports and creates nothing there. The refusal also applies to a
+repository whose `.tezgah` is a symlink or whose git index cannot be read. Run
+the command from another checkout to manage the user-scope learnings.
 
 Session start injects the active learnings (`block`,
 `hooks/tezgah_taste_ledger.py::block`). A rule needs confidence 0.8 and a
@@ -467,11 +502,12 @@ labelled sample (`calibration`, `hooks/tezgah_taste_ledger.py::calibration`). A
 hint needs 0.6. A learning whose evidence paths are all gone is withheld. A
 write also carries the in-scope learnings it has not yet shown in the session,
 on every host's post-tool channel (`write_note`, `hooks/tezgah_taste.py::write_note`).
+The repository's database keeps the learnings each session has already been shown.
 `gate` compares preference corrections per writing turn before and after the
 first injection, by when each turn happened. Once both arms hold 980 turns and
 the after-rate is not lower
-at one-sided p < 0.1, it writes `gate.json` and injection stops (`gate`,
-`hooks/tezgah_taste_ledger.py::gate`). `mine` reads omp's top-level session
+at one-sided p < 0.1, injection stops (`gate`,
+`hooks/tezgah_taste_ledger.py::gate`). The database keeps that stop. `mine` reads omp's top-level session
 files and Claude's top-level transcripts whose cwd is under `--root`
 (`cmd_mine`, `bin/tezgah-taste::cmd_mine`). `measure` and `rate` use a fixed
 labelling rule (`RULE`, `bin/tezgah-taste::RULE`).

package/docs/skills.md

@@ -32,7 +32,7 @@ skill is simply not read.
 
 opencode's plugin does inject prompt-time text - the builder's per-turn block,
 the conditional rules included
-(`hosts/opencode/plugins/tezgah.js:2596-2625`) - but that text names at most one
+(`hosts/opencode/plugins/tezgah.js:2629-2658`) - but that text names at most one
 skill (the hint), never the roster, so the installer writes one:
 `~/.config/tezgah/opencode-skills.md` always-on and
 `opencode-skills.full.md` on demand (`bin/tezgah-setup::SKILL_ROUTER`, `bin/tezgah-setup::SKILL_ROUTER_FULL`), the first

package/docs/status-line.md

@@ -96,9 +96,9 @@ measure the surface cannot see, then armed-and-used or armed-not-used.
 | `graph` | a code-graph tool call (an `mcp__…codegraph…` tool) | `.no-graph` — a missing binary is `idx`'s report, not this mark's |
 | `orch` | a delegate call (`Task`/`Agent`/`spawn_agent`) or a subagent start | `orchestrate-off` |
 | `judge` | a shell command really ran `tezgah-triage` or `tezgah-docs` | `judge-off`, or no credential: no `TYPESAFE_API_KEY` and no non-empty `~/.config/typesafe/key`, and neither the fallback's `OPENROUTER_API_KEY` nor its `~/.config/openrouter/key` |
-| `gate` | never `on`: shown only as `gate✗`, right after the version, in two cases. One: the prompt hook found at least 3 gated calls in this session's transcript since its first turn: write and shell calls, every one of which the gate answers with a `began` or a `deny` row (Bash/PowerShell/Edit/Write/MultiEdit/NotebookEdit on Claude, `exec_command`/`shell`/`apply_patch` on Codex). Over the same span the ledger holds no row from the gate. A PostToolUse row is no proof: that hook keeps writing while a broken PreToolUse lets every call through. The same prompt carries the line "tezgah gate inactive on this host: ...". Two: a kill switch appeared after the session's first prompt; the prompt hook writes one `disarm` row naming it (`disarmed`, baseline `<cache>/switches/<session>.json`). Mark file `<cache>/gate-inactive/<session>` (`gate_inactive`, audit Phase 1.3) | a row from the gate appears and no switch armed mid-session is still armed |
-| `drift` | never `on`: shown as `drift✗` when a session start found tezgah's own hook entries changed since install (`hooks/tezgah_attest.py::run`). One mark per session and host, `<cache>/harness-drift/<session hash>.<host>`; the session's `attest` row names what drifted | the next clean start of that host in that session |
-| `crash` | never `on`: shown as `crash✗` when a hook of this session could not import its core and ran without tezgah (`hooks/tezgah_guard.py::import_failed`, mark `~/.cache/tezgah/import-crash/<session hash>`). When `tezgah_context` itself is the module that failed, `statusline.py` prints `tezgah ✗ core import failed` instead of the line | never by itself: the mark stays for the session |
+| `gate` | never `on`: shown only as `gate✗`, right after the version, in two cases. One: the prompt hook found at least 3 gated calls in this session's transcript since its first turn: write and shell calls, every one of which the gate answers with a `began` or a `deny` row (Bash/PowerShell/Edit/Write/MultiEdit/NotebookEdit on Claude, `exec_command`/`shell`/`apply_patch` on Codex). Over the same span the ledger holds no row from the gate. A PostToolUse row is no proof: that hook keeps writing while a broken PreToolUse lets every call through. The same prompt carries the line "tezgah gate inactive on this host: ...". Two: a kill switch appeared after the session's first prompt; the prompt hook writes one `disarm` row naming it (`disarmed`, baseline a `switches` row of `<cache>/tezgah.db`). The mark is a `gate_inactive` row of the same database (`gate_inactive`, audit Phase 1.3) | a row from the gate appears and no switch armed mid-session is still armed |
+| `drift` | never `on`: shown as `drift✗` when a session start found tezgah's own hook entries changed since install (`hooks/tezgah_attest.py::run`). One mark per session and host, a `harness_drift` row of `<cache>/tezgah.db` keyed `<session hash>.<host>`; the session's `attest` row names what drifted | the next clean start of that host in that session |
+| `crash` | never `on`: shown as `crash✗` when a hook of this session could not import its core and ran without tezgah (`hooks/tezgah_guard.py::import_failed`, mark an `import_crash` row of `~/.cache/tezgah/tezgah.db` keyed `<session hash>`). When `tezgah_context` itself is the module that failed, `statusline.py` prints `tezgah ✗ core import failed` instead of the line | never by itself: the mark stays for the session |
 
 Read `on` for `consult`/`research`/`judge` as "installed and usable", not "you
 must use it": a missing key or binary reads the same red as a kill switch
@@ -147,9 +147,9 @@ have written: a mark the literal omits reads `info` there rather than a claim.
 
 ## The used-kinds channel
 
-A used measure is one append to the session store,
-`<cache_dir>/sessions/<slug(session_id)>.jsonl`, one `{"kind": …}` per line
+A used measure is one row of the session store, keyed by `slug(session_id)` and kind
 (`record()`, `hooks/tezgah_context.py::record`; `used()` reads it back, `hooks/tezgah_context.py::used`).
+The store is the `used` table of `<cache_dir>/tezgah.db`.
 `cache_dir()` is `~/.cache/tezgah` with a temp fallback for sandboxed hosts
 (`hooks/tezgah_paths.py::CACHE`, `hooks/tezgah_paths.py::fallback_cache`, `hooks/tezgah_paths.py::cache_dir`); a missing kind is not an event, so only
 the five kinds are ever written (`hooks/tezgah_context.py::record`).
@@ -160,8 +160,8 @@ the command really ran it (34-38,84) and is the one writer that can earn `judge`
 (a run of `bin/tezgah-triage` or `bin/tezgah-docs`, `shell_kind`, `hooks/tezgah_context.py::shell_kind`)
 — plus `hooks/projects-auto-init.py::main`
 (`orch` on subagent start), `hosts/codex/hook.py::main`,
-`hosts/cursor/hook.py::dispatch`, hosts/opencode/plugins/tezgah.js:2123-2130,
-hosts/opencode/plugins/tezgah.js:2669, `hosts/omp/hook.py::handle`. Both Claude (hooks/hooks.json) and dsh
+`hosts/cursor/hook.py::dispatch`, hosts/opencode/plugins/tezgah.js:2144-2151,
+hosts/opencode/plugins/tezgah.js:2702, `hosts/omp/hook.py::handle`. Both Claude (hooks/hooks.json) and dsh
 (hosts/dsh/hooks.json) wire PostToolUse to that one shared hook, which is how dsh
 gets any used mark at all: with no local transcript, the store is the only channel
 its line has (hooks/projects-posttooluse.py:33-37).

package/hooks/tezgah_attest.py

@@ -27,6 +27,7 @@ import json
 import os
 
 import tezgah_paths as tp
+import tezgah_store
 
 ROOT = tp.PLUGIN_ROOT
 CONTRACT_SHA = os.path.join(tp.CONFIG_DIR, "contract.sha256")
@@ -194,13 +195,13 @@ def drift(host, root=ROOT, shas=None):
     return found, unknown
 
 
-def drift_mark(session_id, host):
-    """The mark one host's drifted session start leaves; its text is the drift
-    list. Keyed by session AND host: two hosts can share a session id (a
-    `tezgah-context attest` run by hand, a host whose ids collide), and a clean
-    start on one must not clear the other's mark."""
-    return os.path.join(tp.cache_dir(), "harness-drift", "%s.%s" % (
-        hashlib.sha256(str(session_id).encode()).hexdigest()[:16], host))
+def drift_key(session_id, host):
+    """The key of the mark one host's drifted session start leaves in the
+    `harness_drift` store; its value is the drift list. Keyed by session AND
+    host: two hosts can share a session id (a `tezgah-context attest` run by
+    hand, a host whose ids collide), and a clean start on one must not clear
+    the other's mark."""
+    return "%s.%s" % (hashlib.sha256(str(session_id).encode()).hexdigest()[:16], host)
 
 
 def mark_text(session_id):
@@ -209,11 +210,8 @@ def mark_text(session_id):
         return ""
     texts = []
     for host in CODE_TARGETS:
-        try:
-            with open(drift_mark(session_id, host), encoding="utf-8") as fh:
-                text = fh.read().strip()
-        except OSError:
-            continue
+        text = tezgah_store.doc("harness_drift", drift_key(session_id, host))
+        text = text.strip() if isinstance(text, str) else ""
         if text and text not in texts:
             texts.append(text)
     return "; ".join(texts)
@@ -242,14 +240,9 @@ def run(host, session_id, cwd=None):
     import tezgah_integrity
     tezgah_integrity.note(session_id, "attest", detail, host=host,
                           switches=",".join(switches()) or None)
-    mark = drift_mark(session_id, host)
-    try:
-        if found:
-            os.makedirs(os.path.dirname(mark), exist_ok=True)
-            with open(mark, "w", encoding="utf-8") as fh:
-                fh.write("; ".join(found) + "\n")
-        elif os.path.exists(mark):
-            os.remove(mark)
-    except OSError:
-        pass
+    key = drift_key(session_id, host)
+    if found:
+        tezgah_store.put_doc("harness_drift", key, "; ".join(found))
+    else:
+        tezgah_store.drop("harness_drift", key)
     return found

package/hooks/tezgah_context.py

@@ -17,7 +17,8 @@ import time
 import tezgah_embed
 import tezgah_orca
 import tezgah_research
-from tezgah_guard import import_crash_mark
+import tezgah_store
+from tezgah_guard import import_crash_key
 from tezgah_integrity import (STEP_KINDS, _heredocs, _path as _ledger_path,
                               _shell_segments, bind_session,
                               changed_files, cut, last_check, note,
@@ -1055,32 +1056,18 @@ def state_stamp(root):
             "lessons": _lessons_state(root)}
 
 
-def _stamp_path(session_id):
-    return os.path.join(cache_dir(), "turns", slug(str(session_id)) + ".json")
-
-
 def read_stamp(session_id):
     """The stamp this session's previous turn wrote, or None when there is none."""
     if not session_id:
         return None
-    try:
-        with open(_stamp_path(session_id), encoding="utf-8") as fh:
-            got = json.load(fh)
-    except (OSError, ValueError):
-        return None
+    got = tezgah_store.doc("turns", slug(str(session_id)))
     return got if isinstance(got, dict) and got.get("root") else None
 
 
 def write_stamp(session_id, root, stamp):
     """Remember this turn's stamp. Best effort: a host may sandbox hook writes."""
-    if not session_id:
-        return
-    try:
-        os.makedirs(os.path.join(cache_dir(), "turns"), exist_ok=True)
-        with open(_stamp_path(session_id), "w", encoding="utf-8") as fh:
-            json.dump(dict(stamp, root=root), fh)
-    except OSError:
-        pass
+    if session_id:
+        tezgah_store.put_doc("turns", slug(str(session_id)), dict(stamp, root=root))
 
 
 def forget_seen(session_id):
@@ -1627,10 +1614,11 @@ POST_TOOL_ROWS = frozenset(k.encode() for k in STEP_KINDS + ("external", "unknow
 
 
 def _ledger_lines(path):
+    """The ledger's rows at `path` as their JSON bytes, oldest first."""
     try:
-        with open(path, "rb") as fh:
-            return fh.read().split(b"\n")
-    except OSError:
+        return [text.encode("utf-8", "replace")
+                for text in tezgah_store.evidence_rows(path)]
+    except tezgah_store.ERRORS:
         return []
 
 
@@ -1672,12 +1660,10 @@ def _ledger_since(session_id):
     return None, False
 
 
-def _gate_mark(session_id):
-    return os.path.join(cache_dir(), "gate-inactive", slug(str(session_id)))
-
-
-def _switch_baseline(session_id):
-    return os.path.join(cache_dir(), "switches", slug(str(session_id)) + ".json")
+def gate_marked(session_id):
+    """True when the prompt hook left the disarmed-gate mark for this session
+    (`gate_inactive`)."""
+    return tezgah_store.marked("gate_inactive", slug(str(session_id)))
 
 
 def disarmed(session_id):
@@ -1694,24 +1680,17 @@ def disarmed(session_id):
     # the files alone (`armed`, unlatched): a switch the latch ignores is still
     # the tamper shape this records
     now = sorted(n for n in SWITCHES if armed(n))
-    path = _switch_baseline(session_id)
+    state = tezgah_store.doc("switches", slug(str(session_id)))
     try:
-        with open(path, encoding="utf-8") as fh:
-            state = json.load(fh)
         start, seen = list(state["start"]), list(state["seen"])
-    except (OSError, ValueError, KeyError, TypeError):
+    except (KeyError, TypeError):
         start, seen = now, []
     moved = [n for n in now if n not in start]
     for name in moved:
         if name not in seen:
             note(session_id, "disarm", name)
             seen.append(name)
-    try:
-        os.makedirs(os.path.dirname(path), exist_ok=True)
-        with open(path, "w", encoding="utf-8") as fh:
-            json.dump({"start": start, "seen": seen}, fh)
-    except OSError:
-        pass
+    tezgah_store.put_doc("switches", slug(str(session_id)), {"start": start, "seen": seen})
     return moved
 
 
@@ -1730,14 +1709,13 @@ def gate_inactive(session_id, payload):
         calls = 0 if since is None or rows else _transcript_calls(
             p.get("transcript_path"), since)
     inactive = calls >= GATE_MIN_CALLS
-    mark = _gate_mark(session_id)
+    key = slug(str(session_id))
     try:
         if inactive or moved:
-            os.makedirs(os.path.dirname(mark), exist_ok=True)
-            open(mark, "w", encoding="utf-8").close()
-        elif os.path.exists(mark):
-            os.remove(mark)
-    except OSError:
+            tezgah_store.mark("gate_inactive", key)
+        else:
+            tezgah_store.drop("gate_inactive", key)
+    except tezgah_store.ERRORS:
         pass
     return GATE_INACTIVE % calls if inactive else ""
 
@@ -2202,6 +2180,18 @@ def context_for(event, cwd, payload=None, with_core=True):
                 taste = ""
             if taste:
                 parts.append(("taste", taste))
+        # Armed taste learns by itself: a detached `learn` when the signals grew,
+        # at most hourly (tezgah_taste.learn_later); session start only, with the
+        # root `enabled` already resolved above.
+        if taste_root and event == "session_start":
+            try:
+                tezgah_taste.learn_later(taste_root)
+            except Exception:
+                pass
+        # The legacy JSONL ledgers into the evidence database: a detached
+        # bulk import at most daily (tezgah_store.import_later).
+        if event == "session_start":
+            tezgah_store.import_later(cache_dir())
         broken = tezgah_research.failing(root) if not off("research-off") else []
         if broken:
             line_slug, err = broken[0]
@@ -2400,62 +2390,22 @@ def record(session_id, kind):
     if kind == "orch":
         note(session_id, "orch")
     try:
-        d = os.path.join(cache_dir(), "sessions")
-        os.makedirs(d, exist_ok=True)
-        with open(os.path.join(d, slug(session_id) + ".jsonl"), "a", encoding="utf-8") as fh:
-            fh.write(json.dumps({"kind": kind}) + "\n")
-    except OSError:
+        tezgah_store.use(slug(session_id), kind)
+    except tezgah_store.ERRORS:
         pass
 
 
-# Past this size `used()` compacts the store to one row per kind. Every reader
-# of the store takes it as a set, so nothing is lost, and the next read is a
-# few hundred bytes however long the session ran.
-USED_MAX_BYTES = 65536
-
-
 def used(session_id):
-    if not session_id:
-        return set()
-    out = set()
-    path = os.path.join(cache_dir(), "sessions", slug(session_id) + ".jsonl")
-    try:
-        with open(path, encoding="utf-8") as fh:
-            size = os.fstat(fh.fileno()).st_size
-            for line in fh:
-                try:
-                    out.add(json.loads(line)["kind"])
-                except (ValueError, KeyError):
-                    pass
-        # a row appended since the open changes the size: skip, never lose it
-        if size > USED_MAX_BYTES and os.path.getsize(path) == size:
-            tmp = path + ".tmp"
-            with open(tmp, "w", encoding="utf-8") as fh:
-                fh.writelines(json.dumps({"kind": k}) + "\n"
-                              for k in sorted(k for k in out
-                                              if isinstance(k, str)))
-            os.replace(tmp, path)
-    except OSError:
-        pass
-    return out
+    """The kinds this session recorded, a set (one `used` row per kind)."""
+    return tezgah_store.used(slug(session_id)) if session_id else set()
 
 
-# How many of the newest recorded session files a fitness report reads. A row is
-# `{"kind": kind}` and carries no timestamp, so the window can only be files by
-# mtime - the moment the session last recorded anything, which for a used-kind
-# store is its last event.
+# How many of the sessions that recorded last a fitness report reads, by the
+# time each last recorded anything, which for a used-kind store is its last
+# event.
 FITNESS_WINDOW = 200
 
 
-def _mtime(path):
-    """A file's mtime, or 0 when it is gone: the window is a sort key, and a
-    session that vanished mid-report must not crash the report."""
-    try:
-        return os.path.getmtime(path)
-    except OSError:
-        return 0.0
-
-
 def skill_fitness(window=FITNESS_WINDOW):
     """Which shipped skills the recorded sessions opened, and which opened none.
 
@@ -2466,45 +2416,29 @@ def skill_fitness(window=FITNESS_WINDOW):
     skill a read opened). This is a measurement, not a gate - it names the
     candidates, and retiring one stays the owner's call.
 
-    The window is the newest `window` session files by mtime, because the rows
-    carry no timestamp. A session counts as having opened a skill when it
+    The window is the `window` sessions that recorded last. A session counts
+    as having opened a skill when it
     recorded that skill's kind: `skill:<name>`, or the mark the status line draws
     for the two marked skills, so reads recorded before `SKILL_KIND` existed
     still count. Sessions on a host that cannot see a read record neither, and
     the report cannot tell that session from one that read nothing - the number
     is a floor, not a census.
 
-    Returns `sessions` and `recorded` (the files read and the files present),
-    `skills` (the opened ones ranked by session count, each with the mark the
-    line draws for it, or None), and `never` (the shipped skills no session in
-    the window opened)."""
+    Returns `sessions` and `recorded` (the sessions read and the sessions
+    recorded), `skills` (the opened ones ranked by session count, each with the
+    mark the line draws for it, or None), and `never` (the shipped skills no
+    session in the window opened)."""
     catalog = shipped_skills()
-    d = os.path.join(cache_dir(), "sessions")
-    try:
-        files = sorted((os.path.join(d, n) for n in os.listdir(d)
-                        if n.endswith(".jsonl")),
-                       key=_mtime, reverse=True)
-    except OSError:
-        files = []
+    window_kinds, recorded = tezgah_store.used_sessions(window)
     opened = {}
-    for path in files[:window]:
-        kinds = set()
-        try:
-            with open(path, encoding="utf-8") as fh:
-                for line in fh:
-                    try:
-                        kinds.add(json.loads(line)["kind"])
-                    except (ValueError, KeyError, TypeError):
-                        pass  # a torn line, the way `used` reads one
-        except OSError:
-            continue
+    for kinds in window_kinds:
         for name in catalog:
             mark = SKILL_MARKS.get(name)
             if (SKILL_KIND + name) in kinds or (mark and mark in kinds):
                 opened[name] = opened.get(name, 0) + 1
     return {
-        "sessions": len(files[:window]),
-        "recorded": len(files),
+        "sessions": len(window_kinds),
+        "recorded": recorded,
         "skills": [{"name": name, "mark": SKILL_MARKS.get(name),
                     "sessions": count}
                    for name, count in sorted(opened.items(),
@@ -2793,7 +2727,7 @@ def health_segments(cwd, session_id=None, used_override=None, idx_override=None,
     segs = with_update_notice(version_segment())
     # Shown only when the prompt hook found the gate disarmed (gate_inactive):
     # first, because it says every other mark is not being enforced.
-    if session_id and os.path.exists(_gate_mark(session_id)):
+    if session_id and gate_marked(session_id):
         segs.append({"key": "gate", "state": "off", "glyph": GLYPHS["off"],
                      "text": "gate", "group": 0})
     # Shown when this session's start found tezgah's own hook entries changed
@@ -2811,7 +2745,7 @@ def health_segments(cwd, session_id=None, used_override=None, idx_override=None,
                      "text": "drift", "group": 0})
     # A hook of this session could not import its core (tezgah_guard.
     # import_failed): it failed open, so what it guards did not run.
-    if session_id and os.path.exists(import_crash_mark(session_id)):
+    if session_id and tezgah_store.doc("import_crash", import_crash_key(session_id)) is not None:
         segs.append({"key": "crash", "state": "off", "glyph": GLYPHS["off"],
                      "text": "crash", "group": 0})
     for name, on, meas in flags:

package/hooks/tezgah_gate.py

@@ -98,6 +98,8 @@ import re
 import shlex
 import time
 
+import tezgah_store
+
 from tezgah_integrity import (BASH_TOOLS, BEGAN_KIND, ENV_WORD, GIT_VALUE_OPTS,
                               HEREDOC_RISK, HOOKS_KEY, PATCH_FILE,
                               PLAIN_TAIL, SECRET_PREFIXED, STEP_KINDS,
@@ -587,25 +589,22 @@ def git_head(repo):
     return None
 
 
-def nudge_mark(session_id):
-    """The once-per-session mark: sha1(id)[:16], the key opencode's oncePerSession writes."""
-    return os.path.join(cache_dir(), "nudged", hashlib.sha1(
-        (session_id or "nosession").encode("utf-8")).hexdigest()[:16])
+def nudge_key(session_id):
+    """The once-per-session mark's key in the `nudged` store: sha1(id)[:16],
+    the key opencode's oncePerSession writes."""
+    return hashlib.sha1((session_id or "nosession").encode("utf-8")).hexdigest()[:16]
 
 
 def first_nudge(session_id):
     """Consume the once-per-session nudge. False when already spent/unwritable.
 
-    The mark lands in cache_dir(), so a sandboxed host (dsh) still gets the
-    one-shot nudge instead of the write failing open."""
-    mark = nudge_mark(session_id)
-    if os.path.exists(mark):
-        return False
+    The mark lands in cache_dir()'s database, so a sandboxed host (dsh) still
+    gets the one-shot nudge instead of the write failing open. One INSERT, so
+    of two calls at once exactly one is first."""
     try:
-        os.makedirs(os.path.dirname(mark), exist_ok=True)
-        open(mark, "w", encoding="utf-8").close()  # consume BEFORE denying: later greps pass
-        return True
-    except OSError:
+        # consume BEFORE denying: later greps pass
+        return tezgah_store.mark("nudged", nudge_key(session_id))
+    except tezgah_store.ERRORS:
         return False
 
 
@@ -1841,11 +1840,13 @@ HOOK_ENTRIES = frozenset(("projects-auto-init", "projects-pretooluse",
 HOOK_HOSTS = frozenset(("codex", "cursor", "omp"))
 # Programs that change a path named in their arguments. Every positional is a
 # target, except for the copiers, whose last one is (`cp switch /tmp` reads it).
-# `sed`/`perl` count only with an in-place flag.
+# `sed`/`perl` count only with an in-place flag. `sqlite3` rewrites the cache
+# stores, rows of `tezgah.db`, as `rm` would remove the files they were; its
+# SQL argument names no protected path.
 CONTROL_PROGRAMS = frozenset(("touch", "rm", "rmdir", "unlink", "shred",
                               "truncate", "chmod", "chown", "chgrp", "mv",
                               "mkdir", "tee", "cp", "ln", "install", "rsync",
-                              "dd", "sed", "perl"))
+                              "dd", "sed", "perl", "sqlite3"))
 CONTROL_COPIERS = frozenset(("cp", "mv", "ln", "install", "rsync"))
 # The programs that remove, disable or move a path. A directory that holds
 # protected state, a repository's husky hooks and the open plans (evidence) are
@@ -1867,13 +1868,15 @@ SHELL_NAMES = frozenset(("sh", "bash", "zsh", "dash", "ksh"))
 SHELL_KEYWORDS = frozenset(("if", "then", "elif", "else", "do", "while",
                             "until", "!", "{", "time"))
 SHELL_OPS = re.compile(r"^[;&|()<>]+$")
-# The cache subtrees whose rows the rules read: the evidence ledger, the session
-# store, the switch baseline (tezgah_context.disarmed), the gate mark, and the
-# marks the status line reads for a drifted hook entry
-# (tezgah_attest.drift_mark) and a core that failed to import
-# (tezgah_guard.import_crash_mark).
-CONTROL_CACHE = ("evidence", "sessions", "switches", "gate-inactive",
-                 "harness-drift", "import-crash", "workspace-index.json")
+# The cache subtrees whose rows the rules read: the cache database with its WAL
+# files (the evidence ledger, the used-kind marks, the switch baselines of
+# tezgah_context.disarmed, the gate mark, and the marks the status line reads
+# for a drifted hook entry and a core that failed to import), the evidence
+# JSONL files it imports, and the files the other stores it imports once
+# (tezgah_store.CACHE_LEGACY) had, until that import reads them.
+CONTROL_CACHE = ("evidence", "tezgah.db", "tezgah.db-wal", "tezgah.db-shm", "sessions",
+                 "switches", "gate-inactive", "harness-drift", "import-crash",
+                 "workspace-index.json")
 # Top-level keys tezgah writes into Claude's settings (bin/tezgah-setup
 # wire_claude_statusline, wire_claude_attribution), and the one that turns every
 # hook off at once; any other key or entry is tezgah's only when it names tezgah.
@@ -2830,7 +2833,7 @@ def _dry_decision(tool, inp, cwd, session_id, agent=None):
 
     g.update(note=lambda *a, **k: None, write_taint=lambda *a, **k: None,
              capture=None,
-             first_nudge=lambda sid: not os.path.exists(nudge_mark(sid)))
+             first_nudge=lambda sid: not tezgah_store.marked("nudged", nudge_key(sid)))
     try:
         return decision(tool, inp, cwd, session_id, agent=agent)
     finally: