opencode-dejavu 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 2.2.0 — 2026-08-23
+
+### Added
+- Interpreter one-liner fingerprinting: `python -c` / `node -e` / `bun -e` and friends get their code payload hashed (`<code:sha1-8>`) instead of flattened to `<str>` — distinct scripts no longer share one gate, the same script failing repeatedly still converges.
+- Global cross-project pattern index (`index.json`): counts distinct project dirs per failure key and now drives global escalation — a gate's own `projects` array only ever sees its own store, so escalation was dead code before.
+- `mergeGate`: evidence merge for escalation and dedupe; never demotes a `blocking` gate.
+- `isNoiseError()`: aborted/cancelled tool executions ("Tool execution aborted") are infrastructure noise and are no longer counted as failures.
+- Self-healing stores (`src/validate.ts` invariant layer): every gate read from disk crosses strict parse + mechanical repair; `GateStore.reconcile()` quarantines unparseable gates.json (bytes preserved as `.corrupt-<ts>`), merges duplicate keys, excises unparseable log lines to `log.jsonl.corrupt`; `Stores.reconcileAll()` reconciles the index (prunes orphans, rebuilds missing entries, escalates gates proven in 2+ projects) — runs at every init.
+- `doctor.ts [--repair]` now checks the full invariant set (shape, duplicates, temporal order, nested-token corruption, blocking without evidence, index consistency, stale project copies, missed escalation, log integrity) and heals on demand.
+
+### Changed
+- `canBlock()` rejects bare one-liner shapes (`-c <str>`); existing gates with them are auto-demoted by `migrate()`.
+- Log appends and rotation run under their own lock with atomic writes — concurrent OpenCode windows no longer interleave broken JSONL lines.
+- `migrate()` merges project-local copies of already-global keys into the global gate.
+- `doctor.ts`: NOT-TEACHING/ANNOYING only flag gates that can actually block; non-blockable legacy gates no longer scream.
+
+### Fixed
+- All-digit `<code:...>` fingerprints are no longer re-parameterized by the number rule (~2.3% of payloads collapsed into one key).
+- Signatures with different `<code:...>` fingerprints can no longer fuzzy-merge (random hashes differing in exactly 3 chars passed the distance rule and merged unrelated one-liners).
+- `doctor.ts` no longer crashes on corrupt log lines; it now reports them as a CORRUPT LOG LINES pathology instead.
+- Init failures (corrupt store, failed migrate) are logged instead of swallowed — a plugin starting on broken state is now visible.
+
 ## 2.1.0 — 2026-08-22
 
 First public release.

package/README.md

@@ -28,7 +28,7 @@ Design decisions (post-mortem of existing approaches):
 - **Remind first, block on repeat.** Pure blocking starts an arms race — the agent routes around gates (`npm` blocked → uses `pnpm`). A reminder with the correction teaches; the block is reserved for ignored reminders.
 - **Gate messages are teachers.** Every message carries `CORRECTION:` (what to do instead) and `EVIDENCE:` (N failures across M sessions), not just a prohibition.
 - **Mechanical pattern-keys only.** No LLM-based error classification in the hot path — the unreliable component doesn't do reliability work.
-- **Two scopes.** Repo-specific gotchas live in `<repo>/.opencode/dejavu/` (committable); patterns seen in 2+ project dirs are agent-level habits and move to `~/.config/opencode/dejavu/`.
+- **Two scopes.** Repo-specific gotchas live in `<repo>/.opencode/dejavu/` (committable); patterns seen in 2+ project dirs are agent-level habits and move to `~/.config/opencode/dejavu/`. No single store can see all projects, so a global pattern index (`index.json`) counts distinct project dirs per key and drives the escalation.
 - **Gates rot — so they expire.** 60 days without recurrence and a gate is dropped. A gate firing 10+ times while the error stopped gets `review: true` for manual inspection.
 - **The metric is recurrence-after-gate.** Tracked per gate as `recurredAfterGate` — if gates don't reduce recurrence, the whole approach is wrong and you'll see it in the data.
 
@@ -61,18 +61,21 @@ Restart OpenCode. Gates appear automatically as failures recur — nothing to co
 ## Robustness & safety
 
 - **Blocking policy** — only `bash` commands that are NOT diagnostics may ever become blocking gates. File probes (read/edit/write/glob/grep) and diagnostics (tsc/eslint/pytest/gradle-test/flutter/curl/grep...) stay `watching` forever: measured, visible in reports, but never interrupting the agent. `canBlock()` in `src/patterns.ts` is the single source of truth.
+- **One-liner identity** — for `python -c` / `node -e` / `bun -e` and friends the code payload IS the call, so it is fingerprinted (`<code:hash>`) instead of flattened to `<str>`: different scripts never share a gate, the same script failing repeatedly still converges. Legacy bare `-c <str>` shapes can never block.
 - **Secret scrubbing** — every signature and snippet passes `scrubSecrets()` (OpenAI/Anthropic/AWS/GitHub/Slack/Stripe/JWT/bearer/DB-conn-string/PEM patterns + `root@host`) before touching disk. Historical data is cleaned by `migrate()` at init or via `bun scripts/migrate.ts <dirs...>` (also scrubs logs).
 - **Intended non-zero exits** — exit 1 from diagnostics is NOT a failure (that is their normal "found nothing / found issues" outcome). Exit ≥ 2 always counts.
+- **Aborted ≠ failed** — cancelled/aborted tool executions ("Tool execution aborted") are infrastructure noise and are never counted as failures.
 - **File content is not command output** — text failure signatures are scanned for `bash` only; `read`/`edit`/`write` failures come exclusively from the event channel (a file containing "TypeError" is not a failure).
-- **Concurrency** — gates.json mutations run under an exclusive lockfile; writes are tmp+rename with EPERM/EACCES/EBUSY retry (Windows AV/indexer). NT long paths get the `\\?\` prefix.
+- **Concurrency** — gates.json mutations run under an exclusive lockfile; log appends and rotation take their own lock (every OpenCode window shares the global log); writes are tmp+rename with EPERM/EACCES/EBUSY retry (Windows AV/indexer). NT long paths get the `\\?\` prefix.
 - **Near-duplicate consolidation** — new failures merge into existing patterns via normalized Levenshtein ≤ 0.3 with an absolute floor of 3 edits (replaces token Jaccard, which collapsed all `<str>` placeholders; the floor stops `git push` vs `git pull`-style merges).
 - **Bounded memory** — per-session maps are capped (200 sessions) and freed on `session.deleted`; handled part IDs evict FIFO; TTL expiry re-runs every 6 h in long-lived processes.
-- **Migration** — gates outside the blocking policy are demoted to `watching` automatically; nothing is deleted.
+- **Migration** — gates outside the blocking policy are demoted to `watching` automatically; project copies of already-global gates are merged into the global gate (evidence is consolidated, never deleted).
+- **Self-healing** — every init reconciles the stores: an unparseable `gates.json` is quarantined (bytes preserved as `gates.json.corrupt-<ts>`), gate records are strictly parsed and mechanically repaired (inverted dates swapped, duplicate keys merged, secrets re-scrubbed, stale blocking demoted), unparseable log lines are excised to `log.jsonl.corrupt`, and the cross-project index is reconciled. Every repair is logged as a `repaired`/`quarantined` event.
 
 ## Observability (debugging aids)
 
 - Every `log.jsonl` gets an `init` event with `PLUGIN_VERSION`; `detected` events carry `channel` (`exit`/`text`/`event`) and the raw exit code; `reminded`/`blocked` carry `via` (`exact`/`fuzzy`/`segment`). Stale plugin sessions are therefore visible in the data.
-- `bun scripts/doctor.ts [projectDirs...]` — one-command pathology report: blocking gates outside policy, not-teaching gates (recurredAfterGate ≥ 3), annoying gates (reminded ≥ 10), secrets on disk, version drift.
+- `bun scripts/doctor.ts [--repair] [projectDirs...]` — one-command report over every invariant the data model implies: gate shape, duplicate keys, temporal order, nested-token corruption, blocking without evidence, policy violations, index↔gates consistency, stale project copies, missed escalation, log integrity, secrets, version drift. `--repair` heals first (idempotent), then reports.
 - `bun scripts/analyze.ts [projectDirs...]` — store summary: statuses, tools, top patterns.
 - `/dejavu` command (installed globally) runs doctor first, then reports.
 
@@ -93,8 +96,10 @@ Not covered (by design, v1): semantically-equivalent-but-syntactically-different
 | File | Contents |
 |---|---|
 | `~/.config/opencode/dejavu/gates.json` | global gates (agent habits) |
+| `~/.config/opencode/dejavu/index.json` | cross-project pattern index: which project dirs each failure key was seen in (escalation evidence) |
 | `<repo>/.opencode/dejavu/gates.json` | project gates (repo gotchas) |
-| `*/dejavu/log.jsonl` | every event: detected, promoted, reminded, blocked, override, expired, recurred-after-gate |
+| `*/dejavu/log.jsonl` | every event: detected, promoted, reminded, blocked, override, expired, recurred-after-gate, repaired, quarantined |
+| `*/dejavu/*.corrupt*` | quarantined corruption (unparseable gates.json, excised log lines) — bytes preserved for forensics; safe to delete after inspection |
 
 Both are human-editable. Removing a gate object disables it. Editing `correction` improves what the agent is told.
 

package/index.ts

@@ -6,6 +6,7 @@ import {
   callSignature,
   detectFailure,
   isIntendedNonzero,
+  isNoiseError,
   parameterizeError,
   patternKey,
   scrubSecrets,
@@ -105,15 +106,19 @@ export const Dejavu: Plugin = async ({ directory, client }) => {
     }
   }
 
-  // Init: migrate old data, expire stale gates, rotate logs, warm the caches.
+  // Init: heal structural damage, migrate old data, expire stale gates,
+  // rotate logs, warm the caches.
   try {
+    await stores.reconcileAll(GLOBAL_PROJECTS)
     await stores.migrate()
     await stores.expireAll(TTL_DAYS)
     await stores.rotateLogs()
     await stores.logAll({ type: "init", key: "dejavu", version: PLUGIN_VERSION })
     await logClient("info", `dejavu initialized v${PLUGIN_VERSION}`)
-  } catch {
-    // init failures must not prevent hook registration
+  } catch (error) {
+    // init failures must not prevent hook registration — but must be visible,
+    // otherwise a corrupted store silently starts the plugin with no gates
+    await logClient("error", `dejavu init failed: ${error instanceof Error ? error.message : String(error)}`)
   }
 
   // Long-lived processes re-run expiry periodically.
@@ -347,6 +352,8 @@ export const Dejavu: Plugin = async ({ directory, client }) => {
         // Never count our own gate signals as failures — a thrown REMINDER/BLOCK
         // comes back through this channel as a tool error.
         if (errorText.includes("[dejavu]")) return
+        // Aborted/cancelled executions are infrastructure noise, not mistakes.
+        if (isNoiseError(errorText)) return
         const session = typeof p.sessionID === "string" ? p.sessionID : "unknown"
 
         // Prefer the real call signature from the tool input — it keeps the gate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-dejavu",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Cross-session memory prosthesis for OpenCode: detects recurring tool-call failures and promotes them into enforced gates. Remind first, block on same-session repeat offense.",
   "type": "module",
   "main": "index.ts",

package/src/AGENTS.md

@@ -9,29 +9,39 @@ Two dependency-free modules: `patterns.ts` (pure functions — call identity, no
 | Task | File | Symbols |
 |------|------|---------|
 | Call identity / gate keys | patterns.ts | `callSignature` → `normalizeCommand`/`normalizeFilePath` → `patternKey` |
+| Interpreter one-liner identity | patterns.ts | `hashInterpreterPayload` — `-c`/`-e` code payload → `<code:hash>` |
 | Chain-bypass protection | patterns.ts | `splitChain` (quote/paren-aware) → `bashSegmentSignatures` |
 | Free-form error collapsing | patterns.ts | `parameterizeError` (event channel) vs `normalizeCommand` (bash) |
 | Near-duplicate merge | patterns.ts | `fuzzySimilar` = normalized `levenshtein` ≤ 0.3 |
 | Failure text scan | patterns.ts | `detectFailure` + `FAILURE_SIGNATURES` |
+| Noise filtering | patterns.ts | `isNoiseError` + `NOISE_ERRORS` (aborted/cancelled ≠ failed) |
 | Diagnostic/intended-exit logic | patterns.ts | `DIAGNOSTIC_VERBS`, `isIntendedNonzero`, `canBlock` |
-| One scope (gates.json + log.jsonl) | store.ts | `GateStore` — `load`/`save`/`log`/`expire`/`rotateLog` |
-| Two-scope logic + promotion | store.ts | `Stores` — `findGate`/`recordFailure`/`migrate`/`blockingGates` |
+| One scope (gates.json + index.json + log.jsonl) | store.ts | `GateStore` — `load`/`save`/`loadIndex`/`saveIndex`/`log`/`expire`/`extract`/`rotateLog`/`reconcile` |
+| Two-scope logic + promotion | store.ts | `Stores` — `findGate`/`recordFailure`/`migrate`/`blockingGates`/`reconcileAll`; `mergeGate` merges duplicate keys |
+| Gate parse/repair boundary | validate.ts | `coerceGateShape` (strict parse), `repairGate` (mechanical coercion), `hasNestedTokens` (corruption fingerprint) |
 | fs safety | store.ts | `ntPath`, `atomicWrite`, `withLock` |
 
 ## INVARIANTS (do not break)
 
 - Rule order in `PARAM_RULES` matters: quoted strings first, specific tokens (uuid/sha/ip/url/date), generic numbers last — reordering fragments signatures
 - `scrubSecrets()` runs on every string before it touches disk; `recordFailure` re-scrubs defensively
-- `canBlock(tool, sig)` = `tool === "bash" && !diagnostic` — the ONLY path to `blocking`; probe tools use `PROMOTE_COUNT_PROBE` and never block
+- `canBlock(tool, sig)` = bash && non-diagnostic && not a bare one-liner shape — the ONLY path to `blocking`; probe tools use `PROMOTE_COUNT_PROBE` and never block
 - `DIAGNOSTIC_VERBS` serves two callers (exit-1 allowlist + blocking policy) — one list, two uses; edit knowing both move
-- Lock order is always project → global (see `recordFailure` escalation) — reversing deadlocks
+- Lock order is always project → global, gates → index (see `recordFailure` escalation) — reversing deadlocks; the log lock is separate and leaf-level
+- Cross-project evidence lives ONLY in the global `index.json` — a gate's own `projects` array sees one store and never drives escalation alone
 - Inside `runLocked` always `load(true)`; unlocked `load()` peeks are routing hints only, never a basis for mutation
 - `GateStore.load` caches by mtime — after external edits the cache refreshes on next stat; `save()` refreshes it manually
+- Log appends and rotation take the log lock — every OpenCode window shares the global log; unlocked appends interleave into broken JSON
+- Every gate read from disk crosses `coerceGateShape` + `repairGate` in `load()` — enforcement never sees raw state; hopeless records are dropped, repairable ones coerced
+- Quarantine preserves bytes: unparseable files are renamed to `*.corrupt-*`, never deleted; every repair emits a `repaired`/`quarantined` log event
 - Fuzzy matching is Levenshtein-based on purpose: token Jaccard collapsed all `<str>` placeholders into one bucket; ratio ≤ 0.3 PLUS absolute distance ≥ 3 (verb-level-different commands must never merge)
 
 ## ANTI-PATTERNS
 
 - Do NOT add a tool to `callSignature` without deciding its class: `PROBE_TOOLS` (higher bar, never blocks) or bash-class
 - Do NOT widen `FAILURE_SIGNATURES` to cover file-tool output — that text is file content; extend the event channel instead
+- Do NOT flatten interpreter one-liner payloads to `<str>` — `hashInterpreterPayload` must run before string parameterization; a bare `-c <str>` gate would block the whole command family
+- Do NOT count aborted/cancelled executions as failures — filter with `isNoiseError()` at the event channel
+- Do NOT widen `coerceGateShape` drop rules casually — records it deems hopeless are silently dropped on every load; a bad rule silently empties stores
 - Do NOT write gates.json directly — always `runLocked` + `save()` (atomicWrite); logs are append-only via `log()`
 - Do NOT let `withLock` throw on contention — it degrades to unlocked after `LOCK_WAIT_MS` by design (pipeline must not hang)

package/src/patterns.ts

@@ -43,6 +43,27 @@ export function scrubSecrets(text: string): string {
 
 // --- Normalization -----------------------------------------------------------
 
+/**
+ * Interpreter one-liners: the quoted argument IS the program. Parameterizing
+ * it to <str> collapsed every script into one key — "python -c <str>" ended up
+ * blocking ALL python -c calls after three unrelated failures. Fingerprint the
+ * payload instead: same code = same key, different code = different key.
+ * Secrets are scrubbed before hashing so they neither persist nor fragment.
+ */
+const INTERPRETER_ONELINER =
+  /(?:^|[|;&(\n]\s*)(?:\S+[\\/])?(python3?|node|bun|deno|perl|ruby|pwsh|powershell)(?:\.exe)?(?:\s+-\w+)*\s+(-c|-e|--eval|-command)\s+/i
+
+function hashInterpreterPayload(command: string): string {
+  const match = INTERPRETER_ONELINER.exec(command)
+  if (!match) return command
+  const payload = command.slice(match.index + match[0].length)
+  if (payload.trim() === "") return command
+  // For whole (unchained) commands the payload runs to end of string; chain
+  // segments are normalized separately, so segment keys stay exact.
+  const fingerprint = createHash("sha1").update(scrubSecrets(payload)).digest("hex").slice(0, 8)
+  return `${command.slice(0, match.index + match[0].length)}<code:${fingerprint}>`
+}
+
 /**
  * Normalize a bash command into a stable signature.
  * Paths, numbers, quoted strings, hashes and agent comments are abstracted
@@ -50,11 +71,13 @@ export function scrubSecrets(text: string): string {
  */
 export function normalizeCommand(command: string): string {
   let s = command.replace(COMMENT_LINE, "$1").toLowerCase()
+  s = hashInterpreterPayload(s)
   s = s.replace(/[a-z]:[\\/][^\s"']+/gi, " <path> ")
   s = s.replace(/(^|\s)\/[^\s"']+/g, "$1<path> ")
   s = s.replace(/"[^"]*"|'[^']*'/g, " <str> ")
-  s = s.replace(/\b[0-9a-f]{7,64}\b/gi, " <hash> ")
-  s = s.replace(/\b\d[\d.]*\b/g, " <n> ")
+  // lookbehind: never re-parameterize the <code:...> fingerprint hex
+  s = s.replace(/(?<!<code:)\b[0-9a-f]{7,64}\b/gi, " <hash> ")
+  s = s.replace(/(?<!<code:)\b\d[\d.]*\b/g, " <n> ")
   s = s.replace(/\s+/g, " ").trim()
   return s
 }
@@ -123,6 +146,14 @@ export function isIntendedNonzero(command: string, exitCode: number): boolean {
   return exitCode === 1 && isDiagnosticText(command)
 }
 
+/**
+ * A code flag whose payload was entirely parameterized away (`-c <str>`)
+ * carries no identity — blocking that shape blocks the whole command family.
+ * New one-liners get <code:...> fingerprints in normalizeCommand; this guard
+ * keeps legacy pre-fingerprint gates (and lookalikes) from ever blocking.
+ */
+const GENERIC_ONELINER_SHAPE = /(^|\s)(-c|-e|--eval|-command)\s+(?:@\s+)?<str>(?:\s+@)?\s*$/i
+
 /**
  * Blocking policy: only bash commands that are NOT diagnostics may ever
  * become enforced gates. File probes and diagnostic queries are measured
@@ -130,7 +161,9 @@ export function isIntendedNonzero(command: string, exitCode: number): boolean {
  * punishes normal work.
  */
 export function canBlock(tool: string, signature: string): boolean {
-  return tool === "bash" && !isDiagnosticSignature(signature)
+  if (tool !== "bash") return false
+  if (isDiagnosticSignature(signature)) return false
+  return !GENERIC_ONELINER_SHAPE.test(signature)
 }
 
 // --- Chain splitting ---------------------------------------------------------
@@ -281,14 +314,25 @@ export function levenshtein(a: string, b: string): number {
   return prev[n] ?? 0
 }
 
+/** Code fingerprints are IDENTITY, not data — they must match exactly. */
+const CODE_FINGERPRINTS = /<code:[0-9a-f]+>/g
+
 /**
  * Near-duplicate match: normalized edit distance <= 30% AND absolute distance
  * >= 3. Unlike token-set Jaccard, this does not collapse commands that merely
  * share placeholder tokens; the absolute floor stops verb-level-different
  * commands ("git push <str>" vs "git pull <str>" = distance 2) from merging.
+ * Signatures carrying <code:...> fingerprints only match if the fingerprints
+ * are identical — random hashes differing in 3 chars would otherwise pass the
+ * distance rule and merge unrelated one-liners into one gate.
  */
 export function fuzzySimilar(a: string, b: string): boolean {
   if (a === b) return true
+  const codesA = a.match(CODE_FINGERPRINTS)
+  const codesB = b.match(CODE_FINGERPRINTS)
+  if (codesA !== null || codesB !== null) {
+    if (codesA === null || codesB === null || codesA.join("\u0000") !== codesB.join("\u0000")) return false
+  }
   const maxLen = Math.max(a.length, b.length)
   if (maxLen === 0) return true
   const distance = levenshtein(a, b)
@@ -331,3 +375,22 @@ export function detectFailure(outputText: string): FailureDetection {
   }
   return { matched: false, snippet: "" }
 }
+
+// --- Noise filtering ----------------------------------------------------------
+
+/**
+ * Infrastructure noise, not agent mistakes: aborted/cancelled executions
+ * (user hit stop, background task reaped) teach nothing and fragmented the
+ * store with unactionable patterns. Aborted != failed.
+ */
+const NOISE_ERRORS: RegExp[] = [
+  /tool execution aborted/i,
+  /execution was aborted/i,
+  /\baborted by user\b/i,
+  /\bcancelled by user\b/i,
+  /\bcanceled by user\b/i,
+]
+
+export function isNoiseError(errorText: string): boolean {
+  return NOISE_ERRORS.some((rule) => rule.test(errorText))
+}

package/src/store.ts

@@ -1,9 +1,10 @@
 import { appendFile, mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { canBlock, fuzzySimilar, scrubSecrets } from "./patterns"
+import { coerceGateShape, repairGate } from "./validate"
 
 /** Bumped on behavior changes; stamped into init log events so stale sessions are visible. */
-export const PLUGIN_VERSION = "2.1.0"
+export const PLUGIN_VERSION = "2.2.0"
 
 export interface Gate {
   /** sha1 signature prefix — the pattern identity */
@@ -38,6 +39,17 @@ interface GatesFile {
   gates: Gate[]
 }
 
+/** Cross-project pattern index: which project dirs have seen each key. */
+interface IndexEntry {
+  projects: string[]
+  lastSeen: string
+}
+
+interface IndexFile {
+  version: 1
+  keys: Record<string, IndexEntry>
+}
+
 export type LogEventType =
   | "detected"
   | "promoted"
@@ -48,6 +60,8 @@ export type LogEventType =
   | "expired"
   | "recurred-after-gate"
   | "init"
+  | "repaired"
+  | "quarantined"
 
 export interface LogEvent {
   type: LogEventType
@@ -161,6 +175,8 @@ async function withLock<T>(lockTarget: string, fn: () => Promise<T>): Promise<T>
 export class GateStore {
   private gates: Gate[] | null = null
   private mtimeMs = 0
+  private index: IndexFile | null = null
+  private indexMtimeMs = 0
 
   constructor(public readonly dir: string) {}
 
@@ -172,12 +188,20 @@ export class GateStore {
     return join(this.dir, "log.jsonl")
   }
 
+  private get indexPath(): string {
+    return join(this.dir, "index.json")
+  }
+
   /** Run a load→mutate→save section under the store's exclusive lock. */
   async runLocked<T>(fn: () => Promise<T>): Promise<T> {
     return withLock(this.gatesPath, fn)
   }
 
-  /** force=true bypasses the mtime cache (always used inside locks). */
+  /**
+   * force=true bypasses the mtime cache (always used inside locks).
+   * Every record crosses the validation boundary: hopeless records are
+   * dropped, repairable ones coerced — enforcement never sees raw state.
+   */
   async load(force = false): Promise<Gate[]> {
     try {
       const info = await stat(ntPath(this.gatesPath))
@@ -186,7 +210,15 @@ export class GateStore {
       }
       const raw = await readFile(ntPath(this.gatesPath), "utf8")
       const parsed = JSON.parse(raw) as Partial<GatesFile>
-      this.gates = Array.isArray(parsed.gates) ? parsed.gates : []
+      const records = Array.isArray(parsed.gates) ? parsed.gates : []
+      const gates: Gate[] = []
+      for (const record of records) {
+        const gate = coerceGateShape(record)
+        if (gate === null) continue
+        repairGate(gate)
+        gates.push(gate)
+      }
+      this.gates = gates
       this.mtimeMs = info.mtimeMs
       return this.gates
     } catch {
@@ -208,10 +240,52 @@ export class GateStore {
     }
   }
 
-  async log(event: LogEvent): Promise<void> {
+  /** Cross-project pattern index; meaningful only on the global store. */
+  async loadIndex(force = false): Promise<IndexFile> {
+    try {
+      const info = await stat(ntPath(this.indexPath))
+      if (!force && this.index !== null && info.mtimeMs === this.indexMtimeMs) {
+        return this.index
+      }
+      const raw = await readFile(ntPath(this.indexPath), "utf8")
+      const parsed = JSON.parse(raw) as Partial<IndexFile>
+      const keys = parsed.keys
+      this.index = { version: 1, keys: keys !== null && typeof keys === "object" ? keys : {} }
+      this.indexMtimeMs = info.mtimeMs
+      return this.index
+    } catch {
+      // missing or unreadable index — treat as empty
+      if (this.index === null) this.index = { version: 1, keys: {} }
+      return this.index
+    }
+  }
+
+  async saveIndex(): Promise<void> {
+    if (this.index === null) return
     await mkdir(ntPath(this.dir), { recursive: true })
-    const line = `${JSON.stringify({ ts: new Date().toISOString(), ...event })}\n`
-    await appendFile(ntPath(this.logPath), line, "utf8")
+    await atomicWrite(this.indexPath, `${JSON.stringify(this.index, null, 2)}\n`)
+    try {
+      this.indexMtimeMs = (await stat(ntPath(this.indexPath))).mtimeMs
+    } catch {
+      // mtime refresh is best-effort
+    }
+  }
+
+  /** Run an index load→mutate→save section under the index's own lock. */
+  async runLockedIndex<T>(fn: () => Promise<T>): Promise<T> {
+    return withLock(this.indexPath, fn)
+  }
+
+  /**
+   * Append under the log lock: every OpenCode window shares the global log,
+   * and unlocked concurrent appends interleave into broken JSON lines.
+   */
+  async log(event: LogEvent): Promise<void> {
+    await withLock(this.logPath, async () => {
+      await mkdir(ntPath(this.dir), { recursive: true })
+      const line = `${JSON.stringify({ ts: new Date().toISOString(), ...event })}\n`
+      await appendFile(ntPath(this.logPath), line, "utf8")
+    })
   }
 
   /** Caller must hold the lock. */
@@ -225,20 +299,151 @@ export class GateStore {
     return expired
   }
 
+  /** Remove gates by key; caller must hold the lock. Returns the removed gates. */
+  extract(keys: Set<string>): Gate[] {
+    if (this.gates === null) return []
+    const removed = this.gates.filter((g) => keys.has(g.key))
+    if (removed.length > 0) this.gates = this.gates.filter((g) => !keys.has(g.key))
+    return removed
+  }
+
   async rotateLog(): Promise<void> {
+    await withLock(this.logPath, async () => {
+      try {
+        const info = await stat(ntPath(this.logPath))
+        if (info.size < LOG_ROTATE_BYTES) return
+        const raw = await readFile(ntPath(this.logPath), "utf8")
+        const lines = raw.split("\n").filter((l) => l.trim() !== "")
+        const kept = lines.slice(-LOG_ROTATE_KEEP_LINES)
+        await atomicWrite(this.logPath, `${kept.join("\n")}\n`)
+      } catch {
+        // missing or unreadable log is fine
+      }
+    })
+  }
+
+  /**
+   * Structural self-healing (idempotent): unparseable gates.json is
+   * quarantined with its bytes preserved; parseable records are coerced,
+   * repaired and deduped; unparseable log lines are excised to
+   * log.jsonl.corrupt. Every repair is logged — healing must be visible.
+   */
+  async reconcile(): Promise<void> {
+    await withLock(this.gatesPath, async () => {
+      let raw: string | null = null
+      try {
+        raw = await readFile(ntPath(this.gatesPath), "utf8")
+      } catch {
+        // no gates file yet — nothing structural to heal
+      }
+      if (raw !== null && raw.trim() !== "") {
+        let parsed: Partial<GatesFile> | null = null
+        try {
+          parsed = JSON.parse(raw) as Partial<GatesFile>
+        } catch {
+          parsed = null
+        }
+        if (parsed === null || typeof parsed !== "object" || !Array.isArray(parsed.gates)) {
+          // SQLite-style quarantine: move aside, keep the bytes, start clean.
+          const quarantine = `${this.gatesPath}.corrupt-${Date.now()}`
+          try {
+            await rename(ntPath(this.gatesPath), ntPath(quarantine))
+            this.gates = []
+            this.mtimeMs = 0
+            await this.save()
+            await this.log({ type: "quarantined", key: "gates.json", snippet: `unparseable gates file moved to ${quarantine}` })
+          } catch {
+            // rename failed — next reconcile retries; never destroy the file
+          }
+        } else {
+          let dropped = 0
+          let repaired = 0
+          const byKey = new Map<string, Gate>()
+          for (const record of parsed.gates) {
+            const gate = coerceGateShape(record)
+            if (gate === null) {
+              dropped += 1
+              continue
+            }
+            if (repairGate(gate)) repaired += 1
+            const existing = byKey.get(gate.key)
+            if (existing) {
+              mergeGate(existing, gate)
+            } else {
+              byKey.set(gate.key, gate)
+            }
+          }
+          const merged = parsed.gates.length - dropped - byKey.size
+          this.gates = [...byKey.values()]
+          this.mtimeMs = 0
+          await this.save()
+          if (dropped > 0 || repaired > 0 || merged > 0) {
+            await this.log({
+              type: "repaired",
+              key: "gates.json",
+              snippet: `dropped ${dropped} hopeless record(s), repaired ${repaired}, merged ${merged} duplicate key(s)`,
+            })
+          }
+        }
+      }
+      await this.exciseCorruptLogLines()
+    })
+  }
+
+  /** Move unparseable JSONL lines to log.jsonl.corrupt; good lines stay. */
+  private async exciseCorruptLogLines(): Promise<void> {
+    let raw: string
     try {
-      const info = await stat(ntPath(this.logPath))
-      if (info.size < LOG_ROTATE_BYTES) return
-      const raw = await readFile(ntPath(this.logPath), "utf8")
-      const lines = raw.split("\n").filter((l) => l.trim() !== "")
-      const kept = lines.slice(-LOG_ROTATE_KEEP_LINES)
-      await writeFile(ntPath(this.logPath), `${kept.join("\n")}\n`, "utf8")
+      raw = await readFile(ntPath(this.logPath), "utf8")
     } catch {
-      // missing or unreadable log is fine
+      return // no log yet
     }
+    const good: string[] = []
+    const bad: string[] = []
+    for (const line of raw.split("\n")) {
+      if (line.trim() === "") continue
+      try {
+        JSON.parse(line)
+        good.push(line)
+      } catch {
+        bad.push(line)
+      }
+    }
+    if (bad.length === 0) return
+    await withLock(this.logPath, async () => {
+      await appendFile(ntPath(`${this.logPath}.corrupt`), `${bad.join("\n")}\n`, "utf8")
+      await atomicWrite(this.logPath, good.length > 0 ? `${good.join("\n")}\n` : "")
+    })
+    await this.log({ type: "repaired", key: "log.jsonl", snippet: `excised ${bad.length} corrupt line(s) to log.jsonl.corrupt` })
   }
 }
 
+/** Merge a gate's accumulated evidence into an existing gate with the same key. */
+function mergeGate(target: Gate, source: Gate): void {
+  // blocking is the stronger state — a merge must never demote an enforced gate
+  if (source.status === "blocking") target.status = "blocking"
+  target.count += source.count
+  for (const session of source.sessions) {
+    if (!target.sessions.includes(session)) target.sessions.push(session)
+  }
+  if (target.sessions.length > MAX_SESSIONS) target.sessions = target.sessions.slice(-MAX_SESSIONS)
+  for (const project of source.projects) {
+    if (!target.projects.includes(project)) target.projects.push(project)
+  }
+  if (target.projects.length > MAX_PROJECTS) target.projects = target.projects.slice(-MAX_PROJECTS)
+  if (source.firstSeen < target.firstSeen) target.firstSeen = source.firstSeen
+  if (source.lastSeen > target.lastSeen) {
+    target.lastSeen = source.lastSeen
+    target.snippet = source.snippet
+  }
+  target.remindedCount += source.remindedCount
+  target.blockedCount += source.blockedCount
+  target.recurredAfterReminder += source.recurredAfterReminder
+  target.recurredAfterGate += source.recurredAfterGate
+  if (target.correction === undefined && source.correction !== undefined) target.correction = source.correction
+  if (source.review === true) target.review = true
+}
+
 /**
  * Two-scope gate management: project-local gates live in the repo
  * (`.opencode/dejavu/`), cross-project agent habits are promoted to the
@@ -309,6 +514,20 @@ export class Stores {
         }
       })
     }
+    // The cross-project index rots on the same schedule as the gates.
+    await this.globalStore.runLockedIndex(async () => {
+      const index = await this.globalStore.loadIndex(true)
+      const cutoff = Date.now() - ttlDays * DAY_MS
+      let changed = false
+      for (const key of Object.keys(index.keys)) {
+        const entry = index.keys[key]
+        if (entry && Date.parse(entry.lastSeen) < cutoff) {
+          delete index.keys[key]
+          changed = true
+        }
+      }
+      if (changed) await this.globalStore.saveIndex()
+    })
   }
 
   async rotateLogs(): Promise<void> {
@@ -321,6 +540,7 @@ export class Stores {
    * One-time (idempotent) schema/behavior migration:
    *  - probe-tool gates never block (they were learned under the old policy)
    *  - signatures and snippets are secret-scrubbed (cleans historical leaks)
+   *  - project copies of already-global keys merge into the global gate
    */
   async migrate(): Promise<void> {
     for (const store of this.scopes()) {
@@ -353,6 +573,112 @@ export class Stores {
         if (changed) await store.save()
       })
     }
+
+    // A key that reached the global store is global everywhere: merge any
+    // leftover project-local copy into the global gate so evidence does not
+    // fragment across scopes (stale local copies kept enforcing from the old
+    // scope while the global gate starved).
+    const projectStore = this.projectStore
+    if (projectStore) {
+      await projectStore.runLocked(async () => {
+        const projGates = await projectStore.load(true)
+        const globalKeys = new Set((await this.globalStore.load()).map((g) => g.key))
+        const dupes = projGates.filter((g) => globalKeys.has(g.key))
+        if (dupes.length === 0) return
+        await this.globalStore.runLocked(async () => {
+          const globalGates = await this.globalStore.load(true)
+          for (const dupe of dupes) {
+            const target = globalGates.find((g) => g.key === dupe.key)
+            if (target) {
+              mergeGate(target, dupe)
+            } else {
+              globalGates.push(dupe)
+            }
+          }
+          await this.globalStore.save()
+        })
+        projectStore.extract(new Set(dupes.map((g) => g.key)))
+        await projectStore.save()
+      })
+    }
+  }
+
+  /**
+   * Structural self-healing across both scopes plus index reconciliation.
+   * Idempotent; runs at plugin init and via `doctor --repair`.
+   */
+  async reconcileAll(globalProjects = 2): Promise<void> {
+    for (const store of this.scopes()) {
+      await store.reconcile()
+    }
+
+    // Index-driven escalation healing: a key proven in enough project dirs
+    // belongs in the global store even if recordFailure never moved it
+    // (racing instances, or stores that predate the index).
+    const projectStore = this.projectStore
+    if (projectStore) {
+      const index = await this.globalStore.loadIndex()
+      const toEscalate = (await projectStore.load(true)).filter((g) => {
+        const entry = index.keys[g.key]
+        return entry !== undefined && entry.projects.length >= globalProjects
+      })
+      if (toEscalate.length > 0) {
+        await projectStore.runLocked(async () => {
+          await this.globalStore.runLocked(async () => {
+            const globalGates = await this.globalStore.load(true)
+            for (const gate of toEscalate) {
+              const target = globalGates.find((g) => g.key === gate.key)
+              if (target) {
+                mergeGate(target, gate)
+              } else {
+                globalGates.push(gate)
+              }
+            }
+            await this.globalStore.save()
+          })
+          projectStore.extract(new Set(toEscalate.map((g) => g.key)))
+          await projectStore.save()
+        })
+        await this.globalStore.log({
+          type: "repaired",
+          key: "index.json",
+          snippet: `escalated ${toEscalate.length} gate(s) proven in ${globalProjects}+ project dirs`,
+        })
+      }
+    }
+
+    // The index must mirror reality: a key absent from every scope is an
+    // orphan (its gate expired or was deleted); a global gate missing from
+    // the index loses cross-project history. Heal both directions.
+    const knownKeys = new Set<string>()
+    for (const store of this.scopes()) {
+      for (const gate of await store.load(true)) knownKeys.add(gate.key)
+    }
+    await this.globalStore.runLockedIndex(async () => {
+      const index = await this.globalStore.loadIndex(true)
+      let pruned = 0
+      for (const key of Object.keys(index.keys)) {
+        if (!knownKeys.has(key)) {
+          delete index.keys[key]
+          pruned += 1
+        }
+      }
+      let rebuilt = 0
+      for (const gate of await this.globalStore.load(true)) {
+        if (!index.keys[gate.key]) {
+          index.keys[gate.key] = { projects: [...gate.projects], lastSeen: gate.lastSeen }
+          rebuilt += 1
+        }
+      }
+      if (pruned > 0 || rebuilt > 0) {
+        await this.globalStore.saveIndex()
+        await this.globalStore.log({
+          type: "repaired",
+          key: "index.json",
+          snippet: `pruned ${pruned} orphan key(s), rebuilt ${rebuilt} missing entr(y/ies)`,
+        })
+      }
+    })
   }
 
   async recordFailure(input: {
@@ -426,18 +752,41 @@ export class Stores {
 
       await store.save()
 
-      // Scope escalation: a pattern seen in enough distinct project directories
-      // is an agent-level habit, not a repo quirk — move it to the global store.
-      // Lock order is always project -> global, so no deadlock.
-      let wentGlobal = false
+      // Cross-project evidence lives in the global index: gate.projects only
+      // ever sees its own store's directory, so alone it can never reach two
+      // projects. A pattern seen in enough distinct project dirs is an
+      // agent-level habit, not a repo quirk — move it to the global store.
+      // Lock order is always gates -> index and project -> global: no cycles.
       const moved = gate
-      if (store !== this.globalStore && this.projectStore && gate.projects.length >= input.globalProjects) {
+      const indexProjects = await this.globalStore.runLockedIndex(async () => {
+        const index = await this.globalStore.loadIndex(true)
+        let entry = index.keys[input.key]
+        if (!entry) {
+          entry = { projects: [], lastSeen: now }
+          index.keys[input.key] = entry
+        }
+        if (input.projectDir !== "" && !entry.projects.includes(input.projectDir)) {
+          entry.projects.push(input.projectDir)
+          if (entry.projects.length > MAX_PROJECTS) entry.projects = entry.projects.slice(-MAX_PROJECTS)
+        }
+        entry.lastSeen = now
+        await this.globalStore.saveIndex()
+        return entry.projects.length
+      })
+
+      let wentGlobal = false
+      if (store !== this.globalStore && this.projectStore && indexProjects >= input.globalProjects) {
         const idx = gates.findIndex((g) => g.key === moved.key)
         if (idx >= 0) gates.splice(idx, 1)
         await store.save()
         await this.globalStore.runLocked(async () => {
           const globalGates = await this.globalStore.load(true)
-          if (!globalGates.some((g) => g.key === moved.key)) globalGates.push(moved)
+          const existing = globalGates.find((g) => g.key === moved.key)
+          if (existing) {
+            mergeGate(existing, moved)
+          } else {
+            globalGates.push(moved)
+          }
           await this.globalStore.save()
         })
         wentGlobal = true

package/src/validate.ts

@@ -0,0 +1,107 @@
+/**
+ * Invariant layer: strict parsing and repair of persisted gate state.
+ * Pure functions — no I/O. Used at the persistence boundary (store reconcile)
+ * and by diagnostics (doctor). Parse, don't validate: what survives
+ * coerceGateShape + repairGate satisfies the data-model invariants.
+ */
+import type { Gate } from "./store"
+import { canBlock, scrubSecrets } from "./patterns"
+
+/** sha1 prefix-12, the only key shape patternKey ever emits */
+const KEY_SHAPE = /^[0-9a-f]{12}$/
+/** detection truncates snippets at 200 chars on ingest */
+const SNIPPET_MAX = 200
+
+/**
+ * Structural parse of one persisted gate object. Returns a well-shaped Gate
+ * or null when the record is hopeless (missing identity fields, unknown
+ * status) — hopeless records are dropped, not guessed at.
+ */
+export function coerceGateShape(raw: unknown): Gate | null {
+  if (typeof raw !== "object" || raw === null) return null
+  const r = raw as Record<string, unknown>
+  if (typeof r.key !== "string" || !KEY_SHAPE.test(r.key)) return null
+  if (typeof r.signature !== "string" || r.signature.trim() === "") return null
+  if (typeof r.tool !== "string" || r.tool.trim() === "") return null
+  if (r.status !== "watching" && r.status !== "blocking") return null
+
+  const num = (v: unknown, fallback: number): number =>
+    typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : fallback
+  const strings = (v: unknown): string[] =>
+    Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : []
+  const str = (v: unknown, fallback: string): string => (typeof v === "string" ? v : fallback)
+  const now = new Date().toISOString()
+
+  const gate: Gate = {
+    key: r.key,
+    signature: r.signature,
+    tool: r.tool,
+    status: r.status,
+    count: num(r.count, 0),
+    sessions: strings(r.sessions),
+    projects: strings(r.projects),
+    firstSeen: str(r.firstSeen, now),
+    lastSeen: str(r.lastSeen, now),
+    snippet: str(r.snippet, ""),
+    remindedCount: num(r.remindedCount, 0),
+    blockedCount: num(r.blockedCount, 0),
+    recurredAfterReminder: num(r.recurredAfterReminder, 0),
+    recurredAfterGate: num(r.recurredAfterGate, 0),
+  }
+  if (typeof r.correction === "string") gate.correction = r.correction
+  if (r.review === true) gate.review = true
+  return gate
+}
+
+/**
+ * In-place coercion of everything mechanically repairable. Returns true when
+ * anything changed. What it cannot repair (identity fields, hopeless shapes)
+ * is rejected earlier by coerceGateShape.
+ */
+export function repairGate(gate: Gate): boolean {
+  let changed = false
+  if (gate.firstSeen > gate.lastSeen) {
+    const swap = gate.firstSeen
+    gate.firstSeen = gate.lastSeen
+    gate.lastSeen = swap
+    changed = true
+  }
+  if (gate.snippet.length > SNIPPET_MAX) {
+    gate.snippet = gate.snippet.slice(0, SNIPPET_MAX)
+    changed = true
+  }
+  const signature = scrubSecrets(gate.signature)
+  if (signature !== gate.signature) {
+    gate.signature = signature
+    changed = true
+  }
+  const snippet = scrubSecrets(gate.snippet)
+  if (snippet !== gate.snippet) {
+    gate.snippet = snippet
+    changed = true
+  }
+  if (gate.correction !== undefined) {
+    const correction = scrubSecrets(gate.correction)
+    if (correction !== gate.correction) {
+      gate.correction = correction
+      changed = true
+    }
+  }
+  // Policy is the single source of truth: a blocking gate that cannot block
+  // is a leftover from an older policy and must be demoted.
+  if (gate.status === "blocking" && !canBlock(gate.tool, gate.signature)) {
+    gate.status = "watching"
+    changed = true
+  }
+  return changed
+}
+
+/**
+ * Corruption fingerprint of tokens re-parameterized inside other tokens
+ * (e.g. `<code: <n> >` — a fingerprint eaten by the number rule). Such a
+ * signature is stable under re-normalization, so only an explicit shape
+ * check catches it.
+ */
+export function hasNestedTokens(signature: string): boolean {
+  return /<[a-z]+:\s*</.test(signature)
+}