iterate-plugin 3.5.1 → 3.5.3

package/dist/tools/fix.js

@@ -18,7 +18,7 @@
  */
 import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
 import { writeJsonAtomic, writeTextAtomic } from "../atomic-fs.js";
-import { join, sep } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { loadEffectiveConfig, resolveProjectRootForExec } from "../config-loader.js";
 import { runWithJob } from "../jobs.js";
@@ -120,9 +120,22 @@ export function readRegistry(projectRoot) {
         const parsed = JSON.parse(readFileSync(file, 'utf-8'));
         if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.rounds))
             return emptyRegistry();
-        // Defensive: a hand-edited or partially-written registry may contain a
-        // round without a `records` array — normalize instead of crashing readers.
-        parsed.rounds = parsed.rounds.filter((r) => r && typeof r === 'object' && Array.isArray(r.records));
+        // Defensive normalization: a hand-edited or partially-written registry may
+        // contain a round without a `records` array, or records that are missing
+        // their id / finding object — all of which would make readers
+        // (findFixRecord / recordsForFile / iterate_diff) throw or sum NaN.
+        parsed.rounds = parsed.rounds
+            .filter((r) => r && typeof r === 'object' && Array.isArray(r.records))
+            .map((r) => ({
+            ...r,
+            round: typeof r.round === 'number' && Number.isFinite(r.round) ? Math.floor(r.round) : 0,
+            records: r.records.filter((rec) => !!rec &&
+                typeof rec === 'object' &&
+                typeof rec.id === 'string' &&
+                !!rec.finding &&
+                typeof rec.finding === 'object'),
+        }))
+            .filter((r) => typeof r.round === 'number' && Number.isFinite(r.round));
         return parsed;
     }
     catch {
@@ -198,15 +211,26 @@ export function resolveProjectFile(projectRoot, file) {
         return { ok: false, reason: 'file resolves outside the project root' };
     }
     // Symlink containment: the lexical prefix check above does not resolve
-    // symlinks. If the target exists, verify its REAL path stays inside the REAL
-    // project root so a symlinked directory/file inside the repo can never route
-    // a fix (write/rollback/diff) outside the project.
-    if (existsSync(resolved)) {
+    // symlinks. Verify the REAL path of the target (when it exists) AND of its
+    // nearest existing ancestor directory (when it does not — e.g. a fix that
+    // creates a new file) stays inside the REAL project root, so a symlinked
+    // directory inside the repo can never route a fix (write/rollback/diff)
+    // outside the project. The probe stops at the project root itself: the root
+    // is harness-provided (not model-controlled), and a path with no existing
+    // entry inside the repo cannot hide a symlink.
+    let probe = resolved;
+    while (!existsSync(probe) && probe !== projectRoot) {
+        const parent = dirname(probe);
+        if (parent === probe)
+            break;
+        probe = parent;
+    }
+    if (existsSync(probe)) {
         let rootReal;
         let real;
         try {
             rootReal = realpathSync(projectRoot);
-            real = realpathSync(resolved);
+            real = realpathSync(probe);
         }
         catch {
             return { ok: false, reason: 'failed to resolve real path for containment check' };
@@ -485,9 +509,9 @@ export function registerFixTool(ctx) {
                     // Registry write failed → the file was already modified but no record
                     // exists, so a later rollback/diff could never see it and a retry would
                     // back up the already-fixed content as "original". Restore the file
-                    // from the backup to leave the tree exactly as it was.
+                    // from the backup atomically to leave the tree exactly as it was.
                     try {
-                        copyFileSync(backupPath, target.resolved);
+                        writeTextAtomic(target.resolved, readFileSync(backupPath, 'utf-8'));
                     }
                     catch (restoreErr) {
                         return {
@@ -600,20 +624,27 @@ export function registerDiffTool(ctx) {
                 for (const r of round.records) {
                     if (!r.success)
                         continue;
-                    const existing = files.find((f) => f.file === r.finding.file);
+                    const file = typeof r.finding.file === 'string' ? r.finding.file : '';
+                    if (!file)
+                        continue;
+                    // Coerce defensively: a hand-edited registry record missing the
+                    // numeric fields must not produce NaN in the accumulated summary.
+                    const added = Number(r.linesAdded) || 0;
+                    const removed = Number(r.linesRemoved) || 0;
+                    const existing = files.find((f) => f.file === file);
                     if (existing) {
-                        existing.linesAdded += r.linesAdded;
-                        existing.linesRemoved += r.linesRemoved;
+                        existing.linesAdded += added;
+                        existing.linesRemoved += removed;
                         // Recompute the summary from the summed counts so a multi-fix
                         // file's text does not contradict its accumulated numbers.
                         existing.diffSummary = `+${existing.linesAdded}/-${existing.linesRemoved} lines`;
                     }
                     else {
                         files.push({
-                            file: r.finding.file,
-                            diffSummary: r.diffSummary,
-                            linesAdded: r.linesAdded,
-                            linesRemoved: r.linesRemoved,
+                            file,
+                            diffSummary: typeof r.diffSummary === 'string' ? r.diffSummary : `+${added}/-${removed} lines`,
+                            linesAdded: added,
+                            linesRemoved: removed,
                         });
                     }
                 }
@@ -691,7 +722,9 @@ export function registerRollbackTool(ctx) {
             if (!target.ok)
                 return { ok: false, error: target.reason };
             try {
-                copyFileSync(record.backupPath, target.resolved);
+                // Atomic restore: never leave a truncated source file if we crash
+                // mid-restore (matches the writeTextAtomic guarantee used by apply).
+                writeTextAtomic(target.resolved, readFileSync(record.backupPath, 'utf-8'));
             }
             catch (err) {
                 return { ok: false, error: `failed to restore backup: ${String(err)}` };

package/dist/tools/history.js

@@ -46,8 +46,10 @@ export function filterDecisionEntries(entries, opts) {
 export function summarizeFixRegistry(registry) {
     const rounds = (registry.rounds ?? []).map((r) => ({
         round: r.round,
-        fixedCount: r.fixedCount,
-        failedCount: r.failedCount,
+        // Coerce defensively so a hand-edited registry round missing either count
+        // can never propagate NaN into the integer output fields.
+        fixedCount: Number(r.fixedCount) || 0,
+        failedCount: Number(r.failedCount) || 0,
     }));
     return {
         totalFixed: rounds.reduce((s, r) => s + r.fixedCount, 0),
@@ -74,7 +76,7 @@ export function registerHistoryTool(ctx) {
             type: {
                 type: 'string',
                 description: 'Optional entry-type filter: round_start, review_result, atomic_fix, architectural_fix, ' +
-                    'revert, validation, decision, report.',
+                    'revert, round_failed, validation, decision, report, resume.',
             },
             since: {
                 type: 'string',

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.1",
+  "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",
@@ -36,7 +36,8 @@
         "0.1.3-alpha.1": "compatible",
         "0.1.5-alpha.1": "compatible",
         "0.1.5-alpha.2": "compatible",
-        "0.1.5-rc.1": "compatible"
+        "0.1.5-rc.1": "compatible",
+        "0.1.5-rc.2": "compatible"
       }
     },
     "client": {
@@ -74,13 +75,13 @@
   },
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-util-values": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-util-values": "0.1.5-rc.2",
     "js-yaml": "4.3.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-jobs": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-jobs": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.5-rc.2",
     "@types/js-yaml": "4.0.9",
     "@types/node": "22.15.0",
     "@types/react": "19.2.2",

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) {