iterate-plugin 3.5.0 → 3.5.2

package/README.md

@@ -260,8 +260,8 @@ validation:
 - `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), or `add` a new verified fix: re-adding the same pattern+dimension bumps its hit count instead of duplicating it. Persists to `.iterate/experience.json`
-- `iterate_quality_gate` — **v3.2** read the quality certificate (`read`), or recompute + persist a fresh one (`compute`) from findings, validation results, `findingsByRound`, and `fixedByDimension`. Real per-dimension convergence rates
+- `iterate_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)
 
 ---

package/README.zh-CN.md

@@ -259,8 +259,8 @@ validation:
 - `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 累加命中次数而非重复写入。持久化到 `.iterate/experience.json`
-- `iterate_quality_gate` — **v3.2** 读取质量凭证（`read`），或基于 findings、验证结果、`findingsByRound` 与 `fixedByDimension` 重新计算并持久化一份新凭证（`compute`）。真实的逐维度收敛率
+- `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）
 
 ---

package/dist/live.js

@@ -69,6 +69,11 @@ export function classifyTool(name, args, projectRoot) {
         iterate_status: 'info',
         iterate_config: 'info',
         iterate_context: 'info',
+        // v3.0 quality command-center tools — surface their activity in the live
+        // feed too (previously these three never produced a live entry).
+        iterate_experience: 'info',
+        iterate_quality_gate: 'info',
+        iterate_defense_events: 'info',
     };
     const type = records[name];
     if (!type)

package/dist/skill-prompt.js

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

package/dist/tools/checkpoint.js

@@ -302,6 +302,27 @@ export function registerStatusTool(ctx) {
                     `Checkpoint: ${value.hasCheckpoint ? 'yes' : 'no'}${value.interrupted ? ' (interrupted — resumable)' : ''}${value.resumeCount ? ` · resumed ${value.resumeCount}x` : ''}`,
                     value.lastUpdated ? `Last updated: ${value.lastUpdated}` : '',
                 ];
+                // v3.0 quality command-center summaries (surfaced here so a single
+                // status read reports the whole run state in text too).
+                const gate = value.qualityGate;
+                if (gate) {
+                    lines.push(`Quality gate: ${gate.overallStatus.toUpperCase()} · score ${gate.overallScore} · ` +
+                        `verification ${gate.passedChecks}/${gate.totalChecks} passed` +
+                        (gate.failReason ? ` · ${gate.failReason}` : ''));
+                }
+                const exp = value.experienceBank;
+                if (exp) {
+                    lines.push(`Experience bank: ${exp.totalEntries ?? 0} entries · ${exp.totalHits ?? 0} cumulative hits`);
+                }
+                const def = value.defenseEvents;
+                if (def) {
+                    const counts = def.counts ?? {};
+                    const total = Object.values(counts).reduce((s, n) => s + (n || 0), 0);
+                    lines.push(`Defense events: ${def.totalEvents ?? total} recorded` +
+                        (total > 0
+                            ? ` (precondition_failed:${counts.precondition_failed ?? 0}, rollback:${counts.rollback ?? 0}, invariant_violated:${counts.invariant_violated ?? 0}, assumption_falsified:${counts.assumption_falsified ?? 0})`
+                            : ''));
+                }
                 return [{ type: 'text', text: lines.filter(Boolean).join('\n') }];
             },
         },

package/dist/tools/context.js

@@ -1,10 +1,40 @@
-import { readFileSync, existsSync, statSync } from 'node:fs';
-import { join, dirname, resolve } from 'node:path';
+import { readFileSync, existsSync, realpathSync, statSync } from 'node:fs';
+import { join, dirname, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
 /** How many ancestor directories we walk up looking for a SKILL.md. */
 const MAX_SKILL_DIR_LOOKUP_DEPTH = 12;
+/**
+ * Whether a model-supplied `skillDir` may be used as a SKILL.md search root.
+ *
+ * `skillDir` is model-controlled, so it is only honored when it is an existing
+ * directory whose REAL path (symlinks resolved) sits inside one of the allowed
+ * roots (the project root or the plugin directory). Anything else — a path
+ * outside the allowed roots, a nonexistent dir, or a symlink pointing outside
+ * (e.g. at `/etc`) — is rejected so arbitrary file contents can never be
+ * injected wholesale into the review context.
+ */
+export function isAllowedSkillDir(skillDir, allowedRoots) {
+    if (typeof skillDir !== 'string' || skillDir.trim().length === 0)
+        return false;
+    try {
+        const dir = resolve(skillDir);
+        if (!existsSync(dir) || !statSync(dir).isDirectory())
+            return false;
+        return allowedRoots.some((root) => {
+            if (typeof root !== 'string' || root.length === 0)
+                return false;
+            const rootReal = realpathSync(root);
+            const rootPrefix = rootReal.endsWith(sep) ? rootReal : rootReal + sep;
+            const real = realpathSync(dir);
+            return real === rootReal || real.startsWith(rootPrefix);
+        });
+    }
+    catch {
+        return false;
+    }
+}
 /** Maximum number of image attachments relayed into the context in one call. */
 const MAX_ATTACHMENTS = 8;
 /** Maximum intrinsic width/height (px) accepted for an attached image. */
@@ -271,9 +301,13 @@ export function registerContextTool(ctx) {
                 // the auto-detected root / project root.
                 if (typeof args.skillDir === 'string' && args.skillDir.trim()) {
                     try {
-                        const dir = resolve(args.skillDir);
-                        if (existsSync(dir) && statSync(dir).isDirectory())
-                            candidates.push(dir);
+                        // Model-controlled path: only honor it when its REAL path stays
+                        // inside the project root or the plugin directory — never let a
+                        // 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));
+                        }
                     }
                     catch {
                         // unreadable/invalid skillDir — skip it

package/dist/tools/decision-log.js

@@ -94,7 +94,14 @@ export function readDecisionLogDetailed(projectRoot) {
         if (trimmed.length === 0)
             continue;
         try {
-            entries.push(JSON.parse(trimmed));
+            const parsed = JSON.parse(trimmed);
+            if (parsed === null || typeof parsed !== 'object' ||
+                typeof parsed.timestamp !== 'string' ||
+                typeof parsed.type !== 'string') {
+                invalidLines += 1;
+                continue;
+            }
+            entries.push(parsed);
         }
         catch {
             invalidLines += 1;

package/dist/tools/experience-bank.js

@@ -7,7 +7,7 @@
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
-import { readExperienceBank, writeExperienceBank, searchExperienceEntries, upsertExperience } from "./experience-store.js";
+import { readExperienceBank, writeExperienceBank, searchExperienceEntries, upsertExperience, removeExperience } from "./experience-store.js";
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 100;
 /** Clamp a caller-supplied limit to a sane range. */
@@ -75,12 +75,13 @@ export function registerExperienceBankTool(ctx) {
             'List/search/get return matching entries with hit counts, verified fixes, and related context. ' +
             '"add" upserts an experience entry into .iterate/experience.json — a repeat of the same ' +
             'pattern+dimension increments its hit count instead of duplicating it. ' +
+            '"remove" deletes an entry by id (useful for pruning stale or incorrect experiences). ' +
             'Use it to remember fixes that worked so future rounds apply them first.',
         parameters: {
             operation: {
                 type: 'string',
-                description: 'Operation: list (browse all), search (by query), get (by id), add (add a new experience). Default: list.',
-                enum: ['list', 'search', 'get', 'add'],
+                description: 'Operation: list (browse all), search (by query), get (by id), add (add a new experience), remove (delete by id). Default: list.',
+                enum: ['list', 'search', 'get', 'add', 'remove'],
             },
             query: {
                 type: 'string',
@@ -147,6 +148,9 @@ export function registerExperienceBankTool(ctx) {
                                 `Tags: ${entry.tags.join(', ')}`,
                             ].join('\n') }];
                 }
+                if (value.operation === 'remove') {
+                    return [{ type: 'text', text: `Removed experience entry. Bank now holds ${value.count ?? 0} entries (${value.totalHits ?? 0} cumulative hits).` }];
+                }
                 if (value.operation === 'get' && value.entry) {
                     const entry = value.entry;
                     return [{ type: 'text', text: [
@@ -204,6 +208,38 @@ export function registerExperienceBankTool(ctx) {
                     totalHits: next.totalHits,
                 };
             }
+            if (operation === 'remove') {
+                const id = typeof args.id === 'string' && args.id ? args.id : '';
+                if (!id) {
+                    return {
+                        ok: false,
+                        kind: 'experience',
+                        operation: 'remove',
+                        error: 'id is required for remove',
+                    };
+                }
+                const bank = readExperienceBank(projectRoot);
+                const { bank: next, removed } = removeExperience(bank, id);
+                if (!removed) {
+                    return {
+                        ok: false,
+                        kind: 'experience',
+                        operation: 'remove',
+                        error: `Experience not found: ${id}`,
+                    };
+                }
+                const write = writeExperienceBank(projectRoot, next);
+                if (!write.ok) {
+                    return { ok: false, kind: 'experience', operation: 'remove', error: write.error };
+                }
+                return {
+                    ok: true,
+                    kind: 'experience',
+                    operation: 'remove',
+                    count: next.entries.length,
+                    totalHits: next.totalHits,
+                };
+            }
             const bank = readExperienceBank(projectRoot);
             if (operation === 'get' && typeof args.id === 'string') {
                 const entry = bank.entries.find((e) => e.id === args.id);

package/dist/tools/experience-store.js

@@ -140,3 +140,27 @@ export function upsertExperience(bank, entry) {
         entryId: id,
     };
 }
+/**
+ * Remove an experience entry by id.
+ * Returns the resulting bank plus whether an entry was actually removed. An
+ * unknown id is a no-op (the caller decides how to surface it). Never mutates
+ * the input bank.
+ */
+export function removeExperience(bank, id) {
+    const target = typeof id === 'string' && id ? id : '';
+    if (!target)
+        return { bank, removed: false };
+    const entries = bank.entries.filter((e) => e.id !== target);
+    if (entries.length === bank.entries.length)
+        return { bank, removed: false };
+    const lastUpdated = new Date().toISOString();
+    return {
+        bank: {
+            ...bank,
+            entries,
+            lastUpdated,
+            totalHits: bank.totalHits ?? 0,
+        },
+        removed: true,
+    };
+}

package/dist/tools/fix.js

@@ -18,13 +18,14 @@
  */
 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";
 import { countTouchedMethods } from "../method-scope.js";
 import { fixBackupPath, fixRegistryPath, fixesDir } from "../paths.js";
 import { appendDecisionEntry } from "./decision-log.js";
+import { markFixRolledBackInTranscript } from "./transcript.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
 /** Upper bound for a single fix `content` payload (characters). */
 export const MAX_FIX_CONTENT_CHARS = 1_000_000;
@@ -197,15 +198,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' };
@@ -484,9 +496,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 {
@@ -690,7 +702,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)}` };
@@ -708,6 +722,11 @@ export function registerRollbackTool(ctx) {
                 type: 'revert',
                 data: { id, file: record.finding.file, revertedDiff: record.diffSummary },
             });
+            // Mirror the reversal into the persisted observatory transcript (F4) so
+            // the client no longer shows a rolled-back fix as "成功". Best-effort:
+            // a missing/corrupt transcript is left untouched and never breaks the
+            // rollback flow.
+            await markFixRolledBackInTranscript(projectRoot, id);
             return { ok: true, id, file: record.finding.file };
         },
     }));

package/dist/tools/quality-gate.js

@@ -8,7 +8,7 @@
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
-import { readQualityGate, writeQualityGate, computeQualityGate } from "./quality-store.js";
+import { readQualityGate, writeQualityGate, computeQualityGate, clearQualityGate } from "./quality-store.js";
 /** Validate a single finding object; returns true when well-formed. */
 function isValidFinding(raw) {
     if (!raw || typeof raw !== 'object')
@@ -66,12 +66,14 @@ export function registerQualityGateTool(ctx) {
             'and overall PASS/FAIL status. ' +
             'Operation "read" (default) returns the persisted machine-readable quality certificate. ' +
             'Operation "compute" computes a fresh snapshot from this round\'s findings/validation results, ' +
-            'persists it to .iterate/quality-gate.json, and returns it.',
+            'persists it to .iterate/quality-gate.json, and returns it. ' +
+            'Operation "clear" removes the persisted certificate (use it to reset a stale gate before ' +
+            'starting a fresh iteration).',
         parameters: {
             operation: {
                 type: 'string',
-                description: 'Operation: read (load persisted certificate) or compute (recompute + persist). Default: read.',
-                enum: ['read', 'compute'],
+                description: 'Operation: read (load persisted certificate), compute (recompute + persist), or clear (remove the persisted certificate). Default: read.',
+                enum: ['read', 'compute', 'clear'],
             },
             dimensions: {
                 type: 'array',
@@ -137,6 +139,9 @@ export function registerQualityGateTool(ctx) {
                 if (operation === 'compute') {
                     lines.push('', 'Quality gate snapshot computed and persisted.');
                 }
+                if (operation === 'clear') {
+                    lines.push('', 'Quality gate certificate cleared — the gate will be recomputed on the next iteration.');
+                }
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
@@ -146,6 +151,18 @@ export function registerQualityGateTool(ctx) {
                 return { ok: false, kind: 'quality_gate', error: resolved.reason };
             const projectRoot = resolved.root;
             const operation = typeof args.operation === 'string' ? args.operation : 'read';
+            if (operation === 'clear') {
+                const result = clearQualityGate(projectRoot);
+                if (!result.ok) {
+                    return { ok: false, kind: 'quality_gate', operation: 'clear', error: result.error };
+                }
+                return {
+                    ok: true,
+                    kind: 'quality_gate',
+                    operation: 'clear',
+                    snapshot: readQualityGate(projectRoot),
+                };
+            }
             if (operation === 'compute') {
                 const dimensions = Array.isArray(args.dimensions)
                     ? args.dimensions.filter((d) => typeof d === 'string' && d.length > 0)

package/dist/tools/quality-store.js

@@ -104,6 +104,24 @@ export function writeQualityGate(projectRoot, snapshot) {
     }
     return { ok: true };
 }
+/**
+ * Clear the persisted quality gate certificate (`.iterate/quality-gate.json`).
+ * Returns whether a file existed and was removed, or a structured error when
+ * the removal fails — a stale FAIL certificate must never silently persist.
+ */
+export function clearQualityGate(projectRoot) {
+    const filePath = path.join(projectRoot, '.iterate', QUALITY_GATE_FILE);
+    const existed = fs.existsSync(filePath);
+    if (!existed)
+        return { ok: true, existed: false };
+    try {
+        fs.rmSync(filePath, { force: true });
+    }
+    catch (err) {
+        return { ok: false, error: `unable to remove ${filePath}: ${String(err)}` };
+    }
+    return { ok: true, existed: true };
+}
 /**
  * Compute the convergence rate for a dimension.
  *

package/dist/tools/transcript.js

@@ -331,3 +331,34 @@ async function persist(file, manifest) {
     await mkdir(dirname(file), { recursive: true });
     await writeTextAtomicAsync(file, JSON.stringify(manifest, null, 2));
 }
+/**
+ * Mark one applied fix as rolled back in the PERSISTED transcript, so the
+ * client observatory (F4 fix/rollback tab) reflects the reversal instead of
+ * showing the fix as still "成功" after a rollback.
+ *
+ * Best-effort and fail-safe: a missing/corrupt transcript is ignored, and a
+ * persistence failure never throws into the caller (rollback itself is the
+ * primary operation; the transcript is a secondary UI projection).
+ *
+ * @returns true when a transcript existed and was updated.
+ */
+export async function markFixRolledBackInTranscript(projectRoot, id) {
+    const file = transcriptPath(projectRoot);
+    if (!existsSync(file))
+        return false;
+    try {
+        const parsed = JSON.parse(await readFile(file, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.fixes))
+            return false;
+        const { config } = loadEffectiveConfig(projectRoot);
+        const approval = config.observatory?.approval ?? 'ask';
+        const builder = rehydrateBuilder(parsed, approval);
+        builder.markFixRolledBack(id);
+        await persist(file, builder.serialize());
+        return true;
+    }
+    catch {
+        // Never let the secondary transcript write break the rollback flow.
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "3.5.0",
+  "version": "3.5.2",
   "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",
@@ -33,7 +33,11 @@
         "0.1.2-alpha.4": "compatible",
         "0.1.2-alpha.5": "compatible",
         "0.1.2-rc.1": "compatible",
-        "0.1.3-alpha.1": "compatible"
+        "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.2": "compatible"
       }
     },
     "client": {
@@ -71,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/live.ts

@@ -107,6 +107,11 @@ export function classifyTool(
     iterate_status: 'info',
     iterate_config: 'info',
     iterate_context: 'info',
+    // v3.0 quality command-center tools — surface their activity in the live
+    // feed too (previously these three never produced a live entry).
+    iterate_experience: 'info',
+    iterate_quality_gate: 'info',
+    iterate_defense_events: 'info',
   }
   const type = records[name]
   if (!type) return null

package/src/skill-prompt.ts

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

package/src/tools/checkpoint.ts

@@ -335,6 +335,33 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
             `Checkpoint: ${value.hasCheckpoint ? 'yes' : 'no'}${value.interrupted ? ' (interrupted — resumable)' : ''}${value.resumeCount ? ` · resumed ${value.resumeCount}x` : ''}`,
             value.lastUpdated ? `Last updated: ${value.lastUpdated}` : '',
           ]
+          // v3.0 quality command-center summaries (surfaced here so a single
+          // status read reports the whole run state in text too).
+          const gate = value.qualityGate as QualityGateSnapshot | null | undefined
+          if (gate) {
+            lines.push(
+              `Quality gate: ${gate.overallStatus.toUpperCase()} · score ${gate.overallScore} · ` +
+                `verification ${gate.passedChecks}/${gate.totalChecks} passed` +
+                (gate.failReason ? ` · ${gate.failReason}` : ''),
+            )
+          }
+          const exp = value.experienceBank as { totalEntries?: number; totalHits?: number } | null | undefined
+          if (exp) {
+            lines.push(
+              `Experience bank: ${exp.totalEntries ?? 0} entries · ${exp.totalHits ?? 0} cumulative hits`,
+            )
+          }
+          const def = value.defenseEvents as { totalEvents?: number; counts?: Record<DefenseEventType, number> } | null | undefined
+          if (def) {
+            const counts = def.counts ?? ({} as Record<DefenseEventType, number>)
+            const total = Object.values(counts).reduce((s, n) => s + (n || 0), 0)
+            lines.push(
+              `Defense events: ${def.totalEvents ?? total} recorded` +
+                (total > 0
+                  ? ` (precondition_failed:${counts.precondition_failed ?? 0}, rollback:${counts.rollback ?? 0}, invariant_violated:${counts.invariant_violated ?? 0}, assumption_falsified:${counts.assumption_falsified ?? 0})`
+                  : ''),
+            )
+          }
           return [{ type: 'text', text: lines.filter(Boolean).join('\n') }]
         },
       },

package/src/tools/context.ts

@@ -1,5 +1,5 @@
-import { readFileSync, existsSync, statSync } from 'node:fs'
-import { join, dirname, resolve } from 'node:path'
+import { readFileSync, existsSync, realpathSync, statSync } from 'node:fs'
+import { join, dirname, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { resolveProjectRootForExec } from '../config-loader.ts'
@@ -7,6 +7,33 @@ import { resolveProjectRootForExec } from '../config-loader.ts'
 /** How many ancestor directories we walk up looking for a SKILL.md. */
 const MAX_SKILL_DIR_LOOKUP_DEPTH = 12
 
+/**
+ * Whether a model-supplied `skillDir` may be used as a SKILL.md search root.
+ *
+ * `skillDir` is model-controlled, so it is only honored when it is an existing
+ * directory whose REAL path (symlinks resolved) sits inside one of the allowed
+ * roots (the project root or the plugin directory). Anything else — a path
+ * outside the allowed roots, a nonexistent dir, or a symlink pointing outside
+ * (e.g. at `/etc`) — is rejected so arbitrary file contents can never be
+ * injected wholesale into the review context.
+ */
+export function isAllowedSkillDir(skillDir: string, allowedRoots: readonly string[]): boolean {
+  if (typeof skillDir !== 'string' || skillDir.trim().length === 0) return false
+  try {
+    const dir = resolve(skillDir)
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) return false
+    return allowedRoots.some((root) => {
+      if (typeof root !== 'string' || root.length === 0) return false
+      const rootReal = realpathSync(root)
+      const rootPrefix = rootReal.endsWith(sep) ? rootReal : rootReal + sep
+      const real = realpathSync(dir)
+      return real === rootReal || real.startsWith(rootPrefix)
+    })
+  } catch {
+    return false
+  }
+}
+
 /** Maximum number of image attachments relayed into the context in one call. */
 const MAX_ATTACHMENTS = 8
 
@@ -304,8 +331,13 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
           // the auto-detected root / project root.
           if (typeof args.skillDir === 'string' && args.skillDir.trim()) {
             try {
-              const dir = resolve(args.skillDir)
-              if (existsSync(dir) && statSync(dir).isDirectory()) candidates.push(dir)
+              // Model-controlled path: only honor it when its REAL path stays
+              // inside the project root or the plugin directory — never let a
+              // 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))
+              }
             } catch {
               // unreadable/invalid skillDir — skip it
             }

package/src/tools/decision-log.ts

@@ -106,7 +106,16 @@ export function readDecisionLogDetailed(projectRoot: string): DecisionLogRead {
     const trimmed = line.trim()
     if (trimmed.length === 0) continue
     try {
-      entries.push(JSON.parse(trimmed) as DecisionLogEntry)
+      const parsed: unknown = JSON.parse(trimmed)
+      if (
+        parsed === null || typeof parsed !== 'object' ||
+        typeof (parsed as { timestamp?: unknown }).timestamp !== 'string' ||
+        typeof (parsed as { type?: unknown }).type !== 'string'
+      ) {
+        invalidLines += 1
+        continue
+      }
+      entries.push(parsed as DecisionLogEntry)
     } catch {
       invalidLines += 1
     }

package/src/tools/experience-bank.ts

@@ -9,7 +9,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
-import { readExperienceBank, writeExperienceBank, searchExperienceEntries, upsertExperience } from './experience-store.ts'
+import { readExperienceBank, writeExperienceBank, searchExperienceEntries, upsertExperience, removeExperience } from './experience-store.ts'
 import type { ExperienceEntryInput } from './experience-store.ts'
 import type { ExperienceEntry } from '../types.ts'
 
@@ -81,12 +81,13 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
         'List/search/get return matching entries with hit counts, verified fixes, and related context. ' +
         '"add" upserts an experience entry into .iterate/experience.json — a repeat of the same ' +
         'pattern+dimension increments its hit count instead of duplicating it. ' +
+        '"remove" deletes an entry by id (useful for pruning stale or incorrect experiences). ' +
         'Use it to remember fixes that worked so future rounds apply them first.',
       parameters: {
         operation: {
           type: 'string',
-          description: 'Operation: list (browse all), search (by query), get (by id), add (add a new experience). Default: list.',
-          enum: ['list', 'search', 'get', 'add'],
+          description: 'Operation: list (browse all), search (by query), get (by id), add (add a new experience), remove (delete by id). Default: list.',
+          enum: ['list', 'search', 'get', 'add', 'remove'],
         },
         query: {
           type: 'string',
@@ -154,6 +155,9 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
               `Tags: ${entry.tags.join(', ')}`,
             ].join('\n') }]
           }
+          if (value.operation === 'remove') {
+            return [{ type: 'text', text: `Removed experience entry. Bank now holds ${value.count ?? 0} entries (${value.totalHits ?? 0} cumulative hits).` }]
+          }
           if (value.operation === 'get' && value.entry) {
             const entry = value.entry as unknown as ExperienceEntry
             return [{ type: 'text', text: [
@@ -214,6 +218,39 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
           }
         }
 
+        if (operation === 'remove') {
+          const id = typeof args.id === 'string' && args.id ? args.id : ''
+          if (!id) {
+            return {
+              ok: false,
+              kind: 'experience',
+              operation: 'remove',
+              error: 'id is required for remove',
+            }
+          }
+          const bank = readExperienceBank(projectRoot)
+          const { bank: next, removed } = removeExperience(bank, id)
+          if (!removed) {
+            return {
+              ok: false,
+              kind: 'experience',
+              operation: 'remove',
+              error: `Experience not found: ${id}`,
+            }
+          }
+          const write = writeExperienceBank(projectRoot, next)
+          if (!write.ok) {
+            return { ok: false, kind: 'experience', operation: 'remove', error: write.error }
+          }
+          return {
+            ok: true,
+            kind: 'experience',
+            operation: 'remove',
+            count: next.entries.length,
+            totalHits: next.totalHits,
+          }
+        }
+
         const bank = readExperienceBank(projectRoot)
 
         if (operation === 'get' && typeof args.id === 'string') {

package/src/tools/experience-store.ts

@@ -171,3 +171,29 @@ export function upsertExperience(
     entryId: id,
   }
 }
+
+/**
+ * Remove an experience entry by id.
+ * Returns the resulting bank plus whether an entry was actually removed. An
+ * unknown id is a no-op (the caller decides how to surface it). Never mutates
+ * the input bank.
+ */
+export function removeExperience(
+  bank: ExperienceBank,
+  id: string,
+): { bank: ExperienceBank; removed: boolean } {
+  const target = typeof id === 'string' && id ? id : ''
+  if (!target) return { bank, removed: false }
+  const entries = bank.entries.filter((e) => e.id !== target)
+  if (entries.length === bank.entries.length) return { bank, removed: false }
+  const lastUpdated = new Date().toISOString()
+  return {
+    bank: {
+      ...bank,
+      entries,
+      lastUpdated,
+      totalHits: bank.totalHits ?? 0,
+    },
+    removed: true,
+  }
+}

package/src/tools/fix.ts

@@ -19,7 +19,7 @@
 
 import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs'
 import { writeJsonAtomic, writeTextAtomic } from '../atomic-fs.ts'
-import { join, sep } from 'node:path'
+import { dirname, join, sep } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { loadEffectiveConfig, resolveProjectRootForExec } from '../config-loader.ts'
@@ -27,6 +27,7 @@ import { runWithJob } from '../jobs.ts'
 import { countTouchedMethods } from '../method-scope.ts'
 import { fixBackupPath, fixRegistryPath, fixesDir } from '../paths.ts'
 import { appendDecisionEntry } from './decision-log.ts'
+import { markFixRolledBackInTranscript } from './transcript.ts'
 import type { FileDiffHunk, FixRecord, FixRegistry, ReviewFinding } from '../types.ts'
 
 // ─── Constants ───────────────────────────────────────────────────────────────
@@ -206,15 +207,25 @@ export function resolveProjectFile(projectRoot: string, file: string): { ok: tru
     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: string
     let real: string
     try {
       rootReal = realpathSync(projectRoot)
-      real = realpathSync(resolved)
+      real = realpathSync(probe)
     } catch {
       return { ok: false, reason: 'failed to resolve real path for containment check' }
     }
@@ -491,9 +502,9 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
           // 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 {
               ok: false,
@@ -704,7 +715,9 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
         const target = resolveProjectFile(projectRoot, record.finding.file)
         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)}` }
         }
@@ -723,6 +736,12 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
           data: { id, file: record.finding.file, revertedDiff: record.diffSummary },
         })
 
+        // Mirror the reversal into the persisted observatory transcript (F4) so
+        // the client no longer shows a rolled-back fix as "成功". Best-effort:
+        // a missing/corrupt transcript is left untouched and never breaks the
+        // rollback flow.
+        await markFixRolledBackInTranscript(projectRoot, id)
+
         return { ok: true, id, file: record.finding.file }
       },
     }),

package/src/tools/quality-gate.ts

@@ -10,7 +10,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
-import { readQualityGate, writeQualityGate, computeQualityGate } from './quality-store.ts'
+import { readQualityGate, writeQualityGate, computeQualityGate, clearQualityGate } from './quality-store.ts'
 import type { QualityGateSnapshot } from '../types.ts'
 
 /** Validate a single finding object; returns true when well-formed. */
@@ -72,12 +72,14 @@ export function registerQualityGateTool(ctx: { tools: { register: (def: ReturnTy
         'and overall PASS/FAIL status. ' +
         'Operation "read" (default) returns the persisted machine-readable quality certificate. ' +
         'Operation "compute" computes a fresh snapshot from this round\'s findings/validation results, ' +
-        'persists it to .iterate/quality-gate.json, and returns it.',
+        'persists it to .iterate/quality-gate.json, and returns it. ' +
+        'Operation "clear" removes the persisted certificate (use it to reset a stale gate before ' +
+        'starting a fresh iteration).',
       parameters: {
         operation: {
           type: 'string',
-          description: 'Operation: read (load persisted certificate) or compute (recompute + persist). Default: read.',
-          enum: ['read', 'compute'],
+          description: 'Operation: read (load persisted certificate), compute (recompute + persist), or clear (remove the persisted certificate). Default: read.',
+          enum: ['read', 'compute', 'clear'],
         },
         dimensions: {
           type: 'array',
@@ -145,6 +147,9 @@ export function registerQualityGateTool(ctx: { tools: { register: (def: ReturnTy
           if (operation === 'compute') {
             lines.push('', 'Quality gate snapshot computed and persisted.')
           }
+          if (operation === 'clear') {
+            lines.push('', 'Quality gate certificate cleared — the gate will be recomputed on the next iteration.')
+          }
           return [{ type: 'text', text: lines.join('\n') }]
         },
       },
@@ -156,6 +161,19 @@ export function registerQualityGateTool(ctx: { tools: { register: (def: ReturnTy
 
         const operation = typeof args.operation === 'string' ? args.operation : 'read'
 
+        if (operation === 'clear') {
+          const result = clearQualityGate(projectRoot)
+          if (!result.ok) {
+            return { ok: false, kind: 'quality_gate', operation: 'clear', error: result.error }
+          }
+          return {
+            ok: true,
+            kind: 'quality_gate',
+            operation: 'clear',
+            snapshot: readQualityGate(projectRoot) as unknown as JsonValue,
+          }
+        }
+
         if (operation === 'compute') {
           const dimensions = Array.isArray(args.dimensions)
             ? args.dimensions.filter((d): d is string => typeof d === 'string' && d.length > 0)

package/src/tools/quality-store.ts

@@ -116,6 +116,25 @@ export function writeQualityGate(
   return { ok: true }
 }
 
+/**
+ * Clear the persisted quality gate certificate (`.iterate/quality-gate.json`).
+ * Returns whether a file existed and was removed, or a structured error when
+ * the removal fails — a stale FAIL certificate must never silently persist.
+ */
+export function clearQualityGate(
+  projectRoot: string,
+): { ok: true; existed: boolean } | { ok: false; error: string } {
+  const filePath = path.join(projectRoot, '.iterate', QUALITY_GATE_FILE)
+  const existed = fs.existsSync(filePath)
+  if (!existed) return { ok: true, existed: false }
+  try {
+    fs.rmSync(filePath, { force: true })
+  } catch (err) {
+    return { ok: false, error: `unable to remove ${filePath}: ${String(err)}` }
+  }
+  return { ok: true, existed: true }
+}
+
 /**
  * Compute the convergence rate for a dimension.
  *

package/src/tools/transcript.ts

@@ -340,4 +340,36 @@ function rehydrateBuilder(manifest: TranscriptManifest, approval: 'ask' | 'deny'
 async function persist(file: string, manifest: TranscriptManifest): Promise<void> {
   await mkdir(dirname(file), { recursive: true })
   await writeTextAtomicAsync(file, JSON.stringify(manifest, null, 2))
+}
+
+/**
+ * Mark one applied fix as rolled back in the PERSISTED transcript, so the
+ * client observatory (F4 fix/rollback tab) reflects the reversal instead of
+ * showing the fix as still "成功" after a rollback.
+ *
+ * Best-effort and fail-safe: a missing/corrupt transcript is ignored, and a
+ * persistence failure never throws into the caller (rollback itself is the
+ * primary operation; the transcript is a secondary UI projection).
+ *
+ * @returns true when a transcript existed and was updated.
+ */
+export async function markFixRolledBackInTranscript(
+  projectRoot: string,
+  id: string,
+): Promise<boolean> {
+  const file = transcriptPath(projectRoot)
+  if (!existsSync(file)) return false
+  try {
+    const parsed = JSON.parse(await readFile(file, 'utf-8')) as unknown as TranscriptManifest
+    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.fixes)) return false
+    const { config } = loadEffectiveConfig(projectRoot)
+    const approval = config.observatory?.approval ?? 'ask'
+    const builder = rehydrateBuilder(parsed, approval)
+    builder.markFixRolledBack(id)
+    await persist(file, builder.serialize())
+    return true
+  } catch {
+    // Never let the secondary transcript write break the rollback flow.
+    return false
+  }
 }