iterate-plugin 2.12.2 → 3.2.1

package/src/config-loader.ts

@@ -207,6 +207,11 @@ export type ProjectRootResult = { ok: true; root: string } | { ok: false; reason
  */
 export function resolveProjectRoot(input?: string, sessionCwd?: string): ProjectRootResult {
   const raw = (input ?? '').trim()
+  // A NUL byte can never name a real path and makes `resolve()` (and every
+  // downstream fs call) throw — treat it as unsafe input, not a throw path.
+  if (raw.includes('\0')) {
+    return { ok: false, reason: 'Refusing project root containing NUL bytes.' }
+  }
   const root = raw ? resolve(raw) : resolve(effectiveCwd(sessionCwd))
   if (!root || root === sep) {
     return { ok: false, reason: 'Refusing filesystem root as project root.' }

package/src/git-scope.ts

@@ -43,6 +43,51 @@ export interface GitScopeResult {
  * NUL is present (callers that did not pass -z) fall back to newline-split
  * with C-style quote/escape unescaping for core.quotePath output.
  */
+/**
+ * Decode the quoted body of a git core.quotePath output line into the real
+ * filename bytes, then interpret them as UTF-8.
+ *
+ * Single-pass and escape-atomic: each `\` consumes exactly one escape (\" \\
+ * \t \n or a 3-digit octal for a raw byte), so a literal `\\303` in a filename
+ * (escaped backslash + literal "303") is decoded as the byte `\` followed by
+ * ASCII "303" rather than as the single byte 0xC3. Ordinary characters in the
+ * quoted body are ASCII (git always octal-escapes non-ASCII bytes), so they map
+ * 1:1 to bytes.
+ */
+function decodeQuotedPath(content: string): string {
+  const bytes: number[] = []
+  let i = 0
+  while (i < content.length) {
+    const ch = content[i]!
+    if (ch !== '\\') {
+      bytes.push(ch.charCodeAt(0))
+      i++
+      continue
+    }
+    const next = content[i + 1]
+    if (next === '"') { bytes.push(0x22); i += 2 }
+    else if (next === '\\') { bytes.push(0x5c); i += 2 }
+    else if (next === 't') { bytes.push(0x09); i += 2 }
+    else if (next === 'n') { bytes.push(0x0a); i += 2 }
+    else if (next !== undefined && next >= '0' && next <= '7') {
+      const oct = content.slice(i + 1, i + 4)
+      if (oct.length === 3 && /^[0-7]{3}$/.test(oct)) {
+        bytes.push(parseInt(oct, 8))
+        i += 4
+      } else {
+        // Malformed octal — keep the backslash literally.
+        bytes.push(0x5c)
+        i++
+      }
+    } else {
+      // Unknown escape — keep the backslash literally.
+      bytes.push(0x5c)
+      i++
+    }
+  }
+  return Buffer.from(bytes).toString('utf-8')
+}
+
 export function parseChangedFiles(stdout: string): string[] {
   if (stdout.includes('\0')) {
     return stdout.split('\0').map((s) => s.trim()).filter((s) => s.length > 0)
@@ -52,15 +97,11 @@ export function parseChangedFiles(stdout: string): string[] {
     .map((line) => {
       const trimmed = line.trim()
       // git core.quotePath wraps paths with special characters in "..."; the
-      // content uses C-style escapes (\" \\ \t \n and \ooo octal for non-ASCII).
+      // content uses C-style escapes (\" \\ \t \n) and \ooo octal escapes for
+      // non-ASCII bytes (which are raw UTF-8 BYTES, not Latin-1 code points).
       const quoted = trimmed.match(/^"(.*)"$/)
       if (!quoted) return trimmed
-      return quoted[1]!
-        .replace(/\\"/g, '"')
-        .replace(/\\\\/g, '\\')
-        .replace(/\\t/g, '\t')
-        .replace(/\\n/g, '\n')
-        .replace(/\\([0-7]{3})/g, (_m, oct: string) => String.fromCharCode(parseInt(oct, 8)))
+      return decodeQuotedPath(quoted[1]!)
     })
     .filter((line) => line.length > 0)
 }

package/src/index.ts

@@ -2,13 +2,16 @@
  * iterate-plugin — dsh plugin for the iterate autonomous closed-loop workflow
  *
  * Architecture:
- * - The plugin registers 14 tools (config, validate, decision-log, context, review,
- *   triage, fix, diff, rollback, checkpoint, status, history, prune, transcript)
+ * - The plugin registers 17 tools (14 original + 3 v3.0 quality command center tools)
+ *   Original: config, validate, decision-log, context, review, triage, fix, diff,
+ *   rollback, checkpoint, status, history, prune, transcript
+ *   v3.0: experience, quality_gate, defense_events
  * - The plugin injects a system prompt section teaching the iterate workflow pattern
  * - The model (prompted by the skill) writes a workflow script using dsh's `workflow` tool
  * - The workflow script uses `agent()` / `parallel()` / `phase()` / `log()` to orchestrate
- * - Subagents use the 14 tools to do real work (read config, run validation, log decisions,
- *   review, triage, apply/rollback/fixing, checkpoint, status, history, prune, transcript)
+ * - Subagents use the 17 tools to do real work (read config, run validation, log decisions,
+ *   review, triage, apply/rollback/fixing, checkpoint, status, history, prune, transcript,
+ *   query experience bank, check quality gates, query defense events)
  * - A `tools/pre-execute` hook gates destructive iterate calls behind human approval
  *   (F8 observatory approval policy: ask / deny / allow).
  *
@@ -20,7 +23,7 @@
  *
  * Key files:
  * - src/index.ts      — Plugin entry: register tools + inject skill prompt
- * - src/tools/        — 13 tool implementations + meta-review/review engines
+ * - src/tools/        — 17 tool implementations (14 original + 3 v3.0)
  * - src/config-loader.ts — YAML config loading
  * - src/types.ts     — Shared types
  */
@@ -37,6 +40,9 @@ import { registerCheckpointTool, registerStatusTool } from './tools/checkpoint.t
 import { registerHistoryTool } from './tools/history.ts'
 import { registerPruneTool } from './tools/prune.ts'
 import { registerTranscriptTool } from './tools/transcript.ts'
+import { registerExperienceBankTool } from './tools/experience-bank.ts'
+import { registerQualityGateTool } from './tools/quality-gate.ts'
+import { registerDefenseEventsTool } from './tools/defense-events.ts'
 import { registerSessionHooks } from './session-hooks.ts'
 import { registerLiveCapture } from './live.ts'
 import { ITERATE_SKILL_PROMPT } from './skill-prompt.ts'
@@ -45,7 +51,7 @@ export const name = 'iterate-plugin'
 export const inject = ['tools', 'systemPrompt'] as const
 
 export function apply(ctx: Context): void {
-  // 1. Register the 14 tools
+  // 1. Register the 17 tools (14 original + 3 v3.0)
   registerConfigTool(ctx)
   registerValidateTool(ctx)
   registerDecisionLogTool(ctx)
@@ -60,6 +66,10 @@ export function apply(ctx: Context): void {
   registerHistoryTool(ctx)
   registerPruneTool(ctx)
   registerTranscriptTool(ctx)
+  // v3.0: Quality Command Center tools
+  registerExperienceBankTool(ctx)
+  registerQualityGateTool(ctx)
+  registerDefenseEventsTool(ctx)
 
   // 2. Wire the observatory approval gate onto dsh's tools/pre-execute waterfall,
   //    and the live reviewer-activity feed onto tools/result.

package/src/session-hooks.ts

@@ -36,17 +36,33 @@ import type { ToolExecution, PreToolDecision } from '@deepseek-ai/dsh-tools'
  * Returns a dsh `PreToolDecision` so the caller can short-circuit the caller.
  */
 export function gateDecision(exec: ToolExecution): PreToolDecision {
-  // Importing the decision, and only inspecting our own tools, keeps unrelated
-  // tooling untouched. Anything we cannot classify is allowed by default.
-  if (!isDestructiveIterateTool(exec.name)) return { kind: 'allow' }
+  // Defensively read the tool name: an exec handed to the waterfall is an
+  // ordinary object, but a hostile/proxied exec must degrade to "not our tool"
+  // (allow) instead of throwing before classification. The gate only ever
+  // inspects iterate tools, so an unreadable name also must not alter
+  // unrelated tooling.
+  let name = ''
+  try {
+    name = exec?.name ?? ''
+  } catch {
+    name = ''
+  }
+  if (!isDestructiveIterateTool(name)) return { kind: 'allow' }
 
   // Resolve the project root (use the call's own `path` arg, else the agent's
   // session cwd) to read the effective observatory policy.
-  const argPath = typeof exec.arguments === 'object' && exec.arguments && !Array.isArray(exec.arguments)
-    && typeof (exec.arguments as Record<string, unknown>).path === 'string'
-    ? (exec.arguments as Record<string, unknown>).path as string
-    : undefined
-  const sessionCwd = exec.agent?.session?.header?.cwd
+  let argPath: string | undefined
+  let sessionCwd: string | undefined
+  try {
+    const args = exec?.arguments
+    if (args && typeof args === 'object' && !Array.isArray(args)) {
+      const p = (args as Record<string, unknown>).path
+      if (typeof p === 'string') argPath = p
+    }
+    sessionCwd = exec?.agent?.session?.header?.cwd
+  } catch {
+    // hostile/proxied exec — fall through with both undefined (defaults to ask)
+  }
   const resolved = resolveProjectRoot(argPath, sessionCwd)
   let policy: 'ask' | 'deny' | 'allow' = 'ask'
   if (resolved.ok) {
@@ -69,12 +85,18 @@ export function gateDecision(exec: ToolExecution): PreToolDecision {
  */
 export function registerSessionHooks(ctx: Context): void {
   ctx.on('tools/pre-execute', (exec: ToolExecution, next: () => Promise<PreToolDecision>) => {
-    // Never let a throwing gate break the pipeline — degrade to allow.
+    // Fail-safe: a throwing gate must never fail OPEN. Degrade to `ask` so a
+    // destructive call still routes through human consent instead of running
+    // via `next()`'s allow default (matches the header's documented contract).
     let decision: PreToolDecision
     try {
       decision = gateDecision(exec)
-    } catch {
-      return next()
+    } catch (err) {
+      console.warn('[iterate] approval gate failed; degrading to ask.', err)
+      return Promise.resolve({
+        kind: 'ask',
+        reason: 'iterate approval gate unavailable — require consent',
+      })
     }
     if (decision.kind === 'ask') {
       // Delegate the actual human-consent prompt + audit to dsh's approval

package/src/skill-prompt.ts

@@ -24,6 +24,9 @@ You have the iterate plugin installed, which registers these tools:
 - \`iterate_history\` — inspect the runtime state in detail: decision-log entries and applied fixes (optionally scoped to a round or a fixed file)
 - \`iterate_prune\` — remove stale runtime artifacts (\`.iterate/\` entries). Defaults to a read-only dry-run that reports what WOULD be removed; pass \`dryRun:false\` to actually prune.
 - \`iterate_transcript\` — runtime observatory file (\`.iterate/transcript.json\`). \`read\` fetches the persisted manifest including any steering \`nudge\` for this run's reviewers; \`capture\` (call once after the final report) persists the per-reviewer threads, convergence trend, findings, fixes, checkpoint, and timeline so the client observatory panel reflects the run; \`nudge\` sets/clears steering text the next round's reviewers read. Purely local, never touches source files.
+- \`iterate_experience\` — experience bank (\`.iterate/experience.json\`): \`list\`/\`search\`/\`get\` recall verified fixes and patterns from past sessions (read the bank before fixing so proven fixes are applied first); \`add\` records a new verified fix — re-adding the same pattern+dimension bumps its hit count instead of duplicating it.
+- \`iterate_quality_gate\` — quality certificate: \`read\` loads the persisted dimension convergence rates / verification pass rate / PASS-FAIL status; \`compute\` recomputes a fresh snapshot from this round's findings + validation results (supply \`findingsByRound\` for real convergence) and persists it to \`.iterate/quality-gate.json\`.
+- \`iterate_defense_events\` — defense event stream (\`.iterate/defense-events.json\`): \`list\`/\`counts\` review precondition failures, rollbacks, invariant violations, and falsified assumptions; \`record\` logs a new event when a defense fires. Human-readable labels follow the project \`language\` (en/zh).
 
 ### When to use
 When the user asks to review or iterate on the project (e.g. "review this project", "iterate on error handling", "check the codebase for issues", "dry-run review", "反复审查"), run an iterate **workflow** by calling the \`workflow\` tool.

package/src/tools/checkpoint.ts

@@ -11,7 +11,7 @@
 
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import { checkpointPath, iterateDir } from '../paths.ts'
 import { readRegistry } from './fix.ts'

package/src/tools/config.ts

@@ -1,6 +1,6 @@
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from '../config-loader.ts'
 import {
   applyConfigUpdates,

package/src/tools/decision-log.ts

@@ -1,7 +1,7 @@
 import { appendFileSync, readFileSync, mkdirSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import type { DecisionLogEntry } from '../types.ts'
 
@@ -63,7 +63,7 @@ export function appendDecisionEntry(projectRoot: string, entry: DecisionLogEntry
     const line = JSON.stringify(entry) + '\n'
     appendFileSync(filePath, line, 'utf-8')
   } catch (err) {
-    return { count: -1, path: join(projectRoot, LOG_DIR, LOG_FILE), error: `failed to append decision log: ${String(err)}` }
+    return { count: 0, path: join(projectRoot, LOG_DIR, LOG_FILE), error: `failed to append decision log: ${String(err)}` }
   }
   // Count entries
   let count = 0
@@ -215,6 +215,15 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
           }
 
           const result = appendDecisionEntry(projectRoot, entry)
+          if (result.error) {
+            return {
+              operation: 'append',
+              success: false,
+              entryCount: 0,
+              logPath: result.path,
+              error: result.error,
+            }
+          }
           return {
             operation: 'append',
             success: true,

package/src/tools/defense-events.ts

@@ -0,0 +1,295 @@
+/**
+ * src/tools/defense-events.ts — defense event stream query & record tool.
+ *
+ *   iterate_defense_events — browse/search defense events from the current
+ *                            iteration, or record a new one.
+ *
+ * Defense events include: precondition failures, rollbacks, invariant violations,
+ * and assumption falsifications. Read operations give visibility into defensive
+ * actions; "record" persists a new event to .iterate/defense-events.json.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+import { resolveProjectRootForExec, loadEffectiveConfig } from '../config-loader.ts'
+import { readDefenseEvents, writeDefenseEvents, addDefenseEvent } from './defense-store.ts'
+import type { DefenseEvent, DefenseEventType } from '../types.ts'
+
+const DEFAULT_LIMIT = 50
+const MAX_LIMIT = 100
+
+const EVENT_TYPES: DefenseEventType[] = [
+  'precondition_failed',
+  'rollback',
+  'invariant_violated',
+  'assumption_falsified',
+]
+
+/** Clamp a caller-supplied limit to a sane range. */
+function clampLimit(limit: number | undefined): number {
+  if (typeof limit !== 'number' || !Number.isInteger(limit) || limit <= 0) {
+    return DEFAULT_LIMIT
+  }
+  return Math.min(limit, MAX_LIMIT)
+}
+
+/** Bilingual, config-driven human-readable labels for defense event types. */
+const EVENT_TYPE_LABELS: Record<DefenseEventType, { zh: string; en: string }> = {
+  precondition_failed: { zh: '前置校验失败', en: 'precondition failed' },
+  rollback: { zh: '回滚', en: 'rollback' },
+  invariant_violated: { zh: '不变量违反', en: 'invariant violated' },
+  assumption_falsified: { zh: '假设被证伪', en: 'assumption falsified' },
+}
+
+/** Label for a defense event type in the requested language (fallback: English). */
+function labelFor(type: DefenseEventType, language: 'zh' | 'en'): string {
+  const labels = EVENT_TYPE_LABELS[type]
+  return labels ? labels[language] : type
+}
+
+/** Validate arguments for the record operation. */
+function validateRecordInput(args: {
+  type?: unknown
+  round?: unknown
+  description?: unknown
+  defense?: unknown
+  outcome?: unknown
+  severity?: unknown
+}): string[] {
+  const errors: string[] = []
+  if (typeof args.type !== 'string' || !EVENT_TYPES.includes(args.type as DefenseEventType)) {
+    errors.push(`type must be one of: ${EVENT_TYPES.join(', ')}`)
+  }
+  if (typeof args.round !== 'number' || !Number.isInteger(args.round) || args.round < 1) {
+    errors.push('round must be a positive integer')
+  }
+  if (typeof args.description !== 'string' || !args.description.trim()) {
+    errors.push('description is required')
+  }
+  if (typeof args.defense !== 'string' || !args.defense.trim()) {
+    errors.push('defense is required')
+  }
+  if (typeof args.outcome !== 'string' || !args.outcome.trim()) {
+    errors.push('outcome is required')
+  }
+  const severity = args.severity
+  if (severity !== 'critical' && severity !== 'high' && severity !== 'medium' && severity !== 'low') {
+    errors.push('severity must be one of critical, high, medium, low')
+  }
+  return errors
+}
+
+/**
+ * Register the `iterate_defense_events` tool.
+ * Queries defense events from the current iteration.
+ */
+export function registerDefenseEventsTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_defense_events',
+      description:
+        'Query or record defense events: precondition failures, rollbacks, invariant violations, ' +
+        'and assumption falsifications. ' +
+        'List/counts return events with descriptions, outcomes, and summary counts; ' +
+        '"record" persists a new event to .iterate/defense-events.json. ' +
+        'Use it to review defensive actions taken, or to log one when a defense fires.',
+      parameters: {
+        operation: {
+          type: 'string',
+          description: 'Operation: list (browse all), counts (summary by type), record (log a new event). Default: list.',
+          enum: ['list', 'counts', 'record'],
+        },
+        type: {
+          type: 'string',
+          description: 'Event type (filter for list; required for record): precondition_failed, rollback, invariant_violated, assumption_falsified.',
+        },
+        round: {
+          type: 'integer',
+          description: 'Round number (filter for list; required for record).',
+        },
+        severity: {
+          type: 'string',
+          description: 'Severity (filter for list; required for record): critical, high, medium, low.',
+        },
+        description: {
+          type: 'string',
+          description: 'What was being checked (required for record).',
+        },
+        defense: {
+          type: 'string',
+          description: 'The defense that was triggered (required for record).',
+        },
+        outcome: {
+          type: 'string',
+          description: 'Outcome: what was protected against (required for record).',
+        },
+        file: {
+          type: 'string',
+          description: 'Optional file/location context (record).',
+        },
+        line: {
+          type: 'integer',
+          description: 'Optional line number context (record).',
+        },
+        language: {
+          type: 'string',
+          description: 'Label language for readable output: en (default) or zh. Falls back to the project config language.',
+          enum: ['en', 'zh'],
+        },
+        limit: {
+          type: 'integer',
+          description: `Max events to return (default: ${DEFAULT_LIMIT}, cap: ${MAX_LIMIT}).`,
+        },
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean', required: true },
+            kind: { type: 'string' },
+            operation: { type: 'string' },
+            count: { type: 'integer' },
+            events: { type: 'json' },
+            counts: { type: 'json' },
+            event: { type: 'json' },
+            language: { type: 'string' },
+            errors: { type: 'json' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (!value.ok) return [{ type: 'text', text: `defense events query failed: ${value.error}` }]
+          const language: 'zh' | 'en' = value.language === 'zh' ? 'zh' : 'en'
+
+          if (value.operation === 'counts' && value.counts) {
+            const counts = value.counts as Record<DefenseEventType, number>
+            const lines = [
+              'Defense Event Summary:',
+              ...EVENT_TYPES.map((type) =>
+                `  ${labelFor(type, language)}: ${counts[type] ?? 0}`
+              ),
+              `  Total: ${EVENT_TYPES.reduce((sum, type) => sum + (counts[type] ?? 0), 0)}`,
+            ]
+            return [{ type: 'text', text: lines.join('\n') }]
+          }
+
+          if (value.operation === 'record' && value.event) {
+            const e = value.event as unknown as DefenseEvent
+            return [{ type: 'text', text: [
+              `Recorded defense event: ${e.id}`,
+              `  Round ${e.round} - ${labelFor(e.type, language)} (${e.severity})`,
+              `  Check: ${e.description}`,
+              `  Defense: ${e.defense}`,
+              `  Outcome: ${e.outcome}`,
+              e.file ? `  File: ${e.file}${e.line ? `:${e.line}` : ''}` : '',
+            ].filter(Boolean).join('\n') }]
+          }
+
+          const events = (value.events as DefenseEvent[] | undefined) ?? []
+          if (events.length === 0) {
+            return [{ type: 'text', text: 'No defense events recorded.' }]
+          }
+
+          const lines = [
+            `Defense Events (${value.count} total):`,
+            '',
+            ...events.map((e) => {
+              const typeLabel = labelFor(e.type, language)
+              return `[${e.id}] Round ${e.round} - ${typeLabel}\n  ${e.description}\n  Outcome: ${e.outcome}`
+            }),
+          ]
+          return [{ type: 'text', text: lines.join('\n') }]
+        },
+      },
+
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
+        if (!resolved.ok) return { ok: false, kind: 'defense_events', error: resolved.reason }
+        const projectRoot = resolved.root
+
+        const configLang = loadEffectiveConfig(projectRoot).config.language
+        const language: 'zh' | 'en' = args.language === 'zh' || args.language === 'en' ? args.language : configLang
+
+        const operation = typeof args.operation === 'string' ? args.operation : 'list'
+        const limit = clampLimit(args.limit as number | undefined)
+
+        if (operation === 'record') {
+          const errors = validateRecordInput(args)
+          if (errors.length > 0) {
+            return {
+              ok: false,
+              kind: 'defense_events',
+              operation: 'record',
+              errors: errors as unknown as JsonValue,
+              error: `Invalid defense event: ${errors.join('; ')}`,
+            }
+          }
+          const stream = readDefenseEvents(projectRoot)
+          const next = addDefenseEvent(stream, {
+            round: args.round as number,
+            type: args.type as DefenseEventType,
+            description: args.description as string,
+            defense: args.defense as string,
+            outcome: args.outcome as string,
+            severity: args.severity as DefenseEvent['severity'],
+            ...(typeof args.file === 'string' && args.file.length > 0 ? { file: args.file } : {}),
+            ...(typeof args.line === 'number' ? { line: args.line } : {}),
+          })
+          writeDefenseEvents(projectRoot, next)
+          const event = next.events[next.events.length - 1]
+          return {
+            ok: true,
+            kind: 'defense_events',
+            operation: 'record',
+            language,
+            event: event as unknown as JsonValue,
+            counts: next.counts as unknown as JsonValue,
+          }
+        }
+
+        const stream = readDefenseEvents(projectRoot)
+
+        if (operation === 'counts') {
+          return {
+            ok: true,
+            kind: 'defense_events',
+            operation: 'counts',
+            language,
+            counts: stream.counts as unknown as JsonValue,
+          }
+        }
+
+        // Filter events
+        let events = stream.events
+
+        if (typeof args.type === 'string' && args.type) {
+          events = events.filter((e) => e.type === args.type)
+        }
+        if (typeof args.round === 'number') {
+          events = events.filter((e) => e.round === args.round)
+        }
+        if (typeof args.severity === 'string' && args.severity) {
+          events = events.filter((e) => e.severity === args.severity)
+        }
+
+        // Sort by timestamp descending (newest first)
+        events.sort((a, b) => b.timestamp.localeCompare(a.timestamp))
+
+        return {
+          ok: true,
+          kind: 'defense_events',
+          operation: 'list',
+          language,
+          count: Math.min(events.length, limit),
+          events: events.slice(0, limit) as unknown as JsonValue,
+        }
+      },
+    }),
+  )
+}