opencode-dejavu 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 2.1.0 — 2026-08-22
+
+First public release.
+
+### Added
+- Gate enforcement state machine: remind on first same-session encounter, hard block after a reminded retry fails again; `dejavu:proceed` explicit escape hatch (logged as `override`).
+- Two-scope store: project gates in `<repo>/.opencode/dejavu/`, escalation to global `~/.config/opencode/dejavu/` after 2+ distinct project dirs; lock order always project → global.
+- Detection channels: `metadata.exit` (bash), line-by-line bash text scan, and `message.part.updated` event stream for tool-level errors; chain-segment matching so gates fire inside `a && gated` chains.
+- Blocking policy: only non-diagnostic bash commands may block (`canBlock()`); probe tools use a higher promotion bar and never block.
+- Secret scrubbing before any persistence (OpenAI/Anthropic/AWS/GitHub/Slack/Stripe/JWT/PEM/DB-conn/bearer/`root@host`, Google `AIza…`, full PEM blocks, `.env`-style `KEY=VALUE`).
+- Near-duplicate consolidation via normalized Levenshtein ≤ 0.3 with an absolute floor of 3 edits.
+- TTL expiry (60 days), log rotation, bounded in-memory session maps, `review: true` flagging, `recurredAfterGate` health metric.
+- Observability: `log.jsonl` forensic events (`channel`, `via`, `exit`, `version`), `scripts/doctor.ts`, `scripts/analyze.ts`, `scripts/migrate.ts`.
+- Companion agent skill (`skills/dejavu/`) and `/dejavu` status command (`command/dejavu.md`).
+- `experimental.session.compacting` hook injecting active gates into compaction context.
+
+### Fixed (post-review hardening, same release line)
+- `pendingCalls` no longer leaks entries for aborted (reminded/blocked) calls; capped at 1000.
+- Quoted-string parameterization regex rewritten as an unrolled loop (no catastrophic backtracking).
+- `migrate()` now also secret-scrubs gate `correction` fields.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WhiteBite
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+<p align="center">
+  <img src="logo/icon.svg" width="96" height="96" alt="dejavu logo — a lowercase d with two amber echo strokes">
+</p>
+
+<h3 align="center">dejavu — OpenCode error-gate plugin</h3>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
+  <img src="https://img.shields.io/badge/OpenCode-plugin-3178c6.svg" alt="OpenCode plugin">
+  <img src="https://img.shields.io/badge/TypeScript-Bun-black.svg" alt="TypeScript + Bun">
+  <img src="https://github.com/WhiteBite/opencode-dejavu/actions/workflows/ci.yml/badge.svg" alt="CI">
+</p>
+
+Cross-session **memory prosthesis with teeth** for [OpenCode](https://github.com/anomalyco/opencode). AI agents repeat the same mistakes because they forget between sessions — and markdown rules don't fix that. dejavu mechanically detects recurring tool-call failures (bash, read, edit, write, glob, grep) and promotes them into enforced gates: a reminder on the next attempt, a hard block on same-session repeat offense. TypeScript + Bun, ships as source, no build step.
+
+## How it works
+
+```
+tool call fails  →  signature normalized (paths/numbers/hashes stripped)
+                 →  pattern-key counted, sessions tracked
+                 →  3 failures across 2 distinct sessions  →  gate promoted
+next attempt     →  [dejavu] REMINDER thrown (call aborted, agent sees the correction)
+retry fails again →  same-session repeat offense → hard BLOCK on further attempts
+```
+
+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/`.
+- **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.
+
+## Install
+
+**npm (recommended)** — one line, OpenCode installs it automatically at startup:
+
+```jsonc
+// ~/.config/opencode/opencode.json (global) or opencode.json (project)
+{ "plugin": ["opencode-dejavu"] }
+```
+
+**From source:**
+
+```bash
+git clone https://github.com/WhiteBite/opencode-dejavu ~/.config/opencode/vendor/dejavu
+cd ~/.config/opencode/vendor/dejavu && bun install
+```
+
+```ts
+// ~/.config/opencode/plugins/dejavu.ts
+export { Dejavu } from "../vendor/dejavu/index.ts"
+```
+
+Companion skill (agent behavior protocol): copy `skills/dejavu/` to `~/.config/opencode/skills/dejavu/`.
+Status command: copy `command/dejavu.md` to `~/.config/opencode/command/dejavu.md`.
+
+Restart OpenCode. Gates appear automatically as failures recur — nothing to configure.
+
+## 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.
+- **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.
+- **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.
+- **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.
+
+## 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/analyze.ts [projectDirs...]` — store summary: statuses, tools, top patterns.
+- `/dejavu` command (installed globally) runs doctor first, then reports.
+
+## Detection coverage
+
+| Channel | Catches |
+|---|---|
+| `tool.execute.after` + `metadata.exit` | bash failures (non-zero exit, TS errors, test failures, stack traces) |
+| `message.part.updated` event scan | tool-level failures (read of missing file, rejected edits) that never reach the after-hook; error text is Sentry-style parameterized (uuid/ip/url/hex/date → placeholders) |
+| chain-segment matching | gates fire even when the gated command hides inside `x && gated-cmd` chains |
+| companion skill | agent behavior protocol (how to react, when to annotate) |
+| `/dejavu` command | status report: active gates, recurrence metric, review flags |
+
+Not covered (by design, v1): semantically-equivalent-but-syntactically-different failures beyond fuzzy (Levenshtein ≤ 0.3, ≥ 3 edits) matching.
+
+## Data files
+
+| File | Contents |
+|---|---|
+| `~/.config/opencode/dejavu/gates.json` | global gates (agent habits) |
+| `<repo>/.opencode/dejavu/gates.json` | project gates (repo gotchas) |
+| `*/dejavu/log.jsonl` | every event: detected, promoted, reminded, blocked, override, expired, recurred-after-gate |
+
+Both are human-editable. Removing a gate object disables it. Editing `correction` improves what the agent is told.
+
+## Development
+
+```bash
+bun install
+bun run typecheck        # tsc --noEmit (index.ts + src/**)
+bun test/smoke.ts        # behavioral smoke test, no framework needed
+```
+
+Tunables are named constants at the top of `index.ts` and `src/store.ts`: `PROMOTE_COUNT` (3), `PROMOTE_COUNT_PROBE` (5), `PROMOTE_SESSIONS` (2), `GLOBAL_PROJECTS` (2), `TTL_DAYS` (60), `REVIEW_FIRES` (10).
+
+## Roadmap
+
+- v2: recurrence-after-gate reporting command; V2 plugin API error hooks when stable
+- v3: auto-proposal of ast-grep rules for statically detectable patterns (repo-level CI gates)
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,412 @@
+import { homedir } from "node:os"
+import { join } from "node:path"
+import type { Plugin } from "@opencode-ai/plugin"
+import {
+  bashSegmentSignatures,
+  callSignature,
+  detectFailure,
+  isIntendedNonzero,
+  parameterizeError,
+  patternKey,
+  scrubSecrets,
+} from "./src/patterns"
+import { GateStore, Stores, type Gate, PLUGIN_VERSION } from "./src/store"
+
+// --- Tunables ---------------------------------------------------------------
+
+/** distinct project dirs before a pattern is promoted to the global store */
+const GLOBAL_PROJECTS = 2
+/** gates expire when the pattern has not recurred for this many days */
+const TTL_DAYS = 60
+/** how often a long-lived process re-runs expiry */
+const TTL_INTERVAL_MS = 6 * 60 * 60 * 1000
+/** a gate firing this often without killing the error gets flagged for review */
+const REVIEW_FIRES = 10
+/** per-session state maps are capped to bound memory in long-lived processes */
+const SESSION_MAP_CAP = 200
+/** handled part IDs are capped FIFO-style */
+const HANDLED_CAP = 5000
+const HANDLED_KEEP = 2500
+/** pendingCalls capped — aborted calls never reach the after-hook, so a cap bounds the fallback map */
+const PENDING_CAP = 1000
+
+/** Sentinel: intentional gate/reminder throws (rethrown); our own bugs are swallowed. */
+class GateSignal extends Error {}
+
+function addToSetMap(map: Map<string, Set<string>>, outer: string, inner: string): void {
+  let set = map.get(outer)
+  if (!set) {
+    set = new Set()
+    map.set(outer, set)
+  }
+  set.add(inner)
+}
+
+/** Drop oldest entries (Map preserves insertion order) to bound memory. */
+function capMap(map: Map<string, Set<string>>, cap: number): void {
+  while (map.size > cap) {
+    const oldest = map.keys().next()
+    if (oldest.done) break
+    map.delete(oldest.value)
+  }
+}
+
+function scrubbedArgs(args: Record<string, unknown>): Record<string, unknown> {
+  if (typeof args.command === "string") return { ...args, command: scrubSecrets(args.command) }
+  if (typeof args.pattern === "string") return { ...args, pattern: scrubSecrets(args.pattern) }
+  return args
+}
+
+function remindMessage(gate: Gate): string {
+  const correction = gate.correction
+    ? `Correction: ${gate.correction}`
+    : "Do NOT retry it unchanged. Diagnose the root cause first, or take a different approach."
+  return [
+    `[dejavu] REMINDER — this exact call has already failed ${gate.count}x across ${gate.sessions.length} session(s).`,
+    `Last failure: ${gate.snippet}`,
+    correction,
+    `If you are certain it works now, retry — a repeated failure hardens this gate into a block. Explicit bypass: append the trailing comment "# dejavu:proceed" to the command — it is a marker read by the gate, NOT a shell command.`,
+  ].join("\n")
+}
+
+function blockMessage(gate: Gate, storeDir: string): string {
+  return [
+    `[dejavu] BLOCKED — you were reminded about this failing call in this session, retried it, and it failed again.`,
+    `CORRECTION: ${gate.correction ?? "Change approach entirely; do not repeat this exact call."}`,
+    `EVIDENCE: ${gate.count} failures across ${gate.sessions.length} sessions, first seen ${gate.firstSeen.slice(0, 10)}.`,
+    `Review or remove this gate: ${join(storeDir, "gates.json")} (key: ${gate.key})`,
+  ].join("\n")
+}
+
+export const Dejavu: Plugin = async ({ directory, client }) => {
+  // DEJAVU_HOME overrides the global store location (testing, custom setups).
+  const globalDir = process.env.DEJAVU_HOME ?? join(homedir(), ".config", "opencode", "dejavu")
+  const globalStore = new GateStore(globalDir)
+  const projectStore =
+    typeof directory === "string" && directory !== ""
+      ? new GateStore(join(directory, ".opencode", "dejavu"))
+      : null
+  const stores = new Stores(globalStore, projectStore)
+
+  /** sessions in which a gate key was already reminded about */
+  const reminded = new Map<string, Set<string>>()
+  /** sessions in which a reminded pattern failed again — next attempt is blocked */
+  const failedAfterReminder = new Map<string, Set<string>>()
+  /** callID -> signature fallback when the after-hook does not receive args */
+  const pendingCalls = new Map<string, string>()
+  /** message part IDs already counted as tool-level errors */
+  let handledParts = new Set<string>()
+
+  const logClient = async (level: "debug" | "info" | "warn" | "error", message: string): Promise<void> => {
+    try {
+      await client.app.log({ body: { service: "dejavu", level, message } })
+    } catch {
+      // logging must never break the plugin
+    }
+  }
+
+  // Init: migrate old data, expire stale gates, rotate logs, warm the caches.
+  try {
+    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
+  }
+
+  // Long-lived processes re-run expiry periodically.
+  const ttlTimer = setInterval(() => {
+    // expiry is best-effort; the timer keeps running regardless
+    stores.expireAll(TTL_DAYS).catch(() => {})
+  }, TTL_INTERVAL_MS)
+  ;(ttlTimer as { unref?: () => void }).unref?.()
+
+  return {
+    "tool.execute.before": async (input, output) => {
+      try {
+        const rawArgs = (output?.args ?? {}) as Record<string, unknown>
+        const args = scrubbedArgs(rawArgs)
+        const signature = callSignature(input.tool, args)
+        if (!signature) return
+
+        // Chain-bypass protection: a gate on "rm -rf /" must also fire when the
+        // command hides inside "git status && rm -rf /".
+        const candidates = [signature]
+        if (input.tool === "bash" && typeof args.command === "string") {
+          candidates.push(...bashSegmentSignatures(args.command))
+        }
+
+        let found: { gate: Gate; store: GateStore; via: "exact" | "fuzzy" | "segment" } | null = null
+        for (let i = 0; i < candidates.length; i++) {
+          const sig = candidates[i] ?? ""
+          const match = await stores.findGate(patternKey(sig), sig)
+          if (match && match.gate.status === "blocking") {
+            found = { gate: match.gate, store: match.store, via: i > 0 && match.via === "exact" ? "segment" : match.via }
+            break
+          }
+        }
+        if (!found) return
+        // Only track calls that will actually run: an aborted (thrown) call never
+        // reaches the after-hook, so recording it earlier would leak forever.
+        if (typeof input.callID === "string") {
+          pendingCalls.set(input.callID, signature)
+          while (pendingCalls.size > PENDING_CAP) {
+            const oldest = pendingCalls.keys().next()
+            if (oldest.done) break
+            pendingCalls.delete(oldest.value)
+          }
+        }
+
+        const gate = found.gate
+        const via = found.via
+        const session = typeof input.sessionID === "string" ? input.sessionID : "unknown"
+
+        // Explicit escape hatch — checked only in the actionable text field,
+        // with word boundaries, so unrelated args cannot bypass gates.
+        const commandText =
+          typeof rawArgs.command === "string"
+            ? rawArgs.command
+            : typeof rawArgs.pattern === "string"
+              ? rawArgs.pattern
+              : typeof rawArgs.filePath === "string"
+                ? rawArgs.filePath
+                : ""
+        if (/\bdejavu:proceed\b/.test(commandText)) {
+          await stores.logAll({ type: "override", key: gate.key, tool: gate.tool, session, project: directory })
+          return
+        }
+
+        // Repeat offense: reminded in this session, retried, failed again -> hard block.
+        if (failedAfterReminder.get(session)?.has(gate.key)) {
+          gate.blockedCount += 1
+          if (gate.blockedCount >= REVIEW_FIRES) gate.review = true
+          await found.store.save()
+          await stores.logAll({ type: "blocked", key: gate.key, tool: gate.tool, session, project: directory, via })
+          throw new GateSignal(blockMessage(gate, found.store.dir))
+        }
+
+        // First encounter this session -> remind (the call is aborted; agent may retry corrected).
+        if (!reminded.get(session)?.has(gate.key)) {
+          addToSetMap(reminded, session, gate.key)
+          addToSetMap(reminded, session, patternKey(signature)) // exact key too: retry may fuzzy-match differently
+          capMap(reminded, SESSION_MAP_CAP)
+          gate.remindedCount += 1
+          await found.store.save()
+          await stores.logAll({ type: "reminded", key: gate.key, tool: gate.tool, session, project: directory, via })
+          throw new GateSignal(remindMessage(gate))
+        }
+
+        // Already reminded, no repeated failure yet -> allow one retry.
+        await stores.logAll({ type: "retry-allowed", key: gate.key, tool: gate.tool, session, project: directory, via })
+      } catch (error) {
+        if (error instanceof GateSignal) throw error
+        // Our own bugs must never break the user's tool calls.
+      }
+    },
+
+    "tool.execute.after": async (input, output) => {
+      try {
+        // Primary signal: the tool's exit code in metadata (verified against live
+        // payloads — failed bash calls arrive as successful tool executions with
+        // metadata.exit !== 0 and often "(no output)" as the text).
+        const metadata = (output?.metadata ?? {}) as { exit?: unknown }
+        const exitCode = typeof metadata.exit === "number" ? metadata.exit : null
+        const isBash = input.tool === "bash"
+        // Text signatures apply to bash ONLY: for read/edit/write the output is
+        // file CONTENT, and scanning it for "TypeError" created false gates.
+        const text = typeof output?.output === "string" ? output.output : ""
+        const detection = isBash ? detectFailure(text) : { matched: false, snippet: "" }
+        const rawCommand = isBash && typeof (input as { args?: { command?: unknown } }).args?.command === "string"
+          ? String((input as { args: { command: string } }).args.command)
+          : ""
+        // grep/pytest/linters: exit 1 is often the INTENDED outcome, not a mistake.
+        const intended = exitCode === 1 && isIntendedNonzero(rawCommand, 1)
+        const failed = exitCode !== null ? exitCode !== 0 && !intended : detection.matched
+        if (!failed) return
+        const snippet = scrubSecrets(detection.matched ? detection.snippet : `exit code ${exitCode}`)
+
+        const args = scrubbedArgs(((input as { args?: unknown }).args ?? {}) as Record<string, unknown>)
+        let signature = callSignature(input.tool, args)
+        if (typeof input.callID === "string") {
+          if (!signature) signature = pendingCalls.get(input.callID) ?? null
+          pendingCalls.delete(input.callID)
+        }
+        if (!signature) return
+
+        // Attribution: if a segment of a failed chain matches an already-known
+        // pattern, record the failure under that segment's key — the chain
+        // wrapper changes every time, the recurring part does not.
+        let recordSignature = signature
+        if (input.tool === "bash" && typeof args.command === "string") {
+          for (const segSig of bashSegmentSignatures(args.command)) {
+            if (await stores.hasKey(patternKey(segSig))) {
+              recordSignature = segSig
+              break
+            }
+          }
+        }
+
+        const key = patternKey(recordSignature)
+        const session = typeof input.sessionID === "string" ? input.sessionID : "unknown"
+
+        const result = await stores.recordFailure({
+          key,
+          signature: recordSignature,
+          tool: input.tool,
+          sessionID: session,
+          projectDir: typeof directory === "string" ? directory : "",
+          snippet,
+          globalProjects: GLOBAL_PROJECTS,
+        })
+
+        await stores.logAll({
+          type: "detected",
+          key,
+          tool: input.tool,
+          session,
+          project: directory,
+          snippet,
+          channel: exitCode !== null ? "exit" : "text",
+          exit: exitCode ?? undefined,
+        })
+
+        if (result.promoted) {
+          await stores.logAll({ type: "promoted", key, tool: input.tool, session, project: directory })
+          await logClient(
+            "info",
+            `dejavu: gate promoted — "${result.gate.signature}" (${result.gate.count}x, ${result.gate.sessions.length} sessions)`,
+          )
+        }
+        if (result.wentGlobal) {
+          await logClient("info", `dejavu: gate went global — "${result.gate.signature}"`)
+        }
+
+        // Metric: failure of an already-enforced pattern (the event that
+        // promoted the gate does not count — the gate did not exist yet).
+        if (result.gate.status === "blocking" && !result.promoted) {
+          result.gate.recurredAfterGate += 1
+          await result.store.save()
+          await stores.logAll({ type: "recurred-after-gate", key, tool: input.tool, session, project: directory })
+        }
+
+        // Same-session repeat after a reminder -> escalate to hard block.
+        if (reminded.get(session)?.has(key) || reminded.get(session)?.has(result.gate.key)) {
+          addToSetMap(failedAfterReminder, session, result.gate.key)
+          capMap(failedAfterReminder, SESSION_MAP_CAP)
+          result.gate.recurredAfterReminder += 1
+          await result.store.save()
+        }
+      } catch {
+        // detection failures must never break the tool pipeline
+      }
+    },
+
+    event: async ({ event }) => {
+      try {
+        const type = (event as { type?: unknown }).type
+
+        // Free per-session state when a session is deleted.
+        if (type === "session.deleted") {
+          const props = (event as { properties?: unknown }).properties as { sessionID?: unknown } | undefined
+          if (typeof props?.sessionID === "string") {
+            reminded.delete(props.sessionID)
+            failedAfterReminder.delete(props.sessionID)
+          }
+          return
+        }
+
+        if (type !== "message.part.updated") return
+        // Tool-level failures (read of missing file, rejected edit, ...) never
+        // reach tool.execute.after — capture them from the message stream.
+        const props: unknown = (event as { properties?: unknown }).properties
+        if (typeof props !== "object" || props === null) return
+        const part: unknown = (props as { part?: unknown }).part
+        if (typeof part !== "object" || part === null) return
+        const p = part as { id?: unknown; type?: unknown; tool?: unknown; state?: unknown; sessionID?: unknown }
+        if (p.type !== "tool" || typeof p.id !== "string") return
+        if (handledParts.has(p.id)) return
+
+        const state: unknown = p.state
+        if (typeof state !== "object" || state === null) return
+        if ((state as { status?: unknown }).status !== "error") return
+
+        handledParts.add(p.id)
+        if (handledParts.size > HANDLED_CAP) {
+          handledParts = new Set([...handledParts].slice(-HANDLED_KEEP))
+        }
+
+        const toolName = typeof p.tool === "string" ? p.tool : "unknown"
+
+        const rawError: unknown = (state as { error?: unknown }).error
+        const rawText =
+          typeof rawError === "string" ? rawError : rawError === undefined ? "unknown error" : JSON.stringify(rawError)
+        // Never persist secrets or infrastructure details.
+        const errorText = scrubSecrets(rawText)
+        // 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
+        const session = typeof p.sessionID === "string" ? p.sessionID : "unknown"
+
+        // Prefer the real call signature from the tool input — it keeps the gate
+        // enforceable by the before-hook. Fall back to a parameterized error
+        // signature so "same root cause, different data" collapses to one key.
+        const toolInput: unknown = (state as { input?: unknown }).input
+        let signature: string | null = null
+        if (typeof toolInput === "object" && toolInput !== null) {
+          signature = callSignature(toolName, scrubbedArgs(toolInput as Record<string, unknown>))
+        }
+        if (!signature) {
+          signature = `${toolName}:tool-error:${parameterizeError(errorText).slice(0, 120)}`
+        }
+        const key = patternKey(signature)
+
+        const result = await stores.recordFailure({
+          key,
+          signature,
+          tool: toolName,
+          sessionID: session,
+          projectDir: typeof directory === "string" ? directory : "",
+          snippet: errorText.slice(0, 200),
+          globalProjects: GLOBAL_PROJECTS,
+        })
+        await stores.logAll({
+          type: "detected",
+          key,
+          tool: toolName,
+          session,
+          project: directory,
+          snippet: errorText.slice(0, 200),
+          channel: "event",
+        })
+        if (result.promoted) {
+          await stores.logAll({ type: "promoted", key, tool: toolName, session, project: directory })
+          await logClient("info", `dejavu: gate promoted — "${result.gate.signature}"`)
+        }
+      } catch {
+        // event stream must never be broken by us
+      }
+    },
+
+    "experimental.session.compacting": async (_input, output) => {
+      try {
+        const gates = await stores.blockingGates()
+        if (gates.length === 0) return
+        const lines = gates
+          .slice(0, 20)
+          .map(
+            (g) =>
+              `- \`${g.signature}\` — failed ${g.count}x in ${g.sessions.length} session(s). ${g.correction ?? "Do not retry unchanged; find the root cause first."}`,
+          )
+        output.context.push(
+          `## dejavu — active error gates\nThese tool calls have repeatedly failed before. Do not attempt them unchanged:\n${lines.join("\n")}`,
+        )
+      } catch {
+        // compaction enrichment is best-effort
+      }
+    },
+  }
+}
+
+export default Dejavu

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "opencode-dejavu",
+  "version": "2.1.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",
+  "files": [
+    "index.ts",
+    "src",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "ai-agents",
+    "coding-agent",
+    "error-gates",
+    "memory",
+    "reliability",
+    "bun"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/WhiteBite/opencode-dejavu.git"
+  },
+  "homepage": "https://github.com/WhiteBite/opencode-dejavu",
+  "bugs": "https://github.com/WhiteBite/opencode-dejavu/issues",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.18.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.5.0"
+  }
+}

package/src/AGENTS.md

@@ -0,0 +1,37 @@
+# src/ — pattern engine + gate persistence
+
+## OVERVIEW
+
+Two dependency-free modules: `patterns.ts` (pure functions — call identity, normalization, detection, policy) and `store.ts` (stateful — gates.json/log.jsonl I/O under locks, promotion, scope escalation).
+
+## WHERE TO LOOK
+
+| Task | File | Symbols |
+|------|------|---------|
+| Call identity / gate keys | patterns.ts | `callSignature` → `normalizeCommand`/`normalizeFilePath` → `patternKey` |
+| 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` |
+| 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` |
+| 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
+- `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
+- 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
+- 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 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)