iterate-plugin 3.5.2 → 3.5.3

package/dist/tools/prune.js

@@ -87,17 +87,25 @@ export function inspectPrune(projectRoot, retainDays) {
     }
     const staleBackups = [];
     const fixDir = fixesDir(projectRoot);
-    if (existsSync(fixDir)) {
-        for (const entry of readdirSync(fixDir)) {
-            if (!entry.endsWith('.bak'))
-                continue;
-            // Extract the fix-id prefix (up to the first underscore after the id).
-            // e.g. "fix-abc123_2026-08-17T00-00-00-000Z.bak" → "fix-abc123"
-            const match = entry.match(/^(fix-[a-z0-9]+)_/);
-            const id = match?.[1];
-            if (id && !activeIds.has(id)) {
-                staleBackups.push(entry);
-            }
+    // existsSync does not prove readability — a permissions failure must degrade
+    // to "nothing listable" (report skipped) instead of throwing out of execute.
+    let fixEntries = [];
+    try {
+        if (existsSync(fixDir))
+            fixEntries = readdirSync(fixDir);
+    }
+    catch {
+        fixEntries = [];
+    }
+    for (const entry of fixEntries) {
+        if (!entry.endsWith('.bak'))
+            continue;
+        // Extract the fix-id prefix (up to the first underscore after the id).
+        // e.g. "fix-abc123_2026-08-17T00-00-00-000Z.bak" → "fix-abc123"
+        const match = entry.match(/^(fix-[a-z0-9]+)_/);
+        const id = match?.[1];
+        if (id && !activeIds.has(id)) {
+            staleBackups.push(entry);
         }
     }
     // 4. Empty rounds (rounds with 0 records).
@@ -106,10 +114,16 @@ export function inspectPrune(projectRoot, retainDays) {
         .map((r) => r.round);
     // 5. Stray atomic-write temp files left behind by a crashed writer. The
     // unique prefix makes them recognizable and safe to delete — no live writer
-    // ever reads another writer's temp file.
-    const staleTemps = existsSync(iterateDir(projectRoot))
-        ? readdirSync(iterateDir(projectRoot)).filter((f) => isPrunableTemp(f)).sort()
-        : [];
+    // ever reads another writer's temp file. A permissions failure listing the
+    // dir degrades to "none found" (report-only) rather than throwing.
+    let iterateEntries = [];
+    try {
+        iterateEntries = existsSync(iterateDir(projectRoot)) ? readdirSync(iterateDir(projectRoot)) : [];
+    }
+    catch {
+        iterateEntries = [];
+    }
+    const staleTemps = iterateEntries.filter((f) => isPrunableTemp(f)).sort();
     return {
         oldLogEntries,
         hasCheckpoint,

package/dist/tools/quality-gate.js

@@ -9,6 +9,8 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
 import { readQualityGate, writeQualityGate, computeQualityGate, clearQualityGate } from "./quality-store.js";
+/** Valid severity values (kept in sync with QualityGateSnapshot counting). */
+const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low']);
 /** Validate a single finding object; returns true when well-formed. */
 function isValidFinding(raw) {
     if (!raw || typeof raw !== 'object')
@@ -16,6 +18,7 @@ function isValidFinding(raw) {
     const f = raw;
     return (typeof f.dimension === 'string' &&
         typeof f.severity === 'string' &&
+        VALID_SEVERITIES.has(f.severity) &&
         typeof f.file === 'string' &&
         (f.line === undefined || typeof f.line === 'number'));
 }

package/dist/tools/quality-store.js

@@ -200,13 +200,19 @@ export function computeQualityGate(opts) {
     const overallScore = dimensionGates.length > 0
         ? Math.round(dimensionGates.reduce((sum, d) => sum + d.score, 0) / dimensionGates.length)
         : 0;
-    // Determine overall status
+    // Determine overall status. An empty review (no dimensions, no findings, no
+    // validation results) is NOT a failure — there is simply nothing to gate —
+    // so it reports `pending` (not-applicable) instead of a fabricated FAIL.
     const hasCritical = criticalCount > 0;
     const hasHighFail = dimensionGates.some((d) => d.status === 'fail');
     const verificationFails = totalChecks > 0 && failedChecks > 0;
+    const noData = dimensionGates.length === 0 && totalFindings === 0 && totalChecks === 0;
     let overallStatus = 'pass';
     let failReason;
-    if (hasCritical) {
+    if (noData) {
+        overallStatus = 'pending';
+    }
+    else if (hasCritical) {
         overallStatus = 'fail';
         failReason = `${criticalCount} critical findings present`;
     }

package/dist/tools/transcript.js

@@ -31,7 +31,10 @@ function captureRound(builder, round) {
     if (!round || typeof round !== 'object')
         return;
     const r = round;
-    const roundNo = typeof r.round === 'number' ? Math.floor(r.round) : 0;
+    const roundNo = typeof r.round === 'number' && Number.isFinite(r.round) ? Math.floor(r.round) : 0;
+    // NaN round values (`Math.floor(NaN) === NaN`, and `NaN <= 0` is false) would
+    // fall through the guard below; a finite check rejects them outright so a
+    // malformed round can never collapse into round 1 via the builder's coercion.
     if (roundNo <= 0)
         return;
     builder.roundStart(roundNo);
@@ -61,15 +64,17 @@ function normalizeCheckpoint(input) {
     if (!input || typeof input !== 'object')
         return null;
     const c = input;
-    const round = typeof c.round === 'number' ? c.round : 0;
+    // Number.isFinite: a NaN round must not pass `round <= 0` (which is false for
+    // NaN) and later coerce into a phantom round 1 row.
+    const round = typeof c.round === 'number' && Number.isFinite(c.round) ? c.round : 0;
     if (round <= 0)
         return null;
     return {
         mode: c.mode === 'dry-run' || c.mode === 'normal' ? c.mode : 'normal',
         round,
-        maxRounds: typeof c.maxRounds === 'number' ? c.maxRounds : 0,
-        fixedCount: typeof c.fixedCount === 'number' ? c.fixedCount : 0,
-        resumeCount: typeof c.resumeCount === 'number' ? c.resumeCount : 0,
+        maxRounds: typeof c.maxRounds === 'number' && Number.isFinite(c.maxRounds) ? c.maxRounds : 0,
+        fixedCount: typeof c.fixedCount === 'number' && Number.isFinite(c.fixedCount) ? c.fixedCount : 0,
+        resumeCount: typeof c.resumeCount === 'number' && Number.isFinite(c.resumeCount) ? c.resumeCount : 0,
         updatedAt: typeof c.updatedAt === 'string' ? c.updatedAt : new Date().toISOString(),
     };
 }
@@ -85,7 +90,7 @@ function normalizeFix(input) {
     return {
         id,
         timestamp: typeof f.timestamp === 'string' ? f.timestamp : new Date().toISOString(),
-        round: typeof f.round === 'number' ? f.round : 0,
+        round: typeof f.round === 'number' && Number.isFinite(f.round) ? f.round : 0,
         file,
         summary: typeof f.summary === 'string' ? f.summary : '',
         linesAdded: typeof f.linesAdded === 'number' ? f.linesAdded : 0,
@@ -211,11 +216,26 @@ export function registerTranscriptTool(ctx) {
                         manifest = null;
                     }
                 }
-                const builder = manifest
-                    ? rehydrateBuilder(manifest, approval)
-                    : new ReviewTranscriptBuilder({ project: projectRoot, mode: 'normal', approval });
+                // Rehydrating a parsed-but-malformed manifest (e.g. `rounds: [null]`
+                // or a non-object) must never crash the nudge — degrade to a fresh
+                // builder so the steering text still lands.
+                let builder;
+                if (manifest) {
+                    try {
+                        builder = rehydrateBuilder(manifest, approval);
+                    }
+                    catch {
+                        builder = new ReviewTranscriptBuilder({ project: projectRoot, mode: 'normal', approval });
+                    }
+                }
+                else {
+                    builder = new ReviewTranscriptBuilder({ project: projectRoot, mode: 'normal', approval });
+                }
                 builder.setNudge(typeof args.text === 'string' && args.text.trim() ? args.text : null);
-                await persist(file, builder.serialize());
+                const persisted = await persistChecked(file, builder.serialize());
+                if (!persisted.ok) {
+                    return { operation: 'nudge', updated: false, error: persisted.error };
+                }
                 return {
                     operation: 'nudge',
                     updated: true,
@@ -276,7 +296,10 @@ export function registerTranscriptTool(ctx) {
             const last = convergence[convergence.length - 1];
             if (convergence.length > 0 && last === 0)
                 builder.finish();
-            await persist(file, builder.serialize());
+            const persisted = await persistChecked(file, builder.serialize());
+            if (!persisted.ok) {
+                return { operation: 'capture', found: true, updated: false, error: persisted.error };
+            }
             const live = await readLive(projectRoot);
             return {
                 operation: 'capture',
@@ -331,6 +354,18 @@ async function persist(file, manifest) {
     await mkdir(dirname(file), { recursive: true });
     await writeTextAtomicAsync(file, JSON.stringify(manifest, null, 2));
 }
+/** persist wrapped with a structured error channel so disk failures surface
+ *  as a structured tool result instead of rejecting the whole execute (matches
+ *  every other write path in this codebase). */
+async function persistChecked(file, manifest) {
+    try {
+        await persist(file, manifest);
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: `failed to persist transcript: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
 /**
  * Mark one applied fix as rolled back in the PERSISTED transcript, so the
  * client observatory (F4 fix/rollback tab) reflects the reversal instead of

package/dist/transcript.js

@@ -35,6 +35,10 @@ const MAX_TIMELINE = 500;
 /** Max applied-fix records kept (newest wins; bounded so a long run cannot
  *  grow the manifest payload without limit). */
 const MAX_FIXES = 200;
+/** Max round number accepted by the builder. A model-authored/manifest-backed
+ *  round value is attacker-influenced JSON: `roundStart(1e9)` / `snapshotConvergence`
+ *  would otherwise preallocate arrays of that size and OOM the host. */
+const MAX_ROUNDS = 1000;
 /** Thresholds applied when reducing a string list under a cap. */
 function clampStringList(source, cap) {
     const out = [];
@@ -162,9 +166,13 @@ export class ReviewTranscriptBuilder {
     /** Open a review round, capturing the current round index. */
     roundStart(round, maxRounds) {
         const r = typeof round === 'number' && Number.isFinite(round) ? Math.floor(round) : 1;
-        this.round = r > 0 ? r : 1;
+        // Clamp to MAX_ROUNDS: `this.rounds.length < this.round` below preallocates
+        // an array of size `round` — an unbounded model-controlled value (e.g. 1e9)
+        // would OOM the host. Values above the cap are folded into the cap so the
+        // real rounds are never silently dropped.
+        this.round = Math.min(r > 0 ? r : 1, MAX_ROUNDS);
         if (typeof maxRounds === 'number' && Number.isFinite(maxRounds) && maxRounds >= 0) {
-            this.maxRounds = Math.floor(maxRounds);
+            this.maxRounds = Math.min(Math.floor(maxRounds), MAX_ROUNDS);
         }
         while (this.rounds.length < this.round) {
             this.rounds.push({ round: this.rounds.length + 1, threads: [] });
@@ -248,7 +256,10 @@ export class ReviewTranscriptBuilder {
     // ─── Convergence (F2) ───────────────────────────────────────────────────
     /** Record a round's new-finding count for the convergence series. */
     snapshotConvergence(round, newCount) {
-        const r = typeof round === 'number' && Number.isFinite(round) ? Math.floor(round) : 1;
+        const rawR = typeof round === 'number' && Number.isFinite(round) ? Math.floor(round) : 1;
+        // Clamp (mirrors roundStart): the loop below preallocates `r` slots, so an
+        // unbounded model-controlled round number would OOM the host.
+        const r = Math.min(rawR > 0 ? rawR : 1, MAX_ROUNDS);
         const n = typeof newCount === 'number' && Number.isFinite(newCount) ? newCount : 0;
         while (this.convergence.length < r)
             this.convergence.push(-1);
@@ -267,7 +278,9 @@ export class ReviewTranscriptBuilder {
         this.fixes.push({
             id,
             timestamp: typeof record.timestamp === 'string' ? record.timestamp : isoNow(),
-            round: typeof record.round === 'number' ? record.round : this.round,
+            round: typeof record.round === 'number' && Number.isFinite(record.round)
+                ? Math.floor(record.round)
+                : this.round,
             file,
             summary: typeof record.summary === 'string' ? record.summary : '',
             linesAdded: typeof record.linesAdded === 'number' ? Math.floor(record.linesAdded) : 0,
@@ -313,7 +326,9 @@ export class ReviewTranscriptBuilder {
         const type = typeof entry.type === 'string' ? entry.type : 'decision';
         this.timeline.push({
             timestamp: typeof entry.timestamp === 'string' ? entry.timestamp : isoNow(),
-            round: typeof entry.round === 'number' ? entry.round : this.round,
+            round: typeof entry.round === 'number' && Number.isFinite(entry.round)
+                ? Math.floor(entry.round)
+                : this.round,
             type,
             data: entry.data && typeof entry.data === 'object'
                 ? entry.data

package/lib/client.js

@@ -1283,7 +1283,10 @@ function buildRuntimeStatusGuide() {
     ...RUNTIME_ARTIFACTS.map((a) => `- ${a.key}\uFF08${a.label}\uFF09\uFF1A${a.hint}`),
     "",
     "\u67E5\u770B\u72B6\u6001\uFF1A\u8BA9\u6A21\u578B\u8C03\u7528 iterate_status\uFF08\u6C47\u603B\uFF09\u6216 iterate_history\uFF08\u660E\u7EC6\uFF09\u3002",
-    "\u6E05\u7406\u72B6\u6001\uFF1A\u8BA9\u6A21\u578B\u8C03\u7528 iterate_prune\uFF08\u9ED8\u8BA4 dry-run\uFF0C\u53EA\u62A5\u544A\u4E0D\u5220\u9664\uFF0C\u663E\u5F0F dryRun:false \u624D\u771F\u6B63\u6E05\u7406\uFF09\u3002"
+    "\u6E05\u7406\u72B6\u6001\uFF1A\u8BA9\u6A21\u578B\u8C03\u7528 iterate_prune\uFF08\u9ED8\u8BA4 dry-run\uFF0C\u53EA\u62A5\u544A\u4E0D\u5220\u9664\uFF0C\u663E\u5F0F dryRun:false \u624D\u771F\u6B63\u6E05\u7406\uFF09\u3002",
+    '\u91CD\u7F6E\u72B6\u6001\uFF1A\u4E2D\u65AD\u540E\u91CD\u65B0\u5F00\u59CB\u524D\uFF0C\u53EF\u5206\u522B\u8BA9\u6A21\u578B\u8C03\u7528 iterate_checkpoint(operation:"clear")\u3001',
+    '  iterate_quality_gate(operation:"clear")\u3001iterate_defense_events(operation:"clear")',
+    "  \u6E05\u9664\u9648\u65E7\u65AD\u70B9\u3001\u8D28\u91CF\u95E8\u7981\u8BC1\u4E66\u4E0E\u9632\u5FA1\u4E8B\u4EF6\u6D41\u3002"
   ];
   return lines.join("\n");
 }
@@ -3095,6 +3098,11 @@ ${JSON.stringify({
       mode: String(cp.mode || "normal"),
       maxRounds: typeof cp.maxRounds === "number" ? cp.maxRounds : null
     }, null, 2)}
+\`\`\``;
+    const clearText = `\u8BF7\u8C03\u7528 \`iterate_checkpoint\` \u6E05\u9664\u5F53\u524D\u65AD\u70B9\uFF1A
+
+\`\`\`json
+${JSON.stringify({ operation: "clear" }, null, 2)}
 \`\`\``;
     const item = (label, value) => React.createElement("span", { className: "iterate-obs-chip" }, `${label} ${String(value ?? "?")}`);
     return React.createElement(
@@ -3118,13 +3126,24 @@ ${JSON.stringify({
           item("fixed", cp.fixedCount),
           item("resume", cp.resumeCount)
         ),
-        React.createElement("button", {
-          className: "iterate-btn",
-          "data-primary": "",
-          "data-copied": copiedKey === "cp-resume" ? "" : void 0,
-          onClick: () => copyInstruction("cp-resume", resumeText),
-          title: "\u590D\u5236 iterate_checkpoint resume \u6307\u4EE4\u6587\u672C\uFF08\u52A0\u8F7D\u65AD\u70B9\u5E76\u8BA1\u6570\u4E00\u6B21\u6062\u590D\uFF09"
-        }, copiedKey === "cp-resume" ? "\u5DF2\u590D\u5236" : "\u590D\u5236\u6062\u590D\u6307\u4EE4")
+        React.createElement(
+          "div",
+          { className: "iterate-obs-bar", style: { marginBottom: 4 } },
+          React.createElement("button", {
+            className: "iterate-btn",
+            "data-primary": "",
+            "data-copied": copiedKey === "cp-resume" ? "" : void 0,
+            onClick: () => copyInstruction("cp-resume", resumeText),
+            title: "\u590D\u5236 iterate_checkpoint resume \u6307\u4EE4\u6587\u672C\uFF08\u52A0\u8F7D\u65AD\u70B9\u5E76\u8BA1\u6570\u4E00\u6B21\u6062\u590D\uFF09"
+          }, copiedKey === "cp-resume" ? "\u5DF2\u590D\u5236" : "\u590D\u5236\u6062\u590D\u6307\u4EE4"),
+          React.createElement("button", {
+            className: "iterate-btn",
+            "data-danger": "",
+            "data-copied": copiedKey === "cp-clear" ? "" : void 0,
+            onClick: () => copyInstruction("cp-clear", clearText),
+            title: "\u590D\u5236 iterate_checkpoint clear \u6307\u4EE4\u6587\u672C\uFF08\u6E05\u9664\u5F53\u524D\u65AD\u70B9\uFF0C\u4F9B\u91CD\u65B0\u5F00\u59CB\uFF09"
+          }, copiedKey === "cp-clear" ? "\u5DF2\u590D\u5236" : "\u6E05\u9664\u65AD\u70B9")
+        )
       )
     );
   };
@@ -3293,6 +3312,11 @@ ${JSON.stringify({ operation: "nudge", text: null }, null, 2)}
   };
   const renderQualityGate = () => {
     const gateInstruction = "\u8BF7\u8C03\u7528 `iterate_quality_gate` \u67E5\u8BE2\u5F53\u524D\u8D28\u91CF\u95E8\u7981\u72B6\u6001";
+    const gateClearInstruction = `\u8BF7\u8C03\u7528 \`iterate_quality_gate\` \u6E05\u9664\u5F53\u524D\u8D28\u91CF\u95E8\u7981\u8BC1\u4E66\uFF1A
+
+\`\`\`json
+${JSON.stringify({ operation: "clear" }, null, 2)}
+\`\`\``;
     const gate = qualityGate;
     const dims = gate && gate.dimensions ? gate.dimensions : [];
     const hasGate = gate !== null && Boolean(gate.overallStatus || gate.overallScore != null || dims.length > 0);
@@ -3309,7 +3333,14 @@ ${JSON.stringify({ operation: "nudge", text: null }, null, 2)}
         "data-copied": copiedKey === "qgate" ? "" : void 0,
         onClick: () => copyInstruction("qgate", gateInstruction),
         title: "\u590D\u5236 iterate_quality_gate \u67E5\u8BE2\u6307\u4EE4"
-      }, copiedKey === "qgate" ? "\u5DF2\u590D\u5236" : "\u67E5\u8BE2\u95E8\u7981")
+      }, copiedKey === "qgate" ? "\u5DF2\u590D\u5236" : "\u67E5\u8BE2\u95E8\u7981"),
+      React.createElement("button", {
+        className: "iterate-btn",
+        "data-danger": "",
+        "data-copied": copiedKey === "qgate-clear" ? "" : void 0,
+        onClick: () => copyInstruction("qgate-clear", gateClearInstruction),
+        title: "\u590D\u5236 iterate_quality_gate clear \u6307\u4EE4\u6587\u672C\uFF08\u91CD\u7F6E\u9648\u65E7\u7684 FAIL \u8BC1\u4E66\uFF09"
+      }, copiedKey === "qgate-clear" ? "\u5DF2\u590D\u5236" : "\u6E05\u9664\u95E8\u7981")
     );
     if (!hasGate) {
       return React.createElement(
@@ -3524,7 +3555,18 @@ ${JSON.stringify({ operation: "list", type: defenseFilter || void 0 }, null, 2)}
         "data-copied": copiedKey === "defense-counts" ? "" : void 0,
         onClick: () => copyInstruction("defense-counts", "\u8BF7\u8C03\u7528 `iterate_defense_events` \u67E5\u8BE2\u4E8B\u4EF6\u7EDF\u8BA1"),
         title: "\u590D\u5236\u7EDF\u8BA1\u6307\u4EE4"
-      }, copiedKey === "defense-counts" ? "\u5DF2\u590D\u5236" : "\u7EDF\u8BA1")
+      }, copiedKey === "defense-counts" ? "\u5DF2\u590D\u5236" : "\u7EDF\u8BA1"),
+      React.createElement("button", {
+        className: "iterate-btn",
+        "data-danger": "",
+        "data-copied": copiedKey === "defense-clear" ? "" : void 0,
+        onClick: () => copyInstruction("defense-clear", `\u8BF7\u8C03\u7528 \`iterate_defense_events\` \u6E05\u9664\u9632\u5FA1\u4E8B\u4EF6\u6D41\uFF1A
+
+\`\`\`json
+${JSON.stringify({ operation: "clear" }, null, 2)}
+\`\`\``),
+        title: "\u590D\u5236 iterate_defense_events clear \u6307\u4EE4\u6587\u672C\uFF08\u91CD\u7F6E\u9648\u65E7\u4E8B\u4EF6\u6D41\uFF09"
+      }, copiedKey === "defense-clear" ? "\u5DF2\u590D\u5236" : "\u6E05\u9664\u4E8B\u4EF6")
     );
     if (allEvents.length === 0 && totalCount === 0) {
       return React.createElement(

package/lib/parse.js

@@ -1816,6 +1816,9 @@ export function buildRuntimeStatusGuide() {
     '',
     '查看状态：让模型调用 iterate_status（汇总）或 iterate_history（明细）。',
     '清理状态：让模型调用 iterate_prune（默认 dry-run，只报告不删除，显式 dryRun:false 才真正清理）。',
+    '重置状态：中断后重新开始前，可分别让模型调用 iterate_checkpoint(operation:"clear")、',
+    '  iterate_quality_gate(operation:"clear")、iterate_defense_events(operation:"clear")',
+    '  清除陈旧断点、质量门禁证书与防御事件流。',
   ]
   return lines.join('\n')
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "3.5.2",
+  "version": "3.5.3",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness with quality command center and experience bank (v3.3). Features: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus dry-run pure-review mode, quality gate compute/persist, writable experience bank, defense events stream (record + bilingual labels), and native command buttons — with a live quality command center (F8/F9/F10 render real session data), §8 assign-fix instruction, and task_mode indicator wired end to end.",
   "type": "module",
   "license": "MIT",

package/src/client/index.ts

@@ -2172,6 +2172,11 @@ function ObservatoryPanel(props: SlotProps) {
       mode: String(cp.mode || 'normal'),
       maxRounds: typeof cp.maxRounds === 'number' ? cp.maxRounds : null,
     }, null, 2)}\n\`\`\``
+    // Clearing a stale checkpoint after an interrupted run — iterate_checkpoint
+    // exposes `clear`, but before this button it was only reachable by typing
+    // the command manually (an interrupted run otherwise shows a permanent
+    // "可恢复" chip with no companion reset action).
+    const clearText = `请调用 \`iterate_checkpoint\` 清除当前断点：\n\n\`\`\`json\n${JSON.stringify({ operation: 'clear' }, null, 2)}\n\`\`\``
     const item = (label: string, value: unknown) =>
       React.createElement('span', { className: 'iterate-obs-chip' }, `${label} ${String(value ?? '?')}`)
     return React.createElement('div', { className: 'iterate-obs-block' },
@@ -2187,11 +2192,18 @@ function ObservatoryPanel(props: SlotProps) {
           item('fixed', cp.fixedCount),
           item('resume', cp.resumeCount),
         ),
-        React.createElement('button', {
-          className: 'iterate-btn', 'data-primary': '', 'data-copied': copiedKey === 'cp-resume' ? '' : undefined,
-          onClick: () => copyInstruction('cp-resume', resumeText),
-          title: '复制 iterate_checkpoint resume 指令文本（加载断点并计数一次恢复）',
-        }, copiedKey === 'cp-resume' ? '已复制' : '复制恢复指令'),
+        React.createElement('div', { className: 'iterate-obs-bar', style: { marginBottom: 4 } },
+          React.createElement('button', {
+            className: 'iterate-btn', 'data-primary': '', 'data-copied': copiedKey === 'cp-resume' ? '' : undefined,
+            onClick: () => copyInstruction('cp-resume', resumeText),
+            title: '复制 iterate_checkpoint resume 指令文本（加载断点并计数一次恢复）',
+          }, copiedKey === 'cp-resume' ? '已复制' : '复制恢复指令'),
+          React.createElement('button', {
+            className: 'iterate-btn', 'data-danger': '', 'data-copied': copiedKey === 'cp-clear' ? '' : undefined,
+            onClick: () => copyInstruction('cp-clear', clearText),
+            title: '复制 iterate_checkpoint clear 指令文本（清除当前断点，供重新开始）',
+          }, copiedKey === 'cp-clear' ? '已复制' : '清除断点'),
+        ),
       ),
     )
   }
@@ -2338,6 +2350,9 @@ function ObservatoryPanel(props: SlotProps) {
   // falls back to copy-able query instructions when no snapshot exists yet.
   const renderQualityGate = () => {
     const gateInstruction = '请调用 `iterate_quality_gate` 查询当前质量门禁状态'
+    // Reset a stale FAIL certificate before a fresh iteration — the tool's
+    // `clear` operation existed since v3.5.1 but had no client entry point.
+    const gateClearInstruction = `请调用 \`iterate_quality_gate\` 清除当前质量门禁证书：\n\n\`\`\`json\n${JSON.stringify({ operation: 'clear' }, null, 2)}\n\`\`\``
     const gate = qualityGate
     const dims = gate && gate.dimensions ? gate.dimensions : []
     const hasGate = gate !== null && Boolean(gate.overallStatus || gate.overallScore != null || dims.length > 0)
@@ -2352,6 +2367,11 @@ function ObservatoryPanel(props: SlotProps) {
         onClick: () => copyInstruction('qgate', gateInstruction),
         title: '复制 iterate_quality_gate 查询指令',
       }, copiedKey === 'qgate' ? '已复制' : '查询门禁'),
+      React.createElement('button', {
+        className: 'iterate-btn', 'data-danger': '', 'data-copied': copiedKey === 'qgate-clear' ? '' : undefined,
+        onClick: () => copyInstruction('qgate-clear', gateClearInstruction),
+        title: '复制 iterate_quality_gate clear 指令文本（重置陈旧的 FAIL 证书）',
+      }, copiedKey === 'qgate-clear' ? '已复制' : '清除门禁'),
     )
 
     if (!hasGate) {
@@ -2538,6 +2558,11 @@ function ObservatoryPanel(props: SlotProps) {
         onClick: () => copyInstruction('defense-counts', '请调用 `iterate_defense_events` 查询事件统计'),
         title: '复制统计指令',
       }, copiedKey === 'defense-counts' ? '已复制' : '统计'),
+      React.createElement('button', {
+        className: 'iterate-btn', 'data-danger': '', 'data-copied': copiedKey === 'defense-clear' ? '' : undefined,
+        onClick: () => copyInstruction('defense-clear', `请调用 \`iterate_defense_events\` 清除防御事件流：\n\n\`\`\`json\n${JSON.stringify({ operation: 'clear' }, null, 2)}\n\`\`\``),
+        title: '复制 iterate_defense_events clear 指令文本（重置陈旧事件流）',
+      }, copiedKey === 'defense-clear' ? '已复制' : '清除事件'),
     )
 
     if (allEvents.length === 0 && totalCount === 0) {

package/src/tools/checkpoint.ts

@@ -24,16 +24,41 @@ import type { DefenseEventType, IterationCheckpoint, IterationStatus, QualityGat
 
 // ─── 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: string): IterationCheckpoint | null {
   const file = checkpointPath(projectRoot)
   if (!existsSync(file)) return null
   try {
-    const parsed = JSON.parse(readFileSync(file, 'utf-8')) as IterationCheckpoint
+    const parsed = JSON.parse(readFileSync(file, 'utf-8')) as Partial<IterationCheckpoint>
     if (!parsed || typeof parsed !== 'object') return null
     if (parsed.mode !== 'dry-run' && parsed.mode !== 'normal') return null
-    if (typeof parsed.round !== 'number') return null
-    return parsed
+    // 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
+    const num = (v: unknown, fallback: number): number =>
+      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 as IterationCheckpoint['findings']) : [],
+      startedAt: typeof parsed.startedAt === 'string' ? parsed.startedAt : new Date().toISOString(),
+      updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+    }
   } catch {
     return null
   }
@@ -82,6 +107,17 @@ export function validateCheckpoint(input: {
   ) {
     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
 }
 
@@ -118,8 +154,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.
@@ -258,7 +297,7 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
             fixedCount: args.fixedCount as number,
             architecturalCount: args.architecturalCount as number,
             resumeCount: (typeof args.resumeCount === 'number' ? args.resumeCount : 0),
-            findings: (Array.isArray(args.findings) ? args.findings : []) as unknown as IterationCheckpoint['findings'],
+            findings: (Array.isArray(args.findings) ? args.findings.slice(0, MAX_CHECKPOINT_FINDINGS) : []) as unknown as IterationCheckpoint['findings'],
             startedAt: readCheckpoint(projectRoot)?.startedAt ?? new Date().toISOString(),
             updatedAt: new Date().toISOString(),
           }

package/src/tools/config.ts

@@ -1,7 +1,8 @@
 import { join } from 'node:path'
+import { existsSync } from 'node:fs'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
-import { loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from '../config-loader.ts'
+import { defaultConfig, loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from '../config-loader.ts'
 import {
   applyConfigUpdates,
   readRawConfig,
@@ -106,7 +107,15 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
           }
           let base: Record<string, unknown>
           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() as unknown as Record<string, unknown>)
           } catch (err) {
             return { operation: 'write', ok: false, found: false, error: `failed to read config: ${String(err)}` }
           }