iterate-plugin 2.12.3 → 3.2.1

package/README.md

@@ -1,7 +1,7 @@
 # iterate-plugin for DeepSeek Harness (dsh)
 
-> dsh 桌面端的 iterate 收敛面板、UI 分诊与审查闭环插件。把 iterate 生态的同一套 review/fix loop 直接搬进 dsh 界面。
-> The iterate ecosystem's convergence dashboard, triage UI, and review/fix loop, natively embedded inside the DeepSeek Harness (dsh) desktop client.
+> dsh 桌面端的 iterate 质量指挥中心 + 经验银行插件（v3.1）。把 iterate 生态的同一套 review/fix loop 直接搬进 dsh 界面，新增质量门禁、经验银行、防御事件流与原生指挥操作。
+> The iterate ecosystem's quality command center + experience bank plugin for dsh (v3.1). Natively embedded inside the DeepSeek Harness (dsh) desktop client with quality gates, experience bank, defense events stream, and native command buttons.
 
 <p align="center">
   <a href="README.md"><strong>English</strong></a> ·
@@ -61,7 +61,9 @@ dsh plugin --profile web add iterate-plugin
 
 `iterate-plugin` is the [iterate](https://github.com/jingzhao-l/iterate-skill) integration for the [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) desktop client. It brings iterate's review loop (review → triage → fix → validate → converge) directly into the dsh UI, offering **autonomous closed-loop code iteration** (normal mode) and **dry-run read-only multi-round review**.
 
-Besides 13 pure-function tools, it ships a **build-free Web UI layer** (triage panel, convergence dashboard, stats card, theme skin, etc.) that plugs straight into dsh's existing UI slots. Configuration (`iterate.config.yaml` and the review dimensions) is identical across the other two components of the iterate ecosystem ([skill](https://github.com/jingzhao-l/iterate-skill) / [headless engine](https://github.com/jingzhao-l/iterate-harness)) — zero migration cost.
+**v3.1 Quality Command Center**: The plugin has been upgraded from a "passive observation panel" to an "active command center + knowledge base". New features include quality gate view, experience bank, defense events stream, native command buttons, and task_mode indicator.
+
+Besides 17 pure-function tools, it ships a **build-free Web UI layer** (convergence dashboard, triage panel, stats card, observatory panel with 10 tabs, theme skin, etc.) that plugs straight into dsh's existing UI slots. Configuration (`iterate.config.yaml` and the review dimensions) is identical across the other two components of the iterate ecosystem ([skill](https://github.com/jingzhao-l/iterate-skill) / [headless engine](https://github.com/jingzhao-l/iterate-harness)) — zero migration cost.
 
 ## Features
 
@@ -81,23 +83,28 @@ Besides 13 pure-function tools, it ships a **build-free Web UI layer** (triage p
 | Fix atomic findings only, keep architectural for later | ❌ | ✅ |
 | Breakpoint save / resume (long iterations) | ✅ | ✅ |
 
-### Tool layer
+### Tool layer (v3.1: 17 tools)
 
-- **13 registered tools**: `iterate_config` / `iterate_validate` / `iterate_decision_log` / `iterate_context` / `iterate_review` / `iterate_triage` / `iterate_fix` / `iterate_diff` / `iterate_rollback` / `iterate_checkpoint` / `iterate_status` / `iterate_history` / `iterate_prune`
+- **17 registered tools** (14 original + 3 v3.1 quality command center tools):
+  - Original: `iterate_config` / `iterate_validate` / `iterate_decision_log` / `iterate_context` / `iterate_review` / `iterate_triage` / `iterate_fix` / `iterate_diff` / `iterate_rollback` / `iterate_checkpoint` / `iterate_status` / `iterate_history` / `iterate_prune` / `iterate_transcript`
+  - v3.1/v3.2: `iterate_experience` (list/search/get/**add**) / `iterate_quality_gate` (read/**compute**) / `iterate_defense_events` (list/counts/**record**)
 - **Findings triage loop**: review → UI triage (y/n/a) → `iterate_triage` writes back `known_intentional` → auto-filtered next round
 - **Structured fix system**: each fix backs up first, writes a registry entry, records the diff; a failed validation can be reverted with `iterate_rollback`
 - **Breakpoint resume**: checkpoints saved at the start of each round; interrupted long iterations can resume
 - **History audit**: `iterate_history` reads the decision log (filtered by type / time / count) and the fix registry summary to audit run process and fix details
 - **Runtime cleanup**: `iterate_prune` removes stale decision-log entries, stale checkpoints, orphaned fix backups and empty rounds; dry-run by default (report-only), real cleanup requires `dryRun:false`, and every cleanup is logged
 - **Config read / write**: `iterate_config` supports validated, backed-up, rollback-capable partial writes
+- **v3.1/v3.2 Experience Bank**: `iterate_experience` queries historical fixes and patterns with search/filter/adopt, and can persist new verified fixes (`add`) — re-adding the same pattern+dimension bumps its hit count instead of duplicating it
+- **v3.1/v3.2 Quality Gate**: `iterate_quality_gate` reads quality gate status with dimension convergence rates and PASS/FAIL, and can recompute + persist a fresh certificate (`compute`) from this round's findings/validation results (real convergence from `findingsByRound`)
+- **v3.1/v3.2 Defense Events**: `iterate_defense_events` queries defense events (precondition failures, rollbacks, invariant violations, assumption falsifications) and can `record` new ones; readable labels follow the project language (en/zh)
 
-### UI layer (build-free client slots)
+### UI layer (build-free client slots, v3.1: 10 tabs)
 
 | UI component | Mounted slot | Function |
 | --- | --- | --- |
-| ConvergenceDashboard | `conversation.input.dock` | Live round progress bar, severity stats, dimension badges, trend mini-chart above the input; normal mode also shows fix-count badges; plus a live workflow-phase chip (current phase + running/stopped) |
-| ObservatoryPanel | `conversation.input.dock` | Seven-tab runtime observatory below the input: live activity stream (type filter), review threads (expand/collapse all), convergence trend, finding locations (severity/dimension/search filter), fixes + rollback, checkpoint resume, decision timeline (type/round filter + search); one-click export of all observatory data to JSON (download, copy fallback) |
-| TriagePanel | `conversation.chat.turnTail` | Per-finding y/n/a triage, filtering, batch (incl. select-all), keyboard shortcuts, localStorage persistence, copy-YAML / apply-instruction |
+| ConvergenceDashboard | `conversation.input.dock` | Live round progress bar, severity stats, dimension badges, trend mini-chart above the input; normal mode also shows fix-count badges; plus a live workflow-phase chip (current phase + running/stopped); **v3.1: task_mode indicator (code/iterate)** |
+| ObservatoryPanel | `conversation.input.dock` | **Ten-tab** runtime observatory below the input: live activity stream (type filter), review threads (expand/collapse all), convergence trend, finding locations (severity/dimension/search filter), fixes + rollback, checkpoint resume, decision timeline (type/round filter + search); **v3.1: Quality Gate (F8)**, **Experience Bank (F9)**, **Defense Events (F10)**; one-click export of all observatory data to JSON (download, copy fallback) |
+| TriagePanel | `conversation.chat.turnTail` | Per-finding y/n/a triage, filtering, batch (incl. select-all), keyboard shortcuts, localStorage persistence, copy-YAML / apply-instruction; **v3.1: Native command buttons (approve architectural fix, trigger new round, rollback to checkpoint)** |
 | StatsCard | `conversation.chat.turnTail` | When no findings remain: convergence stats, round history table, trend chart, completion summary |
 | iterate theme skin | `theme.overrideTokens` | Warm-amber 13-dsw-token override, light/dark modes, togglable in settings |
 | ProgressCapsule | `shell.overlay` | Popup notification on each round completion / convergence (incl. convergence confirm) |
@@ -212,7 +219,7 @@ validation:
 
 > The config can be read and **validated-partially-written** via `iterate_config` (auto backup, auto rollback on write failure).
 
-## Registered tools (13)
+## Registered tools (v3.1: 17)
 
 | Tool | Function |
 | --- | --- |
@@ -229,6 +236,10 @@ validation:
 | `iterate_status` | Summarize current iteration state: mode, current/last round, fixes applied, remaining architectural, decision-log entry count, whether a checkpoint exists |
 | `iterate_history` | Read iteration history (read-only): decision-log entries (filter by `type` / `since` / `limit`, default latest 50, cap 200) + fix-registry summary (per-round fixed/failed counts). For auditing the run, tracing logs, and inventorying fixes |
 | `iterate_prune` | Clean runtime artifacts: stale decision-log entries (by `retainDays`, default 30), stale checkpoints, orphaned fix backups, empty rounds. Dry-run by default (report-only); real cleanup with `dryRun:false`, each cleanup logged |
+| `iterate_transcript` | Runtime observatory: persist review transcripts, threads, fixes, and nudge directions to `.iterate/transcript.json` for the client observatory |
+| `iterate_experience` | **v3.1/v3.2** Query the experience bank (list/search/get), or `add` a new verified fix: re-adding the same pattern+dimension bumps its hit count instead of duplicating it. Persists to `.iterate/experience.json` |
+| `iterate_quality_gate` | **v3.1/v3.2** Read the quality certificate (`read`), or recompute + persist a fresh one (`compute`) from findings, validation results, `findingsByRound`, and `fixedByDimension`. Real per-dimension convergence rates |
+| `iterate_defense_events` | **v3.1/v3.2** Query defense events (list/counts), or `record` a new one. Human-readable labels follow the project language (en/zh) |
 
 ## Runtime artifact layout
 
@@ -240,6 +251,9 @@ All runtime state lives under `.iterate/` at the project root (can be excluded v
   checkpoint.json         # iteration breakpoint (resume)
   transcript.json         # runtime-observatory manifest (per-reviewer threads, trend, fixes, timeline, nudge)
   transcript-live.ndjson  # append-only near-real-time reviewer-activity feed (read/fix/rollback/validate…), byte-capped
+  experience.json         # v3.1: experience bank (historical fixes and patterns, accumulated across sessions)
+  quality-gate.json       # v3.1: quality gate snapshot (dimension convergence, verification pass rates, PASS/FAIL)
+  defense-events.json     # v3.1: defense events stream (precondition failures, rollbacks, invariant violations, assumption falsifications)
   fixes/
     registry.json         # fix registry (list of FixRecords, grouped by round)
     <fix-id>_<ts>.bak     # original file backup before each fix
@@ -249,11 +263,12 @@ All runtime state lives under `.iterate/` at the project root (can be excluded v
 
 The plugin follows dsh's "everything-is-a-plugin" architecture:
 
-- **Does exactly two things**: injects the system prompt teaching the model the iterate workflow + registers 13 pure-function tools
+- **Does exactly two things**: injects the system prompt teaching the model the iterate workflow + registers 17 pure-function tools
 - **All orchestration runs through dsh native `workflow` + `agent` + `parallel`**
 - **Core logic is entirely pure functions** (dedupe / filter / sort / converge / meta-audit / diff computation / history filtering / cleanup reporting) — unit-testable, no I/O
 - **Security model**: file writes confined to the resolved project root (path-traversal protection); always back up before writing, roll back on failure; config writes also back up + roll back; `iterate_prune` is dry-run by default and only clears artifacts under `.iterate/` with every cleanup logged; `iterate_fix` caps content length and `iterate_triage` caps entry count to fend off abnormal oversized payloads
 - **Build-free UI**: `lib/client.js` uses a `React.createElement` tree + injected `<style>` tags, all colors via `--dsw-*` tokens, degrading gracefully when a service is missing
+- **v3.1 Quality Command Center**: extends the plugin from "passive observation panel" to "active command center + knowledge base" with quality gates, experience bank, defense events, and native command buttons
 - Follows the iterate skill's design principles: deterministic convergence, auditable, least privilege
 
 ## Running the tests
@@ -267,8 +282,8 @@ npm test
 
 All tests pass:
 
-- **212 unit tests green**, type-check clean
-- Coverage: dedupe, filter, sort, multi-round convergence, meta-review audit, path safety, timeout clamping, config read/write + rollback, triage merge, diff computation, checkpoint validation, fix registry, history read + filter, prune cleanup report + dry-run semantics, UI pure functions (select-all key, runtime status guide).
+- **426 unit tests green**, type-check clean
+- Coverage: dedupe, filter, sort, multi-round convergence, meta-review audit, path safety, timeout clamping, config read/write + rollback, triage merge, diff computation, checkpoint validation, fix registry, history read + filter, prune cleanup report + dry-run semantics, UI pure functions (select-all key, runtime status guide), **v3.1: experience bank, quality gate, defense events**.
 
 ## ⚠️ Disclaimer
 

package/dist/approval-gate.js

@@ -46,12 +46,26 @@ function describe(toolName, arguments0) {
  * deployments, and for any non-iterate tool.
  */
 export function decideApproval(execution, policy) {
-    const name = typeof execution?.name === 'string' ? execution.name : '';
+    // Defensive reads: a hostile/proxied execution object must degrade to "not
+    // our tool" (allow) rather than throw inside the gate.
+    let name = '';
+    try {
+        name = typeof execution?.name === 'string' ? execution.name : '';
+    }
+    catch {
+        name = '';
+    }
     if (!name)
         return { kind: 'allow' };
     if (!DESTRUCTIVE_TOOLS.has(name))
         return { kind: 'allow' };
-    const rawArgs = execution.arguments;
+    let rawArgs;
+    try {
+        rawArgs = execution.arguments;
+    }
+    catch {
+        rawArgs = undefined;
+    }
     const args = rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs)
         ? rawArgs
         : {};

package/dist/config-loader.js

@@ -191,6 +191,11 @@ export function validateConfig(config) {
  */
 export function resolveProjectRoot(input, sessionCwd) {
     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/dist/index.js

@@ -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
  */
@@ -35,13 +38,16 @@ import { registerCheckpointTool, registerStatusTool } from "./tools/checkpoint.j
 import { registerHistoryTool } from "./tools/history.js";
 import { registerPruneTool } from "./tools/prune.js";
 import { registerTranscriptTool } from "./tools/transcript.js";
+import { registerExperienceBankTool } from "./tools/experience-bank.js";
+import { registerQualityGateTool } from "./tools/quality-gate.js";
+import { registerDefenseEventsTool } from "./tools/defense-events.js";
 import { registerSessionHooks } from "./session-hooks.js";
 import { registerLiveCapture } from "./live.js";
 import { ITERATE_SKILL_PROMPT } from "./skill-prompt.js";
 export const name = 'iterate-plugin';
 export const inject = ['tools', 'systemPrompt'];
 export function apply(ctx) {
-    // 1. Register the 14 tools
+    // 1. Register the 17 tools (14 original + 3 v3.0)
     registerConfigTool(ctx);
     registerValidateTool(ctx);
     registerDecisionLogTool(ctx);
@@ -56,6 +62,10 @@ export function apply(ctx) {
     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.
     registerSessionHooks(ctx);

package/dist/session-hooks.js

@@ -32,17 +32,36 @@ import { decideApproval, isDestructiveIterateTool } from "./approval-gate.js";
  * Returns a dsh `PreToolDecision` so the caller can short-circuit the caller.
  */
 export function gateDecision(exec) {
-    // 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))
+    // 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.path === 'string'
-        ? exec.arguments.path
-        : undefined;
-    const sessionCwd = exec.agent?.session?.header?.cwd;
+    let argPath;
+    let sessionCwd;
+    try {
+        const args = exec?.arguments;
+        if (args && typeof args === 'object' && !Array.isArray(args)) {
+            const p = args.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';
     if (resolved.ok) {
@@ -67,13 +86,19 @@ export function gateDecision(exec) {
  */
 export function registerSessionHooks(ctx) {
     ctx.on('tools/pre-execute', (exec, next) => {
-        // 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;
         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/dist/skill-prompt.js

@@ -23,6 +23,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/dist/tools/decision-log.js

@@ -57,7 +57,7 @@ export function appendDecisionEntry(projectRoot, entry) {
         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;
@@ -202,6 +202,15 @@ export function registerDecisionLogTool(ctx) {
                     data,
                 };
                 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/dist/tools/defense-events.js

@@ -0,0 +1,260 @@
+/**
+ * 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 { resolveProjectRootForExec, loadEffectiveConfig } from "../config-loader.js";
+import { readDefenseEvents, writeDefenseEvents, addDefenseEvent } from "./defense-store.js";
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 100;
+const EVENT_TYPES = [
+    'precondition_failed',
+    'rollback',
+    'invariant_violated',
+    'assumption_falsified',
+];
+/** Clamp a caller-supplied limit to a sane range. */
+function clampLimit(limit) {
+    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 = {
+    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, language) {
+    const labels = EVENT_TYPE_LABELS[type];
+    return labels ? labels[language] : type;
+}
+/** Validate arguments for the record operation. */
+function validateRecordInput(args) {
+    const errors = [];
+    if (typeof args.type !== 'string' || !EVENT_TYPES.includes(args.type)) {
+        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) {
+    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 = value.language === 'zh' ? 'zh' : 'en';
+                if (value.operation === 'counts' && value.counts) {
+                    const counts = value.counts;
+                    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;
+                    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 ?? [];
+                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 = args.language === 'zh' || args.language === 'en' ? args.language : configLang;
+            const operation = typeof args.operation === 'string' ? args.operation : 'list';
+            const limit = clampLimit(args.limit);
+            if (operation === 'record') {
+                const errors = validateRecordInput(args);
+                if (errors.length > 0) {
+                    return {
+                        ok: false,
+                        kind: 'defense_events',
+                        operation: 'record',
+                        errors: errors,
+                        error: `Invalid defense event: ${errors.join('; ')}`,
+                    };
+                }
+                const stream = readDefenseEvents(projectRoot);
+                const next = addDefenseEvent(stream, {
+                    round: args.round,
+                    type: args.type,
+                    description: args.description,
+                    defense: args.defense,
+                    outcome: args.outcome,
+                    severity: args.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,
+                    counts: next.counts,
+                };
+            }
+            const stream = readDefenseEvents(projectRoot);
+            if (operation === 'counts') {
+                return {
+                    ok: true,
+                    kind: 'defense_events',
+                    operation: 'counts',
+                    language,
+                    counts: stream.counts,
+                };
+            }
+            // 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),
+            };
+        },
+    }));
+}