iterate-plugin 3.4.1 → 3.5.1

package/src/config-write.ts

@@ -10,9 +10,10 @@
  * config, always back up before writing, roll back on failure.
  */
 
-import { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { copyFileSync, existsSync, readFileSync, rmSync } from 'node:fs'
 import { join } from 'node:path'
 import yaml from 'js-yaml'
+import { writeTextAtomic } from './atomic-fs.ts'
 
 /** Config file name (must match config-loader). */
 export const CONFIG_FILE = 'iterate.config.yaml'
@@ -194,7 +195,7 @@ export function writeConfigFile(
   }
 
   try {
-    writeFileSync(configPath, yaml.dump(config, { noRefs: true }), 'utf-8')
+    writeTextAtomic(configPath, yaml.dump(config, { noRefs: true }))
   } catch (err) {
     let rollbackError = ''
     try {

package/src/live.ts

@@ -24,8 +24,9 @@
  *     or crash a tool call.
  */
 
-import { mkdir, readFile, writeFile, stat, appendFile, rename } from 'node:fs/promises'
+import { mkdir, readFile, stat, appendFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
+import { writeTextAtomicAsync } from './atomic-fs.ts'
 import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import type { ToolExecution } from '@deepseek-ai/dsh-tools'
@@ -106,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
@@ -136,9 +142,9 @@ export async function appendLive(projectRoot: string, entry: LiveActivityEntry):
       const raw = await readFile(file, 'utf-8')
       const lines = raw.split('\n').filter(Boolean)
       const tail = lines.slice(-LIVE_MAX_ENTRIES)
-      const tmp = `${file}.trim.tmp`
-      await writeFile(tmp, tail.join('\n') + '\n', 'utf-8')
-      await rename(tmp, file)
+      // Atomic rewrite (unique temp + rename) so a crash mid-trim never
+      // truncates the live feed; the temp file is prunable by iterate_prune.
+      await writeTextAtomicAsync(file, tail.join('\n') + '\n')
     }
     await appendFile(file, line, 'utf-8')
   } catch {

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

@@ -9,10 +9,11 @@
  * Checkpoint layout: `.iterate/checkpoint.json`.
  */
 
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
+import { writeJsonAtomic } from '../atomic-fs.ts'
 import { checkpointPath, iterateDir, transcriptPath } from '../paths.ts'
 import { readRegistry } from './fix.ts'
 import { readDecisionEntries } from './decision-log.ts'
@@ -223,10 +224,7 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
           }
           try {
             mkdirSync(iterateDir(projectRoot), { recursive: true })
-            const cpPath = checkpointPath(projectRoot)
-            const tmpPath = `${cpPath}.tmp-${Date.now()}`
-            writeFileSync(tmpPath, JSON.stringify(resumed, null, 2), 'utf-8')
-            renameSync(tmpPath, cpPath)
+            writeJsonAtomic(checkpointPath(projectRoot), resumed)
           } catch (err) {
             return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` }
           }
@@ -266,12 +264,10 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
           }
           try {
             mkdirSync(iterateDir(projectRoot), { recursive: true })
-            // Atomic write (temp + rename): a crash mid-write must not corrupt
-            // the checkpoint and silently lose the interruption state.
-            const cpPath = checkpointPath(projectRoot)
-            const tmpPath = `${cpPath}.tmp-${Date.now()}`
-            writeFileSync(tmpPath, JSON.stringify(checkpoint, null, 2), 'utf-8')
-            renameSync(tmpPath, cpPath)
+            // Atomic write (temp + rename, via writeJsonAtomic): a crash
+            // mid-write must not corrupt the checkpoint and silently lose the
+            // interruption state.
+            writeJsonAtomic(checkpointPath(projectRoot), checkpoint)
           } catch (err) {
             return { operation: 'save', ok: false, error: `failed to write checkpoint: ${String(err)}` }
           }
@@ -294,6 +290,9 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
   ctx.tools.register(
     defineTool({
       name: 'iterate_status',
+      // Read-only aggregation of on-disk state → safe to join a parallel
+      // dispatch group alongside other read-only sibling calls.
+      isConcurrencySafe: () => true,
       description:
         'Summarize the current iterate run: mode, current round vs total, fixes applied, architectural ' +
         'findings remaining, decision-log size, and whether a resume checkpoint exists.',
@@ -336,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/config.ts

@@ -19,6 +19,20 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
   ctx.tools.register(
     defineTool({
       name: 'iterate_config',
+      // `read` never writes; `write` persists a config update → only read
+      // joins a parallel dispatch group.
+      isConcurrencySafe: (args) => (args as { operation?: unknown }).operation !== 'write',
+      // Pending-call card: a config read vs a validated write.
+      presentCall: (args) => {
+        const a = args as { operation?: unknown; section?: unknown }
+        const isWrite = a.operation === 'write'
+        return {
+          card: 'generic',
+          title: isWrite ? 'Update iterate.config.yaml' : 'Read iterate.config.yaml',
+          kind: isWrite ? 'edit' : 'read',
+          ...(typeof a.section === 'string' && a.section ? { rawInput: { section: a.section } } : {}),
+        }
+      },
       description:
         'Read or update the iterate.config.yaml configuration from the project root. ' +
         'Returns the full parsed config, a specific section, or validation errors. ' +

package/src/tools/context.ts

@@ -178,6 +178,9 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
   ctx.tools.register(
     defineTool({
       name: 'iterate_context',
+      // Read-only (reads SKILL.md / ITERATE.md) → safe to join a parallel
+      // dispatch group alongside other read-only sibling calls.
+      isConcurrencySafe: () => true,
       description:
         'Read project context files (SKILL.md and/or ITERATE.md). ' +
         'SKILL.md contains the original iterate skill instructions; it is searched in ' +

package/src/tools/decision-log.ts

@@ -77,30 +77,50 @@ export function appendDecisionEntry(projectRoot: string, entry: DecisionLogEntry
 }
 
 /**
- * Read all entries from the decision log.
+ * Detailed log read: valid entries plus the number of corrupt lines that were
+ * skipped, so callers can surface silent audit-trail loss to the model/UI.
+ */
+export interface DecisionLogRead {
+  entries: DecisionLogEntry[]
+  invalidLines: number
+}
+
+/**
+ * Read all entries from the decision log, plus the count of corrupt lines.
  * A single corrupt line (partial write, hand-edit) is SKIPPED, not fatal —
- * one bad line must never empty the whole history for every reader.
+ * one bad line must never empty the whole history for every reader — but it
+ * is counted in `invalidLines` so it never disappears silently.
  */
-export function readDecisionEntries(projectRoot: string): DecisionLogEntry[] {
+export function readDecisionLogDetailed(projectRoot: string): DecisionLogRead {
   const filePath = join(projectRoot, LOG_DIR, LOG_FILE)
-  if (!existsSync(filePath)) return []
+  if (!existsSync(filePath)) return { entries: [], invalidLines: 0 }
   let content: string
   try {
     content = readFileSync(filePath, 'utf-8')
   } catch {
-    return []
+    return { entries: [], invalidLines: 0 }
   }
-  const out: DecisionLogEntry[] = []
+  const entries: DecisionLogEntry[] = []
+  let invalidLines = 0
   for (const line of content.split('\n')) {
     const trimmed = line.trim()
     if (trimmed.length === 0) continue
     try {
-      out.push(JSON.parse(trimmed) as DecisionLogEntry)
+      entries.push(JSON.parse(trimmed) as DecisionLogEntry)
     } catch {
-      // skip the corrupt line, keep the rest
+      invalidLines += 1
     }
   }
-  return out
+  return { entries, invalidLines }
+}
+
+/**
+ * Read all entries from the decision log.
+ * A single corrupt line (partial write, hand-edit) is SKIPPED, not fatal —
+ * one bad line must never empty the whole history for every reader.
+ */
+export function readDecisionEntries(projectRoot: string): DecisionLogEntry[] {
+  return readDecisionLogDetailed(projectRoot).entries
 }
 
 /**
@@ -112,6 +132,9 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
   ctx.tools.register(
     defineTool({
       name: 'iterate_decision_log',
+      // `read` never writes; `append` extends the audit log → only read joins
+      // a parallel dispatch group.
+      isConcurrencySafe: (args) => (args as { operation?: unknown }).operation === 'read',
       description:
         'Append-only decision log for the iterate loop. ' +
         'Use `append` to record a round start, review finding, fix, validation result, or decision. ' +
@@ -164,6 +187,7 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
           properties: {
             operation: { type: 'string', required: true },
             entryCount: { type: 'integer' },
+            invalidLines: { type: 'integer' },
             logPath: { type: 'string' },
             entries: { type: 'json' },
             success: { type: 'boolean' },
@@ -184,10 +208,11 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
         const projectRoot = resolved.root
 
         if (args.operation === 'read') {
-          const entries = readDecisionEntries(projectRoot)
+          const { entries, invalidLines } = readDecisionLogDetailed(projectRoot)
           return {
             operation: 'read',
             entryCount: entries.length,
+            invalidLines,
             logPath: join(projectRoot, LOG_DIR, LOG_FILE),
             entries: entries as unknown as JsonValue,
           }

package/src/tools/defense-events.ts

@@ -91,6 +91,9 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
   ctx.tools.register(
     defineTool({
       name: 'iterate_defense_events',
+      // List/counts never write; only `record` persists an event → read shapes
+      // join a parallel dispatch group.
+      isConcurrencySafe: (args) => (args as { operation?: unknown }).operation !== 'record',
       description:
         'Query or record defense events: precondition failures, rollbacks, invariant violations, ' +
         'and assumption falsifications. ' +

package/src/tools/defense-store.ts

@@ -7,6 +7,8 @@
 
 import * as fs from 'node:fs'
 import * as path from 'node:path'
+import { iterateDir } from '../paths.ts'
+import { writeJsonAtomic } from '../atomic-fs.ts'
 import type { DefenseEvent, DefenseEventStream, DefenseEventType } from '../types.ts'
 
 const DEFENSE_EVENTS_FILE = 'defense-events.json'
@@ -83,14 +85,16 @@ export function writeDefenseEvents(
   projectRoot: string,
   stream: DefenseEventStream,
 ): { ok: true } | { ok: false; error: string } {
-  const dirPath = path.join(projectRoot, '.iterate')
+  const dirPath = iterateDir(projectRoot)
   const filePath = path.join(dirPath, DEFENSE_EVENTS_FILE)
 
   try {
     if (!fs.existsSync(dirPath)) {
       fs.mkdirSync(dirPath, { recursive: true })
     }
-    fs.writeFileSync(filePath, JSON.stringify(stream, null, 2), 'utf-8')
+    // Atomic (temp + rename): a crash mid-write can never leave a truncated
+    // defense event stream behind.
+    writeJsonAtomic(filePath, stream)
   } catch (err) {
     return { ok: false, error: `unable to write ${filePath}: ${String(err)}` }
   }

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'
 
@@ -72,18 +72,22 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
   ctx.tools.register(
     defineTool({
       name: 'iterate_experience',
+      // List/search/get never write; only `add` upserts the bank → read shapes
+      // join a parallel dispatch group.
+      isConcurrencySafe: (args) => (args as { operation?: unknown }).operation !== 'add',
       description:
         'Query or extend the experience bank: browse/search historical fixes and patterns, ' +
         'or record a new verified fix (operation:"add"). ' +
         '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',
@@ -151,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: [
@@ -211,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

@@ -7,6 +7,8 @@
 
 import * as fs from 'node:fs'
 import * as path from 'node:path'
+import { iterateDir } from '../paths.ts'
+import { writeJsonAtomic } from '../atomic-fs.ts'
 import type { ExperienceBank, ExperienceEntry } from '../types.ts'
 
 const EXPERIENCE_FILE = 'experience.json'
@@ -45,14 +47,16 @@ export function writeExperienceBank(
   projectRoot: string,
   bank: ExperienceBank,
 ): { ok: true } | { ok: false; error: string } {
-  const dirPath = path.join(projectRoot, '.iterate')
+  const dirPath = iterateDir(projectRoot)
   const filePath = path.join(dirPath, EXPERIENCE_FILE)
 
   try {
     if (!fs.existsSync(dirPath)) {
       fs.mkdirSync(dirPath, { recursive: true })
     }
-    fs.writeFileSync(filePath, JSON.stringify(bank, null, 2), 'utf-8')
+    // Atomic (temp + rename): a crash mid-write can never leave a truncated
+    // experience bank behind.
+    writeJsonAtomic(filePath, bank)
   } catch (err) {
     return { ok: false, error: `unable to write ${filePath}: ${String(err)}` }
   }
@@ -167,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

@@ -17,7 +17,8 @@
  *   - Atomicity is enforced against `config.atomic.max_lines` unless `force`.
  */
 
-import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs'
+import { writeJsonAtomic, writeTextAtomic } from '../atomic-fs.ts'
 import { join, sep } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
@@ -26,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 ───────────────────────────────────────────────────────────────
@@ -277,6 +279,19 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
   ctx.tools.register(
     defineTool({
       name: 'iterate_fix',
+      // Pending-call card: surface the file about to change as an inline diff.
+      // oldText is null — a call-time presenter has no access to the file's
+      // prior content (an overwrite, per the presentation contract).
+      presentCall: (args) => {
+        const a = args as { file?: unknown; content?: unknown }
+        if (typeof a.file !== 'string' || typeof a.content !== 'string') return undefined
+        return {
+          card: 'diff',
+          title: `Fix ${a.file}`,
+          diffs: [{ path: a.file, oldText: null, newText: a.content }],
+          locations: [{ path: a.file }],
+        }
+      },
       description:
         'Apply ONE atomic fix to a file. Pass the target relative `file`, the finding that motivated ' +
         'the fix, the NEW full `content` of that file (after your edit), and the current `round`. ' +
@@ -454,7 +469,7 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         }
 
         try {
-          writeFileSync(target.resolved, args.content, 'utf-8')
+          writeTextAtomic(target.resolved, args.content)
         } catch (err) {
           return { ok: false, error: `failed to write file: ${String(err)}` }
         }
@@ -472,7 +487,7 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         }
         const nextRegistry = upsertRecord(registry, record)
         try {
-          writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(nextRegistry, null, 2), 'utf-8')
+          writeJsonAtomic(fixRegistryPath(projectRoot), nextRegistry)
         } catch (err) {
           // 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
@@ -524,6 +539,9 @@ export function registerDiffTool(ctx: { tools: { register: (def: ReturnType<type
   ctx.tools.register(
     defineTool({
       name: 'iterate_diff',
+      // Read-only (never writes project files or plugin state) → safe to join
+      // a parallel dispatch group alongside other read-only sibling calls.
+      isConcurrencySafe: () => true,
       description:
         'Show the changes made by iterate fixes. With `file`, returns the unified diff of the current ' +
         'file content vs its original (first backup). Without `file`, returns a summary of every fixed file.',
@@ -627,6 +645,17 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
   ctx.tools.register(
     defineTool({
       name: 'iterate_rollback',
+      // Pending-call card: which fix is about to be reverted.
+      presentCall: (args) => {
+        const a = args as { id?: unknown }
+        if (typeof a.id !== 'string' || a.id.length === 0) return undefined
+        return {
+          card: 'generic',
+          title: `Rollback fix ${a.id}`,
+          kind: 'edit',
+          rawInput: { id: a.id },
+        }
+      },
       description:
         'Revert a previously applied fix. Pass the fix `id` (returned by iterate_fix). ' +
         'The file is restored from the fix backup, the fix is removed from the registry, ' +
@@ -683,7 +712,7 @@ export function registerRollbackTool(ctx: { tools: { register: (def: ReturnType<
 
         const nextRegistry = removeRecord(registry, id)
         try {
-          writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(nextRegistry, null, 2), 'utf-8')
+          writeJsonAtomic(fixRegistryPath(projectRoot), nextRegistry)
         } catch (err) {
           return { ok: false, error: `failed to update fix registry: ${String(err)}` }
         }
@@ -695,6 +724,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/history.ts

@@ -80,6 +80,9 @@ export function registerHistoryTool(ctx: { tools: { register: (def: ReturnType<t
   ctx.tools.register(
     defineTool({
       name: 'iterate_history',
+      // Read-only audit view over on-disk state → safe to join a parallel
+      // dispatch group alongside other read-only sibling calls.
+      isConcurrencySafe: () => true,
       description:
         'Read the iteration history: decision-log entries (optionally filtered by entry `type`, `since` ' +
         'timestamp, and a `limit`) plus a summary of the fix registry (per-round fixed/failed counts). ' +