opencode-dejavu 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 2.3.0 — 2026-08-24
+
+### Multi-process hardening (several OpenCode windows = several plugin processes on one store)
+- Remind→block session state is persisted ON THE GATE (`remindedSessions`/`failedSessions`) instead of per-process memory: the escalation chain now survives process restarts and is visible to every window serving the session (before: two windows or a restart reset it to "remind forever, never block"). Enforcement reads fresh gate state under the store lock.
+- Session state rots after 24h and is capped per gate; `session.deleted` cleans it from disk.
+
+### Performance (hot path runs on every tool call)
+- `fuzzySimilar`: O(1) length-band pre-filter (triangle inequality — zero false negatives) and a `FUZZY_MAX_LEN` cap — kills the Levenshtein explosion on long signatures (was 150-600ms/tool-call at scale).
+- `GateStore`: O(1) key index + cached blocking subset for lookups; 1s TTL on the mtime cache so the hot path stops paying a `stat` per call (saves refresh the cache directly).
+- Global log rotates at 2MB instead of 512KB — with several projects the aggregate forensics no longer vanish within a day.
+
+### Fixed
+- Init-storm TOCTOU: index orphan-pruning now keeps a 24h grace window, so a just-promoted gate's index entry cannot be pruned by a concurrent startup.
+- After-hook escalation state is written under the store lock and follows the gate to the global store on escalation (previously lost in both cases).
+
+### Added
+- `doctor.ts` reports LOCK DEGRADATIONS (count of `degraded` log events) as an observability note — the evidence signal for whether the storage backend ever needs revisiting.
+
+## 2.2.1 — 2026-08-24
+
+### Fixed (adversarial-review round)
+- Escalation order: the gate is written to the global store BEFORE being removed from the project store — a crash between the two writes leaves a duplicate (healed by migrate), never a hole.
+- `dejavu:proceed` inside quoted strings no longer bypasses gates (`echo "dejavu:proceed" && gated-cmd` stays enforced); the marker is honored only outside quotes.
+- Concurrent first-encounter race: calls dispatched in the same burst as a REMINDER (within 500ms) are reminded too instead of slipping through as a "retry".
+- CRLF/CR commands normalize identically to LF; `splitChain` splits on CR — no more line-ending fragmentation.
+- `normalizeCommand` is fully idempotent: quoted spans are parameterized BEFORE path rules (a `<str>` substitution inserts spaces that would expose an adjacent `/` to the path rule only on a second pass), fingerprint payloads are trimmed, and already-parameterized payloads are never re-fingerprinted.
+- Interpreter flags glued to their payload (`node -e"code"`) fingerprint identically to the spaced form.
+- Session state maps: inner key sets are capped — long sessions no longer grow unbounded.
+
+### Added
+- Lock degradation (contention > 3s) emits a `degraded` log event — the only window where concurrent writes can lose updates is now visible.
+- `test/property.ts` — property-based tests for the normalization pipeline (idempotency, no nested tokens, output bound, one-liner distinctness, marker neutrality, splitChain atomicity).
+- `test/fuzz.ts` — seeded mutation fuzzer with a metamorphic oracle and case shrinking; both harnesses run in CI. The harnesses caught the idempotency, marker-neutrality, glued-flag and nested-token-detector bugs above before production did.
+
 ## 2.2.0 — 2026-08-23
 
 ### Added

package/README.md

@@ -66,7 +66,8 @@ Restart OpenCode. Gates appear automatically as failures recur — nothing to co
 - **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; 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.
+- **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. If a lock cannot be acquired within 3s the critical section degrades to unlocked (the tool pipeline must never hang) and emits a `degraded` log event — the only window where updates can be lost is visible.
+- **Multi-window safe** — the remind→block escalation chain is persisted on the gate itself (`remindedSessions`/`failedSessions`), not in process memory: several OpenCode windows on one store — and process restarts — all see the same chain. Enforcement always reads fresh gate state under the store lock.
 - **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; project copies of already-global gates are merged into the global gate (evidence is consolidated, never deleted).

package/index.ts

@@ -23,8 +23,10 @@ const TTL_DAYS = 60
 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
+/** a "retry" arriving this soon after a reminder was dispatched concurrently with it
+ * (same tool-call burst) and never saw the reminder — it gets reminded as well.
+ * A true agent retry needs a full model turn (≥1s in practice), so 500ms separates both. */
+const REMINDER_RACE_WINDOW_MS = 500
 /** handled part IDs are capped FIFO-style */
 const HANDLED_CAP = 5000
 const HANDLED_KEEP = 2500
@@ -34,24 +36,6 @@ 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) }
@@ -89,10 +73,6 @@ export const Dejavu: Plugin = async ({ directory, client }) => {
       : 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 */
@@ -169,7 +149,10 @@ export const Dejavu: Plugin = async ({ directory, client }) => {
         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.
+        // with word boundaries, so unrelated args cannot bypass gates. Quoted
+        // spans are stripped first: `echo "dejavu:proceed" && gated-cmd` must
+        // NOT bypass the gate on the chained command — the marker is a
+        // comment-style annotation, not data.
         const commandText =
           typeof rawArgs.command === "string"
             ? rawArgs.command
@@ -178,33 +161,50 @@ export const Dejavu: Plugin = async ({ directory, client }) => {
               : typeof rawArgs.filePath === "string"
                 ? rawArgs.filePath
                 : ""
-        if (/\bdejavu:proceed\b/.test(commandText)) {
+        if (/\bdejavu:proceed\b/.test(commandText.replace(/"[^"]*"|'[^']*'/g, " "))) {
           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))
-        }
+        // Enforce from FRESH gate state under the store lock. The remind→block
+        // chain lives on the gate itself (remindedSessions/failedSessions), so
+        // it survives process restarts and is visible to every window serving
+        // this session — per-process maps lost it on both.
+        const target = found
+        let signal: GateSignal | null = null
+        await target.store.runLocked(async () => {
+          const fresh = (await target.store.load(true)).find((g) => g.key === gate.key)
+          if (fresh === undefined) return // gate deleted between find and lock
+
+          // Repeat offense: reminded, retried, failed again -> hard block.
+          if (fresh.failedSessions !== undefined && fresh.failedSessions.includes(session)) {
+            fresh.blockedCount += 1
+            if (fresh.blockedCount >= REVIEW_FIRES) fresh.review = true
+            await target.store.save()
+            await stores.logAll({ type: "blocked", key: fresh.key, tool: fresh.tool, session, project: directory, via })
+            signal = new GateSignal(blockMessage(fresh, target.store.dir))
+            return
+          }
 
-        // 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))
-        }
+          // First encounter this session -> remind (the call is aborted; agent may retry corrected).
+          // Race guard: calls dispatched in the same burst all arrive before the agent can
+          // have seen any reminder, so a "retry" within REMINDER_RACE_WINDOW_MS of the
+          // remind is itself a concurrent first encounter and gets reminded too.
+          const remindedAt = fresh.remindedSessions?.[session]
+          if (remindedAt === undefined || Date.now() - remindedAt < REMINDER_RACE_WINDOW_MS) {
+            if (fresh.remindedSessions === undefined) fresh.remindedSessions = {}
+            fresh.remindedSessions[session] = Date.now()
+            fresh.remindedCount += 1
+            await target.store.save()
+            await stores.logAll({ type: "reminded", key: fresh.key, tool: fresh.tool, session, project: directory, via })
+            signal = new GateSignal(remindMessage(fresh))
+            return
+          }
 
-        // 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 })
+          // Already reminded, no repeated failure yet -> allow one retry.
+          await stores.logAll({ type: "retry-allowed", key: fresh.key, tool: fresh.tool, session, project: directory, via })
+        })
+        if (signal !== null) throw signal
       } catch (error) {
         if (error instanceof GateSignal) throw error
         // Our own bugs must never break the user's tool calls.
@@ -288,21 +288,29 @@ export const Dejavu: Plugin = async ({ directory, client }) => {
           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()
-        }
+        // Persist escalation state on the gate itself (under the store lock) so
+        // every window serving this session sees the same remind→block chain.
+        const ownerStore = result.wentGlobal ? stores.globalStore : result.store
+        await ownerStore.runLocked(async () => {
+          const fresh = (await ownerStore.load(true)).find((g) => g.key === result.gate.key)
+          if (fresh === undefined) return
+          let changed = false
+          // Metric: failure of an already-enforced pattern (the event that
+          // promoted the gate does not count — the gate did not exist yet).
+          if (fresh.status === "blocking" && !result.promoted) {
+            fresh.recurredAfterGate += 1
+            changed = true
+            await stores.logAll({ type: "recurred-after-gate", key: fresh.key, tool: input.tool, session, project: directory })
+          }
+          // Same-session repeat after a reminder -> escalate to hard block.
+          if (fresh.remindedSessions?.[session] !== undefined) {
+            if (fresh.failedSessions === undefined) fresh.failedSessions = []
+            if (!fresh.failedSessions.includes(session)) fresh.failedSessions.push(session)
+            fresh.recurredAfterReminder += 1
+            changed = true
+          }
+          if (changed) await ownerStore.save()
+        })
       } catch {
         // detection failures must never break the tool pipeline
       }
@@ -312,12 +320,11 @@ export const Dejavu: Plugin = async ({ directory, client }) => {
       try {
         const type = (event as { type?: unknown }).type
 
-        // Free per-session state when a session is deleted.
+        // Free the persisted 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)
+            stores.forgetSession(props.sessionID).catch(() => {})
           }
           return
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-dejavu",
-  "version": "2.2.0",
+  "version": "2.3.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

@@ -24,13 +24,16 @@ Two dependency-free modules: `patterns.ts` (pure functions — call identity, no
 ## 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
+- Rule order in `normalizeCommand` matters too: quoted strings are parameterized BEFORE path rules — a `<str>` substitution inserts spaces that would expose an adjacent `/` to the path rule on a second pass (idempotency); interpreter payload hashing runs while the payload is still raw
 - `scrubSecrets()` runs on every string before it touches disk; `recordFailure` re-scrubs defensively
 - `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, 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
+- Escalation writes the global gate FIRST, then removes the project copy — a crash between the two writes must leave a duplicate (healed by migrate), never a hole
 - 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
+- Hot-path reads use the 1s TTL cache + key index (`byKey`/`blockingOnly`); mutations inside locks use `load(true)`; `save()` refreshes the cache directly
+- The remind→block chain is persisted ON THE GATE (`remindedSessions`/`failedSessions`) and enforced under the store lock — process memory holds nothing authoritative, so several windows and restarts share one escalation
 - 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

package/src/patterns.ts

@@ -51,16 +51,24 @@ export function scrubSecrets(text: string): string {
  * 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
+  /(?:^|[|;&(\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
+  // Already fingerprinted (re-normalization) — keep the existing token so
+  // normalizeCommand stays idempotent.
+  if (/^<code:[0-9a-f]+>$/.test(payload.trim())) return command
+  // Already-parameterized placeholders are data, not code — never hash them
+  // (idempotency: a second pass must not fingerprint a <str>).
+  if (/^(?:<(?:str|path|n|hash|uuid|sha|md5|ip|url|email|date)>\s*)+$/.test(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)
+  // Trim before hashing: trailing whitespace (e.g. a stripped override marker)
+  // is not part of the code's identity.
+  const fingerprint = createHash("sha1").update(scrubSecrets(payload.trim())).digest("hex").slice(0, 8)
   return `${command.slice(0, match.index + match[0].length)}<code:${fingerprint}>`
 }
 
@@ -70,11 +78,18 @@ function hashInterpreterPayload(command: string): string {
  * away so that "same failure, different instance" collapses into one pattern.
  */
 export function normalizeCommand(command: string): string {
-  let s = command.replace(COMMENT_LINE, "$1").toLowerCase()
+  // CRLF/CR commands (Windows pastes, agent multi-line) normalize to LF —
+  // otherwise the same command fragments across line-ending styles.
+  let s = command.replace(/\r\n?/g, "\n")
+  s = s.replace(COMMENT_LINE, "$1").toLowerCase()
   s = hashInterpreterPayload(s)
+  // Quoted spans come out FIRST: they are data, and removing them before the
+  // path rules keeps normalization idempotent — a <str> replacement inserts
+  // spaces that would otherwise expose an adjacent "/" to the path rule only
+  // on a second pass.
+  s = s.replace(/"[^"]*"|'[^']*'/g, " <str> ")
   s = s.replace(/[a-z]:[\\/][^\s"']+/gi, " <path> ")
   s = s.replace(/(^|\s)\/[^\s"']+/g, "$1<path> ")
-  s = s.replace(/"[^"]*"|'[^']*'/g, " <str> ")
   // 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> ")
@@ -213,7 +228,7 @@ export function splitChain(command: string): string[] {
       continue
     }
     if (depth === 0) {
-      if (ch === ";" || ch === "\n") {
+      if (ch === ";" || ch === "\n" || ch === "\r") {
         flush()
         i += 1
         continue
@@ -317,6 +332,11 @@ export function levenshtein(a: string, b: string): number {
 /** Code fingerprints are IDENTITY, not data — they must match exactly. */
 const CODE_FINGERPRINTS = /<code:[0-9a-f]+>/g
 
+/** Signatures longer than this match exactly only: a 300-char normalized
+ * command is already specific enough that "30% near" is meaningless, and
+ * Levenshtein on long signatures is the hot-path cost cliff. */
+export const FUZZY_MAX_LEN = 300
+
 /**
  * Near-duplicate match: normalized edit distance <= 30% AND absolute distance
  * >= 3. Unlike token-set Jaccard, this does not collapse commands that merely
@@ -335,6 +355,11 @@ export function fuzzySimilar(a: string, b: string): boolean {
   }
   const maxLen = Math.max(a.length, b.length)
   if (maxLen === 0) return true
+  if (maxLen > FUZZY_MAX_LEN) return false
+  // Triangle inequality: distance >= |lenA - lenB|. If even that floor
+  // exceeds the ratio threshold, no Levenshtein result can pass — an O(1)
+  // pre-filter with zero false negatives that skips most DP computations.
+  if (Math.abs(a.length - b.length) / maxLen > 0.3) return false
   const distance = levenshtein(a, b)
   return distance >= 3 && distance / maxLen <= 0.3
 }

package/src/store.ts

@@ -1,10 +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 { canBlock, fuzzySimilar, FUZZY_MAX_LEN, 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.2.0"
+export const PLUGIN_VERSION = "2.3.0"
 
 export interface Gate {
   /** sha1 signature prefix — the pattern identity */
@@ -32,6 +32,12 @@ export interface Gate {
   recurredAfterGate: number
   /** flagged for manual review when the gate fires often but errors stopped */
   review?: boolean
+  /** sessions currently reminded about this gate: sessionID -> remind time (ms).
+   * Persisted on the gate so the remind→block chain survives process restarts
+   * and is visible to every window serving the session. */
+  remindedSessions?: Record<string, number>
+  /** sessions that failed again after a reminder — their next attempt blocks */
+  failedSessions?: string[]
 }
 
 interface GatesFile {
@@ -62,6 +68,7 @@ export type LogEventType =
   | "init"
   | "repaired"
   | "quarantined"
+  | "degraded"
 
 export interface LogEvent {
   type: LogEventType
@@ -83,8 +90,12 @@ export interface LogEvent {
 const MAX_SESSIONS = 50
 const MAX_PROJECTS = 20
 const LOG_ROTATE_BYTES = 512 * 1024
+/** the global log aggregates every project — rotate it later or forensics vanish in a day */
+const GLOBAL_LOG_ROTATE_BYTES = 2048 * 1024
 const LOG_ROTATE_KEEP_LINES = 1000
 const DAY_MS = 24 * 60 * 60 * 1000
+/** trust the loaded-gates cache this long without re-statting (hot path: every tool call) */
+const LOAD_CACHE_TTL_MS = 1000
 
 /** failures required before a pattern becomes an enforced gate */
 export const PROMOTE_COUNT = 3
@@ -137,7 +148,7 @@ const LOCK_WAIT_MS = 3000
  * degradation: if the lock cannot be acquired within LOCK_WAIT_MS the
  * critical section runs unlocked rather than hanging the tool pipeline.
  */
-async function withLock<T>(lockTarget: string, fn: () => Promise<T>): Promise<T> {
+async function withLock<T>(lockTarget: string, fn: () => Promise<T>, onDegrade?: () => void): Promise<T> {
   const lock = `${lockTarget}.lock`
   await mkdir(ntPath(dirname(lock)), { recursive: true })
   const started = Date.now()
@@ -157,7 +168,11 @@ async function withLock<T>(lockTarget: string, fn: () => Promise<T>): Promise<T>
       } catch {
         continue // lock vanished between attempts
       }
-      if (Date.now() - started > LOCK_WAIT_MS) break
+      if (Date.now() - started > LOCK_WAIT_MS) {
+        // The only window where concurrent writes can lose updates — make it visible.
+        if (onDegrade) onDegrade()
+        break
+      }
       await new Promise((resolve) => setTimeout(resolve, 50))
     }
   }
@@ -175,6 +190,10 @@ async function withLock<T>(lockTarget: string, fn: () => Promise<T>): Promise<T>
 export class GateStore {
   private gates: Gate[] | null = null
   private mtimeMs = 0
+  /** hot-path caches: valid until LOAD_CACHE_TTL_MS / invalidated on mutation */
+  private cacheUntilMs = 0
+  private keyIndex: Map<string, Gate> | null = null
+  private blockingCache: Gate[] | null = null
   private index: IndexFile | null = null
   private indexMtimeMs = 0
 
@@ -194,7 +213,9 @@ export class GateStore {
 
   /** 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)
+    return withLock(this.gatesPath, fn, () => {
+      this.log({ type: "degraded", key: "gates.lock", snippet: `lock contention exceeded ${LOCK_WAIT_MS}ms; critical section ran unlocked` }).catch(() => {})
+    })
   }
 
   /**
@@ -203,9 +224,16 @@ export class GateStore {
    * dropped, repairable ones coerced — enforcement never sees raw state.
    */
   async load(force = false): Promise<Gate[]> {
+    // TTL fast path: the hot path (every tool call) must not pay a stat per
+    // call. Gates change rarely (promotion, manual edit); 1s staleness is
+    // invisible to enforcement and our own saves refresh the cache directly.
+    if (!force && this.gates !== null && Date.now() < this.cacheUntilMs) {
+      return this.gates
+    }
     try {
       const info = await stat(ntPath(this.gatesPath))
       if (!force && this.gates !== null && info.mtimeMs === this.mtimeMs) {
+        this.cacheUntilMs = Date.now() + LOAD_CACHE_TTL_MS
         return this.gates
       }
       const raw = await readFile(ntPath(this.gatesPath), "utf8")
@@ -219,15 +247,39 @@ export class GateStore {
         gates.push(gate)
       }
       this.gates = gates
+      this.keyIndex = new Map(gates.map((g) => [g.key, g]))
+      this.blockingCache = gates.filter((g) => g.status === "blocking")
       this.mtimeMs = info.mtimeMs
+      this.cacheUntilMs = Date.now() + LOAD_CACHE_TTL_MS
       return this.gates
     } catch {
       // missing or unreadable gates.json — treat as an empty store
-      if (this.gates === null) this.gates = []
+      if (this.gates === null) {
+        this.gates = []
+        this.keyIndex = new Map()
+        this.blockingCache = []
+      }
+      this.cacheUntilMs = Date.now() + LOAD_CACHE_TTL_MS
       return this.gates
     }
   }
 
+  /** O(1) exact lookup over the cached gates (call load() first to refresh). */
+  byKey(key: string): Gate | undefined {
+    if (this.keyIndex === null) {
+      this.keyIndex = new Map((this.gates ?? []).map((g) => [g.key, g]))
+    }
+    return this.keyIndex.get(key)
+  }
+
+  /** Cached blocking subset — the fuzzy scan iterates this, not all gates. */
+  blockingOnly(): Gate[] {
+    if (this.blockingCache === null) {
+      this.blockingCache = (this.gates ?? []).filter((g) => g.status === "blocking")
+    }
+    return this.blockingCache
+  }
+
   async save(): Promise<void> {
     if (this.gates === null) return
     await mkdir(ntPath(this.dir), { recursive: true })
@@ -238,6 +290,9 @@ export class GateStore {
     } catch {
       // mtime refresh is best-effort
     }
+    // We know the content we just wrote — refresh the TTL cache directly.
+    // (keyIndex/blockingCache hold references into this.gates, still valid.)
+    this.cacheUntilMs = Date.now() + LOAD_CACHE_TTL_MS
   }
 
   /** Cross-project pattern index; meaningful only on the global store. */
@@ -273,7 +328,9 @@ export class GateStore {
 
   /** 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)
+    return withLock(this.indexPath, fn, () => {
+      this.log({ type: "degraded", key: "index.lock", snippet: `lock contention exceeded ${LOCK_WAIT_MS}ms; critical section ran unlocked` }).catch(() => {})
+    })
   }
 
   /**
@@ -303,15 +360,19 @@ export class GateStore {
   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))
+    if (removed.length > 0) {
+      this.gates = this.gates.filter((g) => !keys.has(g.key))
+      this.keyIndex = null
+      this.blockingCache = null
+    }
     return removed
   }
 
-  async rotateLog(): Promise<void> {
+  async rotateLog(rotateBytes: number = LOG_ROTATE_BYTES): Promise<void> {
     await withLock(this.logPath, async () => {
       try {
         const info = await stat(ntPath(this.logPath))
-        if (info.size < LOG_ROTATE_BYTES) return
+        if (info.size < rotateBytes) 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)
@@ -462,7 +523,8 @@ export class Stores {
   /** True if a pattern with this key exists in any scope (chain attribution). */
   async hasKey(key: string): Promise<boolean> {
     for (const store of this.scopes()) {
-      if ((await store.load()).some((g) => g.key === key)) return true
+      await store.load()
+      if (store.byKey(key) !== undefined) return true
     }
     return false
   }
@@ -473,13 +535,15 @@ export class Stores {
     signature: string,
   ): Promise<{ gate: Gate; store: GateStore; via: "exact" | "fuzzy" } | null> {
     for (const store of this.scopes()) {
-      const exact = (await store.load()).find((g) => g.key === key)
+      await store.load()
+      const exact = store.byKey(key)
       if (exact) return { gate: exact, store, via: "exact" }
     }
+    // Over-long signatures match exactly only — see FUZZY_MAX_LEN.
+    if (signature.length > FUZZY_MAX_LEN) return null
     let best: { gate: Gate; store: GateStore; score: number } | null = null
     for (const store of this.scopes()) {
-      for (const gate of await store.load()) {
-        if (gate.status !== "blocking") continue
+      for (const gate of store.blockingOnly()) {
         if (!fuzzySimilar(signature, gate.signature)) continue
         const score = Math.abs(signature.length - gate.signature.length)
         if (best === null || score < best.score) best = { gate, store, score }
@@ -492,9 +556,8 @@ export class Stores {
   async blockingGates(): Promise<Gate[]> {
     const result: Gate[] = []
     for (const store of this.scopes()) {
-      for (const gate of await store.load()) {
-        if (gate.status === "blocking") result.push(gate)
-      }
+      await store.load()
+      for (const gate of store.blockingOnly()) result.push(gate)
     }
     return result.sort((a, b) => b.count - a.count)
   }
@@ -532,7 +595,31 @@ export class Stores {
 
   async rotateLogs(): Promise<void> {
     for (const store of this.scopes()) {
-      await store.rotateLog()
+      // The global log aggregates every project — give it more room.
+      await store.rotateLog(store === this.globalStore ? GLOBAL_LOG_ROTATE_BYTES : LOG_ROTATE_BYTES)
+    }
+  }
+
+  /** Forget per-session enforcement state when a session dies. */
+  async forgetSession(sessionID: string): Promise<void> {
+    for (const store of this.scopes()) {
+      await store.runLocked(async () => {
+        const gates = await store.load(true)
+        let changed = false
+        for (const gate of gates) {
+          if (gate.remindedSessions && gate.remindedSessions[sessionID] !== undefined) {
+            delete gate.remindedSessions[sessionID]
+            if (Object.keys(gate.remindedSessions).length === 0) delete gate.remindedSessions
+            changed = true
+          }
+          if (gate.failedSessions !== undefined && gate.failedSessions.includes(sessionID)) {
+            gate.failedSessions = gate.failedSessions.filter((s) => s !== sessionID)
+            if (gate.failedSessions.length === 0) delete gate.failedSessions
+            changed = true
+          }
+        }
+        if (changed) await store.save()
+      })
     }
   }
 
@@ -658,7 +745,11 @@ export class Stores {
       const index = await this.globalStore.loadIndex(true)
       let pruned = 0
       for (const key of Object.keys(index.keys)) {
-        if (!knownKeys.has(key)) {
+        const entry = index.keys[key]
+        // Young entries may belong to a promotion in flight in another window
+        // (its gates were snapshotted after this key was written) — only prune
+        // orphans that have been stale for a day.
+        if (entry && !knownKeys.has(key) && Date.now() - Date.parse(entry.lastSeen) > DAY_MS) {
           delete index.keys[key]
           pruned += 1
         }
@@ -776,9 +867,8 @@ export class Stores {
 
       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()
+        // Global FIRST, then remove the local copy: a crash between the two
+        // writes must leave a duplicate (healed by migrate), never a hole.
         await this.globalStore.runLocked(async () => {
           const globalGates = await this.globalStore.load(true)
           const existing = globalGates.find((g) => g.key === moved.key)
@@ -789,6 +879,9 @@ export class Stores {
           }
           await this.globalStore.save()
         })
+        const idx = gates.findIndex((g) => g.key === moved.key)
+        if (idx >= 0) gates.splice(idx, 1)
+        await store.save()
         wentGlobal = true
       }
 

package/src/validate.ts

@@ -11,6 +11,10 @@ import { canBlock, scrubSecrets } from "./patterns"
 const KEY_SHAPE = /^[0-9a-f]{12}$/
 /** detection truncates snippets at 200 chars on ingest */
 const SNIPPET_MAX = 200
+/** per-session enforcement state rots after a day — sessions do not live longer */
+const SESSION_STATE_TTL_MS = 24 * 60 * 60 * 1000
+/** bound per-gate session state so long-lived gates cannot bloat */
+const SESSION_STATE_CAP = 50
 
 /**
  * Structural parse of one persisted gate object. Returns a well-shaped Gate
@@ -50,6 +54,17 @@ export function coerceGateShape(raw: unknown): Gate | null {
   }
   if (typeof r.correction === "string") gate.correction = r.correction
   if (r.review === true) gate.review = true
+  if (r.remindedSessions !== null && typeof r.remindedSessions === "object" && !Array.isArray(r.remindedSessions)) {
+    const sessions: Record<string, number> = {}
+    for (const [session, at] of Object.entries(r.remindedSessions as Record<string, unknown>)) {
+      if (typeof at === "number" && Number.isFinite(at)) sessions[session] = at
+    }
+    if (Object.keys(sessions).length > 0) gate.remindedSessions = sessions
+  }
+  if (Array.isArray(r.failedSessions)) {
+    const sessions = r.failedSessions.filter((x): x is string => typeof x === "string")
+    if (sessions.length > 0) gate.failedSessions = sessions
+  }
   return gate
 }
 
@@ -87,6 +102,33 @@ export function repairGate(gate: Gate): boolean {
       changed = true
     }
   }
+  // Per-session enforcement state hygiene: rot stale entries, bound the rest.
+  if (gate.remindedSessions !== undefined) {
+    const now = Date.now()
+    const reminded = gate.remindedSessions
+    for (const session of Object.keys(reminded)) {
+      if (now - (reminded[session] ?? 0) > SESSION_STATE_TTL_MS) {
+        delete reminded[session]
+        changed = true
+      }
+    }
+    const sessions = Object.keys(reminded)
+    if (sessions.length > SESSION_STATE_CAP) {
+      sessions.sort((a, b) => (reminded[a] ?? 0) - (reminded[b] ?? 0))
+      for (const session of sessions.slice(0, sessions.length - SESSION_STATE_CAP)) {
+        delete reminded[session]
+      }
+      changed = true
+    }
+    if (Object.keys(reminded).length === 0) delete gate.remindedSessions
+  }
+  if (gate.failedSessions !== undefined) {
+    if (gate.failedSessions.length > SESSION_STATE_CAP) {
+      gate.failedSessions = gate.failedSessions.slice(-SESSION_STATE_CAP)
+      changed = true
+    }
+    if (gate.failedSessions.length === 0) delete gate.failedSessions
+  }
   // 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)) {
@@ -97,11 +139,11 @@ export function repairGate(gate: Gate): boolean {
 }
 
 /**
- * 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.
+ * Corruption fingerprint of a placeholder re-parameterized inside another
+ * token (`<code: <n> >` — a fingerprint eaten by the number rule). Only the
+ * `<code:` token carries nested content, so the check is scoped to it —
+ * shell text like heredoc `<<eof:` must NOT trip the detector.
  */
 export function hasNestedTokens(signature: string): boolean {
-  return /<[a-z]+:\s*</.test(signature)
+  return /<code:\s*</.test(signature)
 }