iterate-plugin 3.4.0 → 3.5.0

package/lib/parse.js

@@ -133,12 +133,13 @@ export function countSessionImages(session) {
   if (!session || typeof session !== 'object') return 0
 
   const ids = new Set()
+  const consumed = new Set()
   let count = 0
 
   /** @param {unknown} obj */
   const walk = (obj, depth) => {
     if (depth <= 0 || !obj || typeof obj !== 'object') return
-    if (seen.has(obj)) return
+    if (seen.has(obj) || consumed.has(obj)) return
     seen.add(obj)
     const o = /** @type {Record<string, unknown>} */ (obj)
 
@@ -158,6 +159,9 @@ export function countSessionImages(session) {
       } else {
         count += 1
       }
+      // The ref node is already counted; mark it consumed so descending into it
+      // (its own mediaType/attachmentId keys) does not double-count the image.
+      consumed.add(ref)
     }
 
     if (Array.isArray(obj)) {
@@ -364,18 +368,25 @@ function attachLive(manifest, source) {
  * manifest buried inside an arbitrary result still surfaces. Never throws.
  *
  * @param {unknown} obj
+ * @param {Set<unknown>} [seen]
+ * @param {number} [depth]
  * @returns {Record<string, unknown> | null}
  */
-function extractTranscript(obj) {
+function extractTranscript(obj, seen, depth) {
+  if (depth === undefined) depth = 0
+  if (depth > 20) return null
   if (typeof obj === 'string') {
     try {
       const parsed = JSON.parse(obj)
-      return extractTranscript(parsed)
+      return extractTranscript(parsed, seen, depth + 1)
     } catch {
       return null
     }
   }
   if (!obj || typeof obj !== 'object') return null
+  if (!seen) seen = new Set()
+  if (seen.has(obj)) return null
+  seen.add(obj)
 
   // Direct manifest.
   if (isTranscriptManifest(obj)) return /** @type {Record<string, unknown>} */ (obj)
@@ -397,11 +408,11 @@ function extractTranscript(obj) {
     if (val !== undefined) {
       if (Array.isArray(val)) {
         for (const item of val) {
-          const found = extractTranscript(item)
+          const found = extractTranscript(item, seen, depth + 1)
           if (found) return attachLive(found, o)
         }
       } else {
-        const found = extractTranscript(val)
+        const found = extractTranscript(val, seen, depth + 1)
         if (found) return attachLive(found, o)
       }
     }
@@ -745,6 +756,29 @@ function latestToolResultNode(session, toolName) {
   const messages = safeGet(s, 'messages')
   if (Array.isArray(messages)) {
     const msgs = /** @type {Array<Record<string, unknown>>} */ (messages)
+    // Assistant tool-call variant: the tool result may live on the call object
+    // inside message.tool_calls rather than on session.toolCalls. Scan every
+    // message for a matching call (newest-first) before falling back to the
+    // last message's raw content — a conversational closing message must not
+    // shadow an earlier message's real tool result.
+    for (let i = msgs.length - 1; i >= 0; i--) {
+      const msg = msgs[i]
+      if (!msg) continue
+      const calls = safeGet(msg, 'tool_calls')
+      if (!Array.isArray(calls)) continue
+      const callList = /** @type {Array<Record<string, unknown>>} */ (calls)
+      for (let j = callList.length - 1; j >= 0; j--) {
+        const call = callList[j]
+        if (!call) continue
+        const name = String(safeGet(call, 'name') ?? safeGet(call, 'tool') ?? '')
+        if (name !== toolName && !name.endsWith(toolName)) continue
+        const result = safeGet(call, 'result') ?? safeGet(call, 'response') ?? safeGet(call, 'message')
+        if (result !== undefined && result !== null) return result
+      }
+    }
+    // Fallback: the last message's raw content (pre-existing behavior — a
+    // plain conversational string yields null upstream, but an embedded JSON
+    // body is still worth surfacing for the deep-scan finders).
     for (let i = msgs.length - 1; i >= 0; i--) {
       const msg = msgs[i]
       if (!msg) continue
@@ -1151,6 +1185,7 @@ function computeSummaryFromFindings(findings) {
   const byDimension = {}
 
   for (const f of findings) {
+    if (!f || typeof f !== 'object') continue
     const sev = String(f.severity ?? 'low')
     if (sev in counts) counts[sev]++
     const dim = String(f.dimension ?? 'unknown')
@@ -1224,6 +1259,7 @@ export function severityStats(report) {
   const findings = /** @type {Array<Record<string, unknown>>} */ (report.findings ?? [])
   const counts = { critical: 0, high: 0, medium: 0, low: 0 }
   for (const f of findings) {
+    if (!f || typeof f !== 'object') continue
     const sev = String(f.severity ?? 'low')
     if (sev in counts) counts[sev]++
   }
@@ -1243,6 +1279,7 @@ export function groupByDimension(report) {
   /** @type {Record<string, Array<Record<string, unknown>>>} */
   const groups = {}
   for (const f of findings) {
+    if (!f || typeof f !== 'object') continue
     const dim = String(f.dimension ?? 'unknown')
     if (!groups[dim]) groups[dim] = []
     groups[dim].push(f)
@@ -1412,6 +1449,7 @@ export function normalizeFindingFilter(filter) {
  * @returns {boolean}
  */
 export function findingMatches(finding, filter) {
+  if (!finding || typeof finding !== 'object') return false
   const f = normalizeFindingFilter(filter)
   const sev = String(finding.severity ?? 'low')
   if (f.severities.length > 0 && !f.severities.includes(sev)) return false
@@ -1553,6 +1591,7 @@ export function setAllVerdicts(triageState, verdict, indices) {
 export function buildRoundHistory(report) {
   const rounds = Array.isArray(report.rounds) ? report.rounds : []
   return rounds.map((r) => {
+    if (!r || typeof r !== 'object') return { round: 0, count: 0, critical: 0, high: 0, medium: 0, low: 0 }
     const rr = /** @type {Record<string, unknown>} */ (r)
     const findings = Array.isArray(rr.findings) ? rr.findings : []
     const sev = severityStats({ findings })
@@ -1823,7 +1862,15 @@ export function filterTimelineEntries(entries, opts) {
     if (type && String(t.type ?? '') !== type) return false
     if (round && String(t.round ?? '') !== round) return false
     if (q) {
-      const hay = [String(t.type ?? ''), String(t.round ?? ''), JSON.stringify(t.data ?? {})].join(' ').toLowerCase()
+      let dataText = ''
+      try {
+        dataText = JSON.stringify(t.data ?? {})
+      } catch {
+        // A self-referential `data` reference would throw on stringify — degrade
+        // to a string representation rather than crashing the search.
+        dataText = t.data === undefined ? '{}' : String(t.data)
+      }
+      const hay = [String(t.type ?? ''), String(t.round ?? ''), dataText].join(' ').toLowerCase()
       if (hay.indexOf(q) < 0) return false
     }
     return true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "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",
@@ -29,9 +29,11 @@
     },
     "compatibility": {
       "dshReleases": {
+        "0.1.1-rc.1": "compatible",
         "0.1.2-alpha.4": "compatible",
         "0.1.2-alpha.5": "compatible",
-        "0.1.2-rc.1": "compatible"
+        "0.1.2-rc.1": "compatible",
+        "0.1.3-alpha.1": "compatible"
       }
     },
     "client": {

package/src/atomic-fs.ts

@@ -0,0 +1,83 @@
+/**
+ * src/atomic-fs.ts — crash-safe file writes for all plugin state.
+ *
+ * Every JSON/YAML artifact the plugin persists (.iterate/*.json,
+ * iterate.config.yaml) is written through here: content goes to a
+ * uniquely-named temp file in the SAME directory as the target (rename is
+ * only atomic within one filesystem), then is `renameSync`ed over the
+ * destination. A crash mid-write can therefore leave a stale temp file
+ * behind, but never a truncated / half-written state file — readers
+ * (which all tolerate missing/corrupt files) see either the previous or
+ * the new content, never a mixture.
+ */
+
+import { dirname, join } from 'node:path'
+import { renameSync, rmSync, writeFileSync } from 'node:fs'
+import { rename, rm, writeFile } from 'node:fs/promises'
+
+/** Best-effort unlink of a leftover temp file (never throws). */
+function cleanupTemp(tmp: string): void {
+  try {
+    rmSync(tmp, { force: true })
+  } catch {
+    /* ignore — temp files follow the prunable `.tmp-<pid>-<rand>` convention */
+  }
+}
+
+/** Best-effort async unlink of a leftover temp file (never throws). */
+async function cleanupTempAsync(tmp: string): Promise<void> {
+  try {
+    await rm(tmp, { force: true })
+  } catch {
+    /* ignore — temp files follow the prunable `.tmp-<pid>-<rand>` convention */
+  }
+}
+
+/**
+ * Unique temp file path for `filePath`, in the same directory, following the
+ * prunable `.<basename>.tmp-<pid>-<random>` convention (see prune.ts
+ * `isPrunableTemp`). The pid+random suffix makes concurrent writers safe.
+ */
+function tempPathFor(filePath: string): string {
+  return join(
+    dirname(filePath),
+    `.${filePath.split('/').pop() ?? 'file'}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`,
+  )
+}
+
+/**
+ * Write `data` to `filePath` atomically (temp file + rename, same dir).
+ * Temp files follow the `<name>.tmp-<pid>-<random>` convention also used by
+ * prune.ts / checkpoint.ts so they are recognizable and prunable.
+ * Throws on failure (callers own error reporting — they map failures to
+ * structured tool results).
+ */
+export function writeTextAtomic(filePath: string, data: string): void {
+  const tmp = tempPathFor(filePath)
+  writeFileSync(tmp, data, 'utf-8')
+  try {
+    renameSync(tmp, filePath)
+  } catch (err) {
+    // Best-effort temp cleanup so a failed write never litters the directory.
+    cleanupTemp(tmp)
+    throw err
+  }
+}
+
+/** Async variant of {@link writeTextAtomic} (same temp naming convention). */
+export async function writeTextAtomicAsync(filePath: string, data: string): Promise<void> {
+  const tmp = tempPathFor(filePath)
+  await writeFile(tmp, data, 'utf-8')
+  try {
+    await rename(tmp, filePath)
+  } catch (err) {
+    // Best-effort temp cleanup so a failed write never litters the directory.
+    await cleanupTempAsync(tmp)
+    throw err
+  }
+}
+
+/** JSON.stringify (2-space indent) + atomic write in one call. */
+export function writeJsonAtomic(filePath: string, value: unknown): void {
+  writeTextAtomic(filePath, JSON.stringify(value, null, 2))
+}

package/src/client/index.ts

@@ -61,7 +61,6 @@ import {
   batchSetVerdict,
   setAllVerdicts,
   buildRoundHistory,
-  buildFindingTrend,
   computeTrendMetrics,
   trendMax,
   buildCompletionSummary,
@@ -1226,7 +1225,10 @@ function TriagePanel(props: SlotProps) {
 
   // v3.0: Command handlers for native action buttons
   const doApproveArchitecturalFix = () => {
-    const cmd = '请调用 `iterate_fix` 批准架构修复（设置 is_architectural: true）'
+    // Architectural findings exceed the atomic threshold, so "approving" one
+    // means telling the model to apply it as a deliberate forced change via
+    // iterate_fix with force:true (is_architectural is not a real parameter).
+    const cmd = '请调用 `iterate_fix`，对本项目剩余架构型 finding 生成修复内容并设置 force: true 应用（架构修复允许超过 atomic 阈值）'
     copyText(cmd).then((ok) => {
       if (ok) {
         setCmdCopied('approve-arch')
@@ -1246,7 +1248,10 @@ function TriagePanel(props: SlotProps) {
   }
 
   const doRollbackToCheckpoint = () => {
-    const cmd = '请调用 `iterate_checkpoint` 回滚到上一个检查点'
+    // iterate_checkpoint has NO rollback operation (save/load/resume/clear
+    // only); reverting applied fixes is done via iterate_rollback by fix id,
+    // so the paste-able instruction must point there instead.
+    const cmd = '请回滚上一轮迭代的修复：调用 `iterate_history` 查看本轮 fix id，再用 `iterate_rollback` 逐个撤销这些修复'
     copyText(cmd).then((ok) => {
       if (ok) {
         setCmdCopied('rollback')
@@ -2267,7 +2272,10 @@ function ObservatoryPanel(props: SlotProps) {
     const sorted = filtered.slice()
     const rows = sorted.map((t, i) => {
       const k = `f7-${i}`
-      const dataText = t.data && typeof t.data === 'object' ? JSON.stringify(t.data) : ''
+      let dataText = ''
+      if (t.data && typeof t.data === 'object') {
+        try { dataText = JSON.stringify(t.data) } catch { dataText = String(t.data) }
+      }
       return React.createElement('div', { key: k, className: 'iterate-obs-row', style: { flexDirection: 'column', alignItems: 'flex-start' } },
         React.createElement('div', { className: 'iterate-obs-bar', style: { width: '100%' } },
           React.createElement('span', { className: 'iterate-obs-chip' }, String(t.type || '?')),

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/git-scope.ts

@@ -23,7 +23,7 @@
 
 import { execFile } from 'node:child_process'
 import { existsSync, statSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, sep } from 'node:path'
 
 /** A resolved changed-only scope result. */
 export interface GitScopeResult {
@@ -113,10 +113,11 @@ export function parseChangedFiles(stdout: string): string[] {
  */
 export function filterExistingFiles(root: string, files: string[]): string[] {
   const out: string[] = []
+  const rootPrefix = root.endsWith(sep) ? root : root + sep
   for (const rel of files) {
     if (rel.startsWith('/') || rel.includes('\0')) continue
     const candidate = join(root, rel)
-    if (!candidate.startsWith(root + '/') && candidate !== root) continue
+    if (!candidate.startsWith(rootPrefix) && candidate !== root) continue
     try {
       if (existsSync(candidate) && statSync(candidate).isFile()) out.push(rel)
     } catch {

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'
@@ -136,9 +137,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

@@ -143,9 +143,20 @@ for (let r = 1; r <= maxRounds; r++) {
   // Feed the DEDUPED + already-filtered set back (not raw findings) so the known
   // list stays bounded and reviewers never see the same issue twice.
   if (agg && agg.report && Array.isArray(agg.report.findings)) known = agg.report.findings
-  if (agg && agg.report && agg.report.convergence && agg.report.convergence.findingsByRound[r-1] === 0) {
-    log('round ' + r + ' found 0 new findings — converged')
-    break
+  // A round counts as "converged" ONLY when the aggregate accepted it
+  // (schema-valid) AND it genuinely found zero NEW findings. If reviewers all
+  // failed or their output stayed schema-invalid after retries, the round is
+  // INCONCLUSIVE — never report an empty-but-broken round as converged (an
+  // invalid/failed round must fail the run, not masquerade as a clean pass).
+  if (!schemaInvalid) {
+    const newCount =
+      agg && agg.report && agg.report.convergence
+        ? agg.report.convergence.findingsByRound[r - 1]
+        : thisRound.findings.length
+    if (newCount === 0) {
+      log('round ' + r + ' found 0 new findings — converged')
+      break
+    }
   }
 }
 
@@ -238,7 +249,7 @@ if (checkpoint) {
 
 phase('plan')
 const configRes = await agent(
-  'Call iterate_config({ validate: true }) and return the config JSON.',
+  'Call iterate_config({}) and return the config JSON.',
   Object.assign({ label: 'config:read' }, backend)
 )
 const cfg = (configRes && configRes.config) ? configRes.config : null
@@ -421,7 +432,7 @@ for (let r = startRound; r <= maxRounds; r++) {
     Object.assign({ label: 'checkpoint:save:r' + r }, backend)
   )
 
-  if (atomic.length === 0 && remaining.length === 0) {
+  if (atomic.length === 0 && remaining.length === 0 && !schemaInvalid) {
     log('round ' + r + ' found nothing to fix — converged')
     converged = true
     break

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.',

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

@@ -72,6 +72,9 @@ 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"). ' +