iterate-plugin 3.5.2 → 3.5.4

package/README.md

@@ -106,7 +106,7 @@ Both modes share:
 ### UI layer (build-free client slots, v3.2: 10 tabs)
 
 - **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) and a **v3.2 task_mode indicator (code / iterate)**, now backed by the persisted transcript (`iterate_status` / `iterate_transcript` emit `taskMode`).
-- **ObservatoryPanel** (`conversation.input.dock`) — a **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.2 tabs: Quality Gate (F8), Experience Bank (F9), Defense Events (F10)**; one-click JSON export of all observatory data (download, copy fallback). **v3.3: F8/F9/F10 are now live** — they scan the session stream for the latest `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` results and render real data (PASS/FAIL chip + per-dimension score bars, experience entries with adopt buttons + client-side search, defense type-count chips + filtered event stream), degrading to copy-able query instructions only when the session has none.
+- **ObservatoryPanel** (`conversation.input.dock`) — a **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.2 tabs: Quality Gate (F8), Experience Bank (F9), Defense Events (F10)**; one-click JSON export of all observatory data (download, copy fallback). **v3.3+: F8/F9/F10 are live** — they scan the session stream for the latest `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` results and render real data (PASS/FAIL chip + per-dimension score bars, experience entries with adopt buttons + client-side search, defense type-count chips + filtered event stream), degrading to copy-able query instructions only when the session has none. **v3.5.3: reset actions surfaced** — F5 copies an `iterate_checkpoint clear` instruction, F8 an `iterate_quality_gate clear` instruction, F10 an `iterate_defense_events clear` instruction.
 - **TriagePanel** (`conversation.chat.turnTail`) — per-finding y/n/a triage, filtering, batch ops (incl. select-all), keyboard shortcuts, localStorage persistence, copy-YAML / apply-instruction. **v3.2: native command buttons** (approve architectural fix, trigger new round, rollback to checkpoint). **v3.3: §8 指派修复 (assign)** — one click copies an `iterate_fix` instruction carrying every in-scope finding (respecting the batch toggle).
 - **StatsCard** (`conversation.chat.turnTail`) — convergence stats, round history, trend chart and completion summary when no findings remain.
 - **iterate theme skin** (`theme.overrideTokens`) — a warm-amber 13-token `--dsw-*` override, light/dark modes, togglable in settings.
@@ -255,14 +255,14 @@ validation:
 - `iterate_fix` — apply **one atomic fix**: validates the relative path, backs up the original file, enforces atomicity via `atomic.max_lines` (skippable with `force`), writes new content, records a FixRecord and an `atomic_fix` log. The only legal file-modifying entry in normal mode
 - `iterate_diff` — view accumulated fix changes: with `file`, returns the unified diff against the first backup; without it, a per-fixed-file summary
 - `iterate_rollback` — roll back an applied fix: restore the file from backup, remove that FixRecord from the registry, append a `revert` log. Used after a failed round validation
-- `iterate_checkpoint` — iteration breakpoint: `save` persists progress to `.iterate/checkpoint.json`, `load` reads it back, `resume` loads + bumps the resume counter (interruption recovery), `clear` removes it. Resumable interrupted long iterations
+- `iterate_checkpoint` — iteration breakpoint: `save` persists progress to `.iterate/checkpoint.json`, `load` reads it back, `resume` loads + bumps the resume counter (interruption recovery), `clear` removes it (bounded findings payload, `round ≤ maxRounds` enforced). Resumable interrupted long iterations
 - `iterate_status` — summarize current iteration state: mode, current/last round, fixes applied, remaining architectural, decision-log entry count, whether a checkpoint exists; **v3.4: also surfaces the persisted quality-gate snapshot, experience-bank summary, and defense-events summary** (`qualityGate` / `experienceBank` / `defenseEvents`)
 - `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, stray temp files (crashed atomic writes). 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.2** query the experience bank (list / search / get), `add` a new verified fix (re-adding the same pattern+dimension bumps its hit count instead of duplicating it), or **v3.5 remove a stale/incorrect entry by `id`** so bad experiences never resurface. Persists to `.iterate/experience.json`
 - `iterate_quality_gate` — **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. **v3.5: `clear` removes the persisted certificate to reset a stale gate before a fresh iteration**
-- `iterate_defense_events` — **v3.2** query defense events (list / counts), or `record` a new one. Human-readable labels follow the project language (en / zh)
+- `iterate_defense_events` — **v3.2** query defense events (list / counts), `record` a new one, or **v3.5.3 `clear` the persisted stream** so a fresh iteration starts without stale defensive data. Human-readable labels follow the project language (en / zh)
 
 ---
 

package/README.zh-CN.md

@@ -105,7 +105,7 @@ dsh plugin --profile web add iterate-plugin
 ### UI 层（客户端免构建槽位，v3.2：10 个标签页）
 
 - **收敛看板 `ConvergenceDashboard`**（`conversation.input.dock`）— 输入框上方实时显示轮次进度条、严重度统计、维度徽章、趋势迷你图；normal 模式另显示修复计数徽章；还有运行阶段芯片（当前工作流阶段 + 运行中/已结束）与 **v3.2 task_mode 指示器（code / iterate）**。
-- **运行时观测台 `ObservatoryPanel`**（`conversation.input.dock`）— 输入框下方**十个标签页**运行时观测台：实时活动流（支持按活动类型筛选）、审查线程（支持全部展开/全部收起）、收敛趋势、发现定位（支持按严重度/维度/关键词筛选）、修复与回滚、断点恢复、决策时间线（支持按类型/轮次筛选与关键词搜索）。**v3.2 新增标签：质量门禁（F8）、经验银行（F9）、防御事件（F10）**；支持一键导出全部观测数据为 JSON（优先下载，失败回退复制）。
+- **运行时观测台 `ObservatoryPanel`**（`conversation.input.dock`）— 输入框下方**十个标签页**运行时观测台：实时活动流（支持按活动类型筛选）、审查线程（支持全部展开/全部收起）、收敛趋势、发现定位（支持按严重度/维度/关键词筛选）、修复与回滚、断点恢复、决策时间线（支持按类型/轮次筛选与关键词搜索）。**v3.2 新增标签：质量门禁（F8）、经验银行（F9）、防御事件（F10）**；支持一键导出全部观测数据为 JSON（优先下载，失败回退复制）。**v3.5.3 新增重置操作**：F5 复制 `iterate_checkpoint clear`、F8 复制 `iterate_quality_gate clear`、F10 复制 `iterate_defense_events clear` 指令。
 - **Findings 分诊面板 `TriagePanel`**（`conversation.chat.turnTail`）— 逐条 y/n/a 判定，支持筛选、批量（含一键全选所有 findings）、键盘快捷键、localStorage 持久化、复制 YAML / 应用指令。**v3.2：原生命令按钮**（批准架构修复、触发新一轮、回滚到断点）。
 - **收敛统计卡片 `StatsCard`**（`conversation.chat.turnTail`）— 无 findings 时显示收敛统计、历史轮次、趋势图、完成摘要。
 - **iterate 主题皮肤**（`theme.overrideTokens`）— 暖琥珀配色的 13 个 `--dsw-*` token 覆盖，明暗双模式，可在设置页开关。
@@ -254,14 +254,14 @@ validation:
 - `iterate_fix` — 应用**一个原子修复**：校验相对路径、备份原文件、按 `atomic.max_lines` 强制原子性（可 `force` 跳过）、写入新内容、记录 FixRecord 与 `atomic_fix` 日志。normal 模式唯一合法的改文件入口
 - `iterate_diff` — 查看修复累积变更：指定 `file` 返回相对首个备份的 unified diff；省略则返回每个已修复文件的汇总
 - `iterate_rollback` — 回滚一个已应用的修复：从备份还原文件、从注册表移除该 FixRecord、追加 `revert` 日志。用于某轮验证失败后
-- `iterate_checkpoint` — 迭代断点：`save` 保存当前进度到 `.iterate/checkpoint.json`，`load` 读回，`resume` 加载并累加恢复计数（中断恢复），`clear` 清除。长迭代可中断续跑
+- `iterate_checkpoint` — 迭代断点：`save` 保存当前进度到 `.iterate/checkpoint.json`，`load` 读回，`resume` 加载并累加恢复计数（中断恢复），`clear` 清除（findings 载荷有上限，强制 `round ≤ maxRounds`）。长迭代可中断续跑
 - `iterate_status` — 汇总当前迭代状态：模式、当前轮/总轮、已修复数、剩余 architectural、决策日志条数、是否存在 checkpoint；**v3.4：同时返回持久化的质量门禁快照、经验银行摘要与防御事件摘要**（`qualityGate` / `experienceBank` / `defenseEvents`）
 - `iterate_history` — 读取迭代历史（只读）：决策日志条目（可按 `type` / `since` / `limit` 过滤，默认取最新 50 条，上限 200 条）+ 修复注册表汇总（各轮 fixed/failed 计数）。用于审查运行过程、审计日志、盘点修复
 - `iterate_prune` — 清理运行时产物：过期决策日志条目（按 `retainDays`，默认 30 天）、陈旧断点、孤儿修复备份、空轮次、崩溃原子写入残留的临时文件。默认 dry-run 只报告不删除；`dryRun:false` 才真正清理，每次清理写入决策日志
 - `iterate_transcript` — 运行时观测台：把审查转录、线程、修复与 nudge 指令持久化到 `.iterate/transcript.json`，供客户端观测台读取
 - `iterate_experience` — **v3.2** 查询经验银行（list / search / get），或 `add` 一条新的已验证修复：重复添加同一 pattern + dimension 累加命中次数而非重复写入。**v3.5 新增 `remove`：按 `id` 删除过时或错误的经验条目**。持久化到 `.iterate/experience.json`
 - `iterate_quality_gate` — **v3.2** 读取质量凭证（`read`），或基于 findings、验证结果、`findingsByRound` 与 `fixedByDimension` 重新计算并持久化一份新凭证（`compute`）。真实的逐维度收敛率。**v3.5 新增 `clear`：删除持久化的质量凭证**，用于新一轮迭代前重置陈旧的门禁
-- `iterate_defense_events` — **v3.2** 查询防御事件（list / counts），或 `record` 记录一条新事件。可读标签跟随项目语言（en / zh）
+- `iterate_defense_events` — **v3.2** 查询防御事件（list / counts），`record` 记录一条新事件，或 **v3.5.3 `clear` 清除持久化事件流**，让新一轮迭代不带陈旧防御数据起跑。可读标签跟随项目语言（en / zh）
 
 ---
 

package/dist/session-hooks.js

@@ -7,12 +7,22 @@
  *
  *   - `allow` policy      → the call runs.
  *   - `deny`  policy      → the call is refused (fail-closed), surfaced as an
- *                           error to the model.
+ *                           error to the model. Since dsh 0.1.6-alpha.1 the
+ *                           denial carries a structured `info` (name
+ *                           `iterate-approval-gate`, code `APPROVAL_DENIED`,
+ *                           plus the human-readable reason) so durable
+ *                           projections can route it distinctly from a normal
+ *                           tool failure.
  *   - `ask`   policy      → return `{ kind: 'ask', reason }`; dsh's own
  *                           scheduler routes it through the `approval` service
  *                           (see `@deepseek-ai/dsh-user-approval`), which
  *                           prompts the human and audits an approve/deny pair
  *                           on the session.
+ *   - canceled            → if the caller aborted the invocation before
+ *                           dispatch, return `{ kind: 'cancel' }` (the
+ *                           canonical 0.1.6-alpha.1 cancellation result) so a
+ *                           destructive call never runs (or asks) for a dead
+ *                           request.
  *
  * We deliberately do NOT also add `approved` flags inside the tool bodies:
  * the pre-execute waterfall consumes the human decision before the tool runs,
@@ -27,6 +37,13 @@
  */
 import { loadEffectiveConfig, resolveProjectRoot } from "./config-loader.js";
 import { decideApproval, isDestructiveIterateTool } from "./approval-gate.js";
+/** Structured error identity attached to policy denials (dsh 0.1.6-alpha.1:
+ *  `deny.info` lets durable projections / retry / replay distinguish an
+ *  approval-policy denial from a tool-thrown failure). */
+const DENY_INFO = {
+    name: 'iterate-approval-gate',
+    code: 'APPROVAL_DENIED',
+};
 /**
  * Build the per-call approval decision for a tool execution.
  * Returns a dsh `PreToolDecision` so the caller can short-circuit the caller.
@@ -46,6 +63,20 @@ export function gateDecision(exec) {
     }
     if (!isDestructiveIterateTool(name))
         return { kind: 'allow' };
+    // dsh 0.1.6-alpha.1: if the caller already aborted this invocation before
+    // dispatch, there is nothing to gate — select the canonical cancellation
+    // result (`cancel`) rather than prompting a human for a dead call or running
+    // `next()` (which would allow) on an aborted one.
+    let signal;
+    try {
+        signal = exec.signal;
+    }
+    catch {
+        signal = undefined;
+    }
+    if (signal && typeof signal.aborted === 'boolean' && signal.aborted) {
+        return { kind: 'cancel' };
+    }
     // Resolve the project root (use the call's own `path` arg, else the agent's
     // session cwd) to read the effective observatory policy.
     let argPath;
@@ -74,8 +105,18 @@ export function gateDecision(exec) {
         // anything else (including a corrupt/missing `ask`) → 'ask'
     }
     const decision = decideApproval(exec, policy);
-    if (decision.kind === 'deny')
-        return { kind: 'deny', reason: decision.reason };
+    if (decision.kind === 'deny') {
+        return {
+            kind: 'deny',
+            reason: decision.reason,
+            info: {
+                ...DENY_INFO,
+                // ToolErrorInfo.reason (0.1.6-alpha.1): raw user-facing detail kept in
+                // durable state; the model-facing text still only sees `reason` above.
+                reason: decision.reason,
+            },
+        };
+    }
     if (decision.kind === 'ask')
         return { kind: 'ask', reason: decision.reason };
     return { kind: 'allow' };
@@ -106,7 +147,10 @@ export function registerSessionHooks(ctx) {
             // to allow, which would bypass consent — so return our ask decision.
             return Promise.resolve(decision);
         }
-        if (decision.kind === 'deny') {
+        if (decision.kind === 'deny' || decision.kind === 'cancel') {
+            // deny: refuse the call. cancel: the caller already aborted this
+            // invocation — selecting the canonical cancellation result instead of
+            // letting `next()` allow it or prompting consent for a dead request.
             return Promise.resolve(decision);
         }
         return next();

package/dist/skill-prompt.js

@@ -94,10 +94,11 @@ for (let r = 1; r <= maxRounds; r++) {
   log('round ' + r + ' of ' + maxRounds + ' — finding NEW issues only')
   let agg = null
   let schemaInvalid = false
-  let retries = 0
+  let attempts = 0
   do {
+    attempts += 1
     // Schema validation retry: on the 2nd+ pass, nudge reviewers toward strict JSON.
-    const nudge = retries > 0
+    const nudge = attempts > 1
       ? '\\nSTRICT JSON REQUIRED: your previous output failed schema validation. Return ONLY a JSON object {"findings":[...]} where EVERY finding has dimension, file, line (non-negative integer; 0 = whole-file), severity (critical|high|medium|low), summary, failure_scenario, suggested_fix, is_atomic (boolean).'
       : ''
     const raw = await parallel(dims.map(dim => () => {
@@ -134,11 +135,15 @@ for (let r = 1; r <= maxRounds; r++) {
     schemaInvalid = agg && agg.schemaValidation && agg.schemaValidation.length > 0
       ? agg.schemaValidation[agg.schemaValidation.length - 1].valid === false
       : false
-    if (schemaInvalid && retries < 2) {
-      retries += 1
-      log('retry ' + retries + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
+    if (schemaInvalid && attempts < 3) {
+      log('retry ' + attempts + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
     }
-  } while (schemaInvalid && retries <= 2)
+  } while (schemaInvalid && attempts < 3)
+  if (schemaInvalid) {
+    // Bounded exit: never loop forever. Surface the failure so the run's
+    // final summary can explain WHY the round was inconclusive.
+    log('round ' + r + ' output STILL schema-invalid after 3 attempts — marking round inconclusive (NOT converged)')
+  }
   // Feed the DEDUPED + already-filtered set back (not raw findings) so the known
   // list stays bounded and reviewers never see the same issue twice.
   if (agg && agg.report && Array.isArray(agg.report.findings)) known = agg.report.findings
@@ -269,6 +274,7 @@ let fixedCount = (checkpoint && typeof checkpoint.fixedCount === 'number') ? che
 let converged = false
 let abortedByValidation = false
 let failedCommands = []
+let configErrors = []          // validation commands NOT in validation.commands (config gap, no rollback)
 const fixRecords = []        // observatory fix records collected round by round
 
 // Read any steering nudge intended for this run's reviewers.
@@ -288,10 +294,11 @@ for (let r = startRound; r <= maxRounds; r++) {
   )
   let agg = null
   let schemaInvalid = false
-  let retries = 0
+  let attempts = 0
   do {
+    attempts += 1
     // Schema validation retry: on the 2nd+ pass, nudge reviewers toward strict JSON.
-    const nudge = retries > 0
+    const nudge = attempts > 1
       ? '\\nSTRICT JSON REQUIRED: your previous output failed schema validation. Return ONLY a JSON object {"findings":[...]} where EVERY finding has dimension, file, line (non-negative integer; 0 = whole-file), severity (critical|high|medium|low), summary, failure_scenario, suggested_fix, is_atomic (boolean).'
       : ''
     const raw = await parallel(dims.map(dim => () => {
@@ -327,11 +334,15 @@ for (let r = startRound; r <= maxRounds; r++) {
     schemaInvalid = agg && agg.schemaValidation && agg.schemaValidation.length > 0
       ? agg.schemaValidation[agg.schemaValidation.length - 1].valid === false
       : false
-    if (schemaInvalid && retries < 2) {
-      retries += 1
-      log('retry ' + retries + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
+    if (schemaInvalid && attempts < 3) {
+      log('retry ' + attempts + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
     }
-  } while (schemaInvalid && retries <= 2)
+  } while (schemaInvalid && attempts < 3)
+  if (schemaInvalid) {
+    // Bounded exit: never loop forever. Surface the failure so the run's
+    // final summary can explain WHY the round was inconclusive.
+    log('round ' + r + ' output STILL schema-invalid after 3 attempts — marking round inconclusive (NOT converged)')
+  }
   const findings = (agg && agg.report && agg.report.findings) ? agg.report.findings : thisRound.findings
   const atomic = findings.filter(f => f.is_atomic === true)
   const remaining = findings.filter(f => f.is_atomic !== true)
@@ -386,18 +397,33 @@ for (let r = startRound; r <= maxRounds; r++) {
     if (seenKeys.indexOf(key) < 0) { architectural.push(f); seenKeys.push(key) }
   }
 
-  // Validate every configured command; on ANY failure roll back this round's fixes.
+  // Validate every configured command; on ANY *executed* failure roll back this
+  // round's fixes. iterate_validate returns \`allowed:false\` + \`rejectReason\`
+  // when a command is NOT in validation.commands (a config gap, NOT a code
+  // failure) — those abort the run WITHOUT rolling back (the code changes are
+  // fine; the trust list just needs fixing).
   const valRes = await agent(
     'Read iterate.config.yaml validation.commands, then call iterate_validate({ command: <cmd> }) for EACH configured command ' +
-    '(one tool call per command). Return all results as {command, exitCode} entries.',
+    '(one tool call per command). Return all results as {command, exitCode, allowed, rejectReason} entries — include \`allowed\` and \`rejectReason\` exactly as returned by iterate_validate (allowed:false means the command is not in validation.commands).',
     Object.assign({ label: 'validate:r' + r, phase: 'validate', schema: {
       type: 'object', additionalProperties: false,
       properties: {
-        results: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { command: { type: 'string' }, exitCode: { type: 'integer' } }, required: ['command', 'exitCode'] } }
+        results: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { command: { type: 'string' }, exitCode: { type: 'integer' }, allowed: { type: 'boolean' }, rejectReason: { type: 'string' } }, required: ['command', 'exitCode'] } }
       },
       required: ['results'] } }, backend)
   )
-  failedCommands = (valRes && Array.isArray(valRes.results)) ? valRes.results.filter(v => v.exitCode !== 0).map(v => v.command) : []
+  const valResults = (valRes && Array.isArray(valRes.results)) ? valRes.results : []
+  configErrors = valResults.filter(v => v.allowed === false).map(v => v.rejectReason || (v.command + ' was rejected'))
+  failedCommands = valResults.filter(v => !(v.allowed === false) && v.exitCode !== 0).map(v => v.command)
+  if (configErrors.length > 0) {
+    log('round ' + r + ' validation CONFIG error (not in validation.commands): ' + configErrors.join(' | ') + ' — aborting WITHOUT rollback (code changes are kept; the command trust list needs updating)')
+    abortedByValidation = true
+    await agent(
+      'Call iterate_decision_log({operation:"append", type:"round_failed", round:' + r + ', data:{configErrors:' + JSON.stringify(configErrors) + ', rolledBack:0, reason:"command not in validation.commands"}})',
+      Object.assign({ label: 'log:configError:r' + r }, backend)
+    )
+    break
+  }
   if (failedCommands.length > 0) {
     log('round ' + r + ' validation FAILED on: ' + failedCommands.join(', ') + ' — rolling back this round')
     abortedByValidation = true
@@ -458,17 +484,23 @@ if (!abortedByValidation) {
 }
 // Persist the run's observatory transcript (threads, trend, fixes, checkpoint)
 // so the client observatory panel reflects the run. Writes ONLY .iterate/transcript.json.
-const obsCheckpoint = abortedByValidation ? null : {
-  mode: 'normal',
-  round: rounds.length,
-  maxRounds: maxRounds,
-  fixedCount: fixedCount,
-  resumeCount: effectiveResumeCount,
-}
-await agent(
-  'Call iterate_transcript({operation:"capture", mode:"normal", goal:' + JSON.stringify(plan.goal) + ', maxRounds:' + maxRounds + ', roundsExecuted:' + rounds.length + ', findingsByRound:' + JSON.stringify(rounds.map(rr => (rr.findings && rr.findings.length) ? rr.findings.length : 0)) + ', fixes:' + JSON.stringify(fixRecords) + ', checkpoint:' + JSON.stringify(obsCheckpoint) + ', rounds:' + JSON.stringify(rounds.map(rr => ({ round: rr.round, findings: rr.findings, readFiles: rr.readFiles }))) + '}). Return {operation:"ok"}.',
-  { label: 'transcript:capture' }
-)
+// The checkpoint survives on disk for aborted runs (that is how resumption
+  // works), so the transcript must mirror that reality — a null checkpoint here
+  // would hide the very thing F5 is meant to resume. Reflect what is on disk.
+  const obsCheckpoint = {
+    mode: 'normal',
+    round: rounds.length,
+    maxRounds: maxRounds,
+    fixedCount: fixedCount,
+    resumeCount: effectiveResumeCount,
+  }
+  const stopReason = abortedByValidation
+    ? (configErrors.length > 0 ? 'aborted_by_config' : 'aborted_by_validation')
+    : (converged ? 'converged' : 'max_rounds_reached')
+  await agent(
+    'Call iterate_transcript({operation:"capture", mode:"normal", goal:' + JSON.stringify(plan.goal) + ', maxRounds:' + maxRounds + ', roundsExecuted:' + rounds.length + ', findingsByRound:' + JSON.stringify(rounds.map(rr => (rr.findings && rr.findings.length) ? rr.findings.length : 0)) + ', stoppedReason:"' + stopReason + '", fixes:' + JSON.stringify(fixRecords) + ', checkpoint:' + JSON.stringify(obsCheckpoint) + ', rounds:' + JSON.stringify(rounds.map(rr => ({ round: rr.round, findings: rr.findings, readFiles: rr.readFiles }))) + '}). Return {operation:"ok"}.',
+    { label: 'transcript:capture' }
+  )
 return {
   mode: 'normal',
   goal: plan.goal,
@@ -477,6 +509,8 @@ return {
   converged: converged,
   abortedByValidation: abortedByValidation,
   failedCommands: failedCommands,
+  configErrors: configErrors,
+  stoppedReason: stopReason,
   findingsFixed: fixedCount,
   remainingArchitecturalCount: architectural.length,
   remainingArchitectural: architectural,
@@ -494,10 +528,10 @@ return {
 Key rules for normal mode:
 - Fixers are the ONLY agents allowed to write files, and they must go through \`iterate_fix\` — never edit files directly. That is what gives every change a backup, a diff, and a rollback path. Reviewers read only. Architectural findings are reported, never auto-fixed.
 - Aggregate the current round deterministically (\`report.findings\`) before fixing, so fixes act on deduped/filtered/sorted findings.
-- **Schema validation & retry**: when \`reviewer.output_schema_validation\` is on (default), retry the round's reviewers up to 2 times when \`aggregate\` reports \`schemaValidation\` valid=false for it, then re-aggregate. Never forward schema-invalid findings into \`iterate_fix\`.
+- **Schema validation & retry**: when \`reviewer.output_schema_validation\` is on (default), retry the round's reviewers up to 2 times (3 attempts total) when \`aggregate\` reports \`schemaValidation\` valid=false for it, then re-aggregate. Never forward schema-invalid findings into \`iterate_fix\`. If the output is still schema-invalid after the 3rd attempt, mark the round inconclusive (never report it as a clean convergence).
 - Apply atomic fixes **per file**: one fixer agent handles all findings for a given file serially (so the same file is never edited concurrently); different files are fixed in parallel.
 - **Resume**: load the checkpoint first; if a previous run left one, continue from \`checkpoint.round + 1\` (its \`fixedCount\` and deduped \`findings\` are carried forward).
-- **Validate after every round** of fixes; on ANY validation failure, roll back the round's fixes via \`iterate_rollback\` and stop (the checkpoint is left in place so the run can be resumed).
+- **Validate after every round** of fixes; on ANY validation failure, roll back the round's fixes via \`iterate_rollback\` and stop (the checkpoint is left in place so the run can be resumed). EXCEPTION: \`iterate_validate\` returning \`allowed:false\` means the command is simply not in \`validation.commands\` — a config gap, not broken code. In that case abort WITHOUT rolling back the round's fixes and surface the missing command + file so the user can fix the trust list.
 - **Checkpoint after every round**; clear it only when the iteration completes cleanly.
 - Stop when a round produces nothing to fix (converged) or maxReviewRounds is reached.
 - Every round, every rollback, and the final report go to the append-only decision log.

package/dist/tools/checkpoint.js

@@ -19,6 +19,9 @@ import { readQualityGate } from "./quality-store.js";
 import { readExperienceBank } from "./experience-store.js";
 import { readDefenseEvents } from "./defense-store.js";
 // ─── Pure helpers (exported for unit tests) ─────────────────────────────────
+/** Max findings persisted in a checkpoint (a model-authored findings payload is
+ *  bounded, mirroring MAX_FIX_CONTENT_CHARS for fix content). */
+export const MAX_CHECKPOINT_FINDINGS = 1000;
 /** Read the current checkpoint from disk (missing/corrupt → null). */
 export function readCheckpoint(projectRoot) {
     const file = checkpointPath(projectRoot);
@@ -30,9 +33,28 @@ export function readCheckpoint(projectRoot) {
             return null;
         if (parsed.mode !== 'dry-run' && parsed.mode !== 'normal')
             return null;
-        if (typeof parsed.round !== 'number')
+        // Strict round gate: non-numeric (incl. NaN — `NaN <= 0` is false and
+        // `NaN < 0` also false) round values must not survive into the status.
+        const round = typeof parsed.round === 'number' && Number.isFinite(parsed.round)
+            ? Math.floor(parsed.round)
+            : null;
+        if (round === null || round < 0)
             return null;
-        return parsed;
+        const num = (v, fallback) => typeof v === 'number' && Number.isFinite(v) ? v : fallback;
+        // Normalize every field so a hand-edited/corrupt checkpoint (string
+        // maxRounds, missing fixedCount, …) can never leak a non-numeric value
+        // into the status output or crash a consumer.
+        return {
+            mode: parsed.mode,
+            round,
+            maxRounds: num(parsed.maxRounds, round),
+            fixedCount: num(parsed.fixedCount, 0),
+            architecturalCount: num(parsed.architecturalCount, 0),
+            resumeCount: num(parsed.resumeCount, 0),
+            findings: Array.isArray(parsed.findings) ? parsed.findings : [],
+            startedAt: typeof parsed.startedAt === 'string' ? parsed.startedAt : new Date().toISOString(),
+            updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+        };
     }
     catch {
         return null;
@@ -73,6 +95,15 @@ export function validateCheckpoint(input) {
         (typeof input.resumeCount !== 'number' || !Number.isInteger(input.resumeCount) || input.resumeCount < 0)) {
         return 'resumeCount must be a non-negative integer';
     }
+    // A round that claims to be past the configured cap is an inconsistent save —
+    // the status would render `Round X / Y` with X > Y, which is never legitimate
+    // for a resumed run (resume continues AT the checkpoint, it does not exceed
+    // the cap).
+    if (typeof input.round === 'number' &&
+        typeof input.maxRounds === 'number' &&
+        input.round > input.maxRounds) {
+        return 'round must not exceed maxRounds';
+    }
     return null;
 }
 /**
@@ -95,8 +126,11 @@ export function computeStatus(input) {
         }
     }
     const totalRounds = checkpoint?.maxRounds ?? currentRound;
-    const registryFixed = registry.rounds.reduce((sum, r) => sum + r.fixedCount, 0);
-    const failedCount = registry.rounds.reduce((sum, r) => sum + r.failedCount, 0);
+    // Coerce the registry's per-round counts defensively: a hand-edited registry
+    // round missing fixedCount/failedCount would otherwise feed NaN into the
+    // status integer fields.
+    const registryFixed = registry.rounds.reduce((sum, r) => sum + (Number(r.fixedCount) || 0), 0);
+    const failedCount = registry.rounds.reduce((sum, r) => sum + (Number(r.failedCount) || 0), 0);
     // When a checkpoint exists, its snapshot fields are authoritative for resume
     // (fixedCount / architecturalCount / findings); otherwise derive from the
     // live fix registry and decision log.
@@ -230,7 +264,7 @@ export function registerCheckpointTool(ctx) {
                     fixedCount: args.fixedCount,
                     architecturalCount: args.architecturalCount,
                     resumeCount: (typeof args.resumeCount === 'number' ? args.resumeCount : 0),
-                    findings: (Array.isArray(args.findings) ? args.findings : []),
+                    findings: (Array.isArray(args.findings) ? args.findings.slice(0, MAX_CHECKPOINT_FINDINGS) : []),
                     startedAt: readCheckpoint(projectRoot)?.startedAt ?? new Date().toISOString(),
                     updatedAt: new Date().toISOString(),
                 };

package/dist/tools/config.js

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
+import { existsSync } from 'node:fs';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from "../config-loader.js";
+import { defaultConfig, loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from "../config-loader.js";
 import { applyConfigUpdates, readRawConfig, validateConfigUpdates, writeConfigFile, } from "../config-write.js";
 /**
  * Register the `iterate_config` tool.
@@ -91,7 +92,15 @@ export function registerConfigTool(ctx) {
                 }
                 let base;
                 try {
-                    base = readRawConfig(join(projectRoot, 'iterate.config.yaml'));
+                    // Partial updates must be mergeable on a FRESH project (no config
+                    // file yet): otherwise `{max_rounds: 5}` alone fails schema
+                    // validation with a misleading "missing goal". Merge against the
+                    // built-in defaults when there is no file to read, so the written
+                    // config captures the effective config (defaults + update) and the
+                    // documented "write a partial update" contract works out of the box.
+                    base = existsSync(join(projectRoot, 'iterate.config.yaml'))
+                        ? readRawConfig(join(projectRoot, 'iterate.config.yaml'))
+                        : defaultConfig();
                 }
                 catch (err) {
                     return { operation: 'write', ok: false, found: false, error: `failed to read config: ${String(err)}` };

package/dist/tools/context.js

@@ -306,7 +306,11 @@ export function registerContextTool(ctx) {
                         // skillDir point at arbitrary filesystem locations (e.g. /etc)
                         // whose contents would be injected wholesale into the context.
                         if (isAllowedSkillDir(args.skillDir, [projectRoot, PLUGIN_SRC_DIR])) {
-                            candidates.push(resolve(args.skillDir));
+                            // Read from the REAL (symlink-resolved) path that was actually
+                            // validated — never the raw path. Validating one path and then
+                            // reading through a different (swappable) symlink would leave a
+                            // check-vs-read TOCTOU gap; using the realpath here closes it.
+                            candidates.push(realpathSync(resolve(args.skillDir)));
                         }
                     }
                     catch {

package/dist/tools/defense-events.js

@@ -10,7 +10,7 @@
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec, loadEffectiveConfig } from "../config-loader.js";
-import { readDefenseEvents, writeDefenseEvents, addDefenseEvent } from "./defense-store.js";
+import { readDefenseEvents, writeDefenseEvents, addDefenseEvent, clearDefenseEvents } from "./defense-store.js";
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 100;
 const EVENT_TYPES = [
@@ -72,19 +72,25 @@ function validateRecordInput(args) {
 export function registerDefenseEventsTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_defense_events',
-        // List/counts never write; only `record` persists an event → read shapes
-        // join a parallel dispatch group.
-        isConcurrencySafe: (args) => args.operation !== 'record',
-        description: 'Query or record defense events: precondition failures, rollbacks, invariant violations, ' +
+        // List/counts never write; `record` persists an event and `clear` removes
+        // the persisted stream, so only the read shapes may join a parallel
+        // dispatch group.
+        isConcurrencySafe: (args) => {
+            const op = args.operation;
+            return op !== 'record' && op !== 'clear';
+        },
+        description: 'Query, record, or clear 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. ' +
+            '"record" persists a new event to .iterate/defense-events.json; ' +
+            '"clear" resets the persisted event stream (use it to start a fresh iteration without stale ' +
+            'defense data). ' +
             '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'],
+                description: 'Operation: list (browse all), counts (summary by type), record (log a new event), clear (reset the stream). Default: list.',
+                enum: ['list', 'counts', 'record', 'clear'],
             },
             type: {
                 type: 'string',
@@ -141,6 +147,7 @@ export function registerDefenseEventsTool(ctx) {
                     kind: { type: 'string' },
                     operation: { type: 'string' },
                     count: { type: 'integer' },
+                    counted: { type: 'boolean', description: 'clear only: true when a persisted stream was removed.' },
                     events: { type: 'json' },
                     counts: { type: 'json' },
                     event: { type: 'json' },
@@ -153,6 +160,16 @@ export function registerDefenseEventsTool(ctx) {
                 if (!value.ok)
                     return [{ type: 'text', text: `defense events query failed: ${value.error}` }];
                 const language = value.language === 'zh' ? 'zh' : 'en';
+                if (value.operation === 'clear') {
+                    // Fresh stream: counts are all zero and the event list is empty.
+                    return [{ type: 'text', text: [
+                                value.counted === true
+                                    ? 'Defense event stream cleared — a fresh iteration starts with an empty stream.'
+                                    : 'No persisted defense event stream to clear.',
+                                'Defense Event Summary:',
+                                ...EVENT_TYPES.map((type) => `  ${labelFor(type, language)}: 0`),
+                            ].join('\n') }];
+                }
                 if (value.operation === 'counts' && value.counts) {
                     const counts = value.counts;
                     const lines = [
@@ -193,10 +210,32 @@ export function registerDefenseEventsTool(ctx) {
             if (!resolved.ok)
                 return { ok: false, kind: 'defense_events', error: resolved.reason };
             const projectRoot = resolved.root;
-            const configLang = loadEffectiveConfig(projectRoot).config.language;
+            // A hand-edited `language` value outside zh/en must not leak out of the
+            // declared 'zh' | 'en' enum (labelFor would return undefined for it) —
+            // normalize any non-'zh' config value to 'en'.
+            const rawConfigLang = loadEffectiveConfig(projectRoot).config.language;
+            const configLang = rawConfigLang === 'zh' ? 'zh' : 'en';
             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 === 'clear') {
+                // Reset the persisted event stream so a fresh iteration does not carry
+                // stale defensive data (mirrors iterate_quality_gate clear / clearQualityGate).
+                const result = clearDefenseEvents(projectRoot);
+                if (!result.ok) {
+                    return { ok: false, kind: 'defense_events', operation: 'clear', error: result.error };
+                }
+                const empty = readDefenseEvents(projectRoot);
+                return {
+                    ok: true,
+                    kind: 'defense_events',
+                    operation: 'clear',
+                    counted: result.existed,
+                    language,
+                    counts: empty.counts,
+                    events: empty.events,
+                };
+            }
             if (operation === 'record') {
                 const errors = validateRecordInput(args);
                 if (errors.length > 0) {