iterate-plugin 3.5.2 → 3.5.3

package/src/tools/defense-events.ts

@@ -12,7 +12,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec, loadEffectiveConfig } from '../config-loader.ts'
-import { readDefenseEvents, writeDefenseEvents, addDefenseEvent } from './defense-store.ts'
+import { readDefenseEvents, writeDefenseEvents, addDefenseEvent, clearDefenseEvents } from './defense-store.ts'
 import type { DefenseEvent, DefenseEventType } from '../types.ts'
 
 const DEFAULT_LIMIT = 50
@@ -95,16 +95,18 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
       // join a parallel dispatch group.
       isConcurrencySafe: (args) => (args as { operation?: unknown }).operation !== 'record',
       description:
-        'Query or record defense events: precondition failures, rollbacks, invariant violations, ' +
+        'Query, record, or clear defense events: precondition failures, rollbacks, invariant violations, ' +
         'and assumption falsifications. ' +
         'List/counts return events with descriptions, outcomes, and summary counts; ' +
-        '"record" persists a new event to .iterate/defense-events.json. ' +
+        '"record" persists a new event to .iterate/defense-events.json; ' +
+        '"clear" resets the persisted event stream (use it to start a fresh iteration without stale ' +
+        'defense data). ' +
         'Use it to review defensive actions taken, or to log one when a defense fires.',
       parameters: {
         operation: {
           type: 'string',
-          description: 'Operation: list (browse all), counts (summary by type), record (log a new event). Default: list.',
-          enum: ['list', 'counts', 'record'],
+          description: 'Operation: list (browse all), counts (summary by type), record (log a new event), clear (reset the stream). Default: list.',
+          enum: ['list', 'counts', 'record', 'clear'],
         },
         type: {
           type: 'string',
@@ -162,6 +164,7 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
             kind: { type: 'string' },
             operation: { type: 'string' },
             count: { type: 'integer' },
+            counted: { type: 'boolean', description: 'clear only: true when a persisted stream was removed.' },
             events: { type: 'json' },
             counts: { type: 'json' },
             event: { type: 'json' },
@@ -174,6 +177,17 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
           if (!value.ok) return [{ type: 'text', text: `defense events query failed: ${value.error}` }]
           const language: 'zh' | 'en' = value.language === 'zh' ? 'zh' : 'en'
 
+          if (value.operation === 'clear') {
+            // Fresh stream: counts are all zero and the event list is empty.
+            return [{ type: 'text', text: [
+              value.counted === true
+                ? 'Defense event stream cleared — a fresh iteration starts with an empty stream.'
+                : 'No persisted defense event stream to clear.',
+              'Defense Event Summary:',
+              ...EVENT_TYPES.map((type) => `  ${labelFor(type, language)}: 0`),
+            ].join('\n') }]
+          }
+
           if (value.operation === 'counts' && value.counts) {
             const counts = value.counts as Record<DefenseEventType, number>
             const lines = [
@@ -220,12 +234,35 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
         if (!resolved.ok) return { ok: false, kind: 'defense_events', error: resolved.reason }
         const projectRoot = resolved.root
 
-        const configLang = loadEffectiveConfig(projectRoot).config.language
+        // A hand-edited `language` value outside zh/en must not leak out of the
+        // declared 'zh' | 'en' enum (labelFor would return undefined for it) —
+        // normalize any non-'zh' config value to 'en'.
+        const rawConfigLang = loadEffectiveConfig(projectRoot).config.language
+        const configLang: 'zh' | 'en' = rawConfigLang === 'zh' ? 'zh' : 'en'
         const language: 'zh' | 'en' = args.language === 'zh' || args.language === 'en' ? args.language : configLang
 
         const operation = typeof args.operation === 'string' ? args.operation : 'list'
         const limit = clampLimit(args.limit as number | undefined)
 
+        if (operation === 'clear') {
+          // Reset the persisted event stream so a fresh iteration does not carry
+          // stale defensive data (mirrors iterate_quality_gate clear / clearQualityGate).
+          const result = clearDefenseEvents(projectRoot)
+          if (!result.ok) {
+            return { ok: false, kind: 'defense_events', operation: 'clear', error: result.error }
+          }
+          const empty = readDefenseEvents(projectRoot)
+          return {
+            ok: true,
+            kind: 'defense_events',
+            operation: 'clear',
+            counted: result.existed,
+            language,
+            counts: empty.counts as unknown as JsonValue,
+            events: empty.events as unknown as JsonValue,
+          }
+        }
+
         if (operation === 'record') {
           const errors = validateRecordInput(args)
           if (errors.length > 0) {

package/src/tools/defense-store.ts

@@ -46,11 +46,41 @@ function emptyStream(): DefenseEventStream {
   }
 }
 
+/** Valid severity values (kept in sync with DefenseEvent). */
+const VALID_SEVERITIES: ReadonlySet<string> = new Set(['critical', 'high', 'medium', 'low'])
+
+/**
+ * Normalize one persisted event. Hand-edited files can carry events missing
+ * `timestamp`/`round`/`description`/`defense`/`outcome`/`severity` — readers
+ * (list sort by timestamp, render label selection) must never crash or emit
+ * NaN for those. Returns null when the entry is not an object or has no usable
+ * `type`; otherwise fills every required field with a safe default.
+ */
+function normalizeEvent(raw: unknown): DefenseEvent | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const e = raw as Record<string, unknown>
+  if (typeof e.type !== 'string' || !VALID_EVENT_TYPES.has(e.type as DefenseEventType)) return null
+  return {
+    id: typeof e.id === 'string' && e.id ? e.id : `def-${Math.random().toString(36).slice(2, 8)}`,
+    timestamp: typeof e.timestamp === 'string' && e.timestamp ? e.timestamp : new Date().toISOString(),
+    round: typeof e.round === 'number' && Number.isFinite(e.round) ? Math.floor(e.round) : 0,
+    type: e.type as DefenseEventType,
+    description: typeof e.description === 'string' ? e.description : '',
+    defense: typeof e.defense === 'string' ? e.defense : '',
+    outcome: typeof e.outcome === 'string' ? e.outcome : '',
+    ...(typeof e.file === 'string' && e.file.length > 0 ? { file: e.file } : {}),
+    ...(typeof e.line === 'number' && Number.isFinite(e.line) && e.line >= 0 ? { line: e.line } : {}),
+    severity: VALID_SEVERITIES.has(String(e.severity)) ? (e.severity as DefenseEvent['severity']) : 'low',
+  }
+}
+
 /**
  * Read the defense events stream from disk.
  * Normalizes the persisted stream so a hand-edited / partial file can never
  * produce NaN counts: `counts` is recomputed from the events when missing or
- * malformed, and every type key is guaranteed present.
+ * malformed, every type key is guaranteed present, and every surviving event is
+ * shape-normalized so consumers (timestamp sort, render label selection) cannot
+ * throw on missing fields.
  */
 export function readDefenseEvents(projectRoot: string): DefenseEventStream {
   const filePath = path.join(projectRoot, '.iterate', DEFENSE_EVENTS_FILE)
@@ -58,10 +88,9 @@ export function readDefenseEvents(projectRoot: string): DefenseEventStream {
     const content = fs.readFileSync(filePath, 'utf-8')
     const parsed = JSON.parse(content) as Partial<DefenseEventStream>
     if (parsed && Array.isArray(parsed.events)) {
-      const events = parsed.events.filter(
-        (e): e is DefenseEvent =>
-          !!e && typeof e === 'object' && typeof (e as DefenseEvent).type === 'string',
-      )
+      const events = parsed.events
+        .map(normalizeEvent)
+        .filter((e): e is DefenseEvent => e !== null)
       const counts = computeCounts(events)
       return {
         events,
@@ -101,6 +130,26 @@ export function writeDefenseEvents(
   return { ok: true }
 }
 
+/**
+ * Clear the persisted defense-event stream (`.iterate/defense-events.json`).
+ * Mirrors `clearQualityGate` in quality-store.ts: a stale event stream from a
+ * previous iteration must be resettable before a fresh run. Returns whether a
+ * file existed and was removed, or a structured error when removal fails.
+ */
+export function clearDefenseEvents(
+  projectRoot: string,
+): { ok: true; existed: boolean } | { ok: false; error: string } {
+  const filePath = path.join(iterateDir(projectRoot), DEFENSE_EVENTS_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 }
+}
+
 /** Add a defense event to the stream. */
 export function addDefenseEvent(
   stream: DefenseEventStream,

package/src/tools/experience-bank.ts

@@ -151,8 +151,8 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
               `Dimension: ${entry.dimension}`,
               `Description: ${entry.description}`,
               `Fix: ${entry.verifiedFix}`,
-              `Files: ${entry.files.join(', ')}`,
-              `Tags: ${entry.tags.join(', ')}`,
+              `Files: ${Array.isArray(entry.files) ? entry.files.join(', ') : ''}`,
+              `Tags: ${Array.isArray(entry.tags) ? entry.tags.join(', ') : ''}`,
             ].join('\n') }]
           }
           if (value.operation === 'remove') {
@@ -165,9 +165,9 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
               `Pattern: ${entry.pattern}`,
               `Description: ${entry.description}`,
               `Fix: ${entry.verifiedFix}`,
-              `Files: ${entry.files.join(', ')}`,
+              `Files: ${Array.isArray(entry.files) ? entry.files.join(', ') : ''}`,
               `Hits: ${entry.hitCount}`,
-              `Tags: ${entry.tags.join(', ')}`,
+              `Tags: ${Array.isArray(entry.tags) ? entry.tags.join(', ') : ''}`,
             ].join('\n') }]
           }
           const entries = (value.entries as unknown as ExperienceEntry[] | undefined) ?? []
@@ -264,7 +264,7 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
             operation: 'get',
             count: 1,
             entry: entry as unknown as JsonValue,
-            totalHits: bank.totalHits,
+            totalHits: bank.totalHits ?? 0,
           }
         }
 
@@ -280,7 +280,7 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
             operation: 'search',
             count: entries.length,
             entries: entries as unknown as JsonValue,
-            totalHits: bank.totalHits,
+            totalHits: bank.totalHits ?? 0,
           }
         }
 
@@ -290,7 +290,7 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
           entries = entries.filter((e) => e.dimension === args.dimension)
         }
         if (Array.isArray(args.tags) && args.tags.length > 0) {
-          entries = entries.filter((e) => args.tags!.every((t: string) => e.tags.includes(t)))
+          entries = entries.filter((e) => args.tags!.every((t: string) => Array.isArray(e.tags) && e.tags.includes(t)))
         }
 
         return {
@@ -299,7 +299,7 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
           operation: 'list',
           count: Math.min(entries.length, limit),
           entries: entries.slice(0, limit) as unknown as JsonValue,
-          totalHits: bank.totalHits,
+          totalHits: bank.totalHits ?? 0,
         }
       },
     }),

package/src/tools/experience-store.ts

@@ -22,14 +22,62 @@ function emptyBank(): ExperienceBank {
   }
 }
 
+/** Valid severity values (kept in sync with ExperienceEntry). */
+const VALID_SEVERITIES: ReadonlySet<string> = new Set(['critical', 'high', 'medium', 'low'])
+
+/** String array guard for fields that must be arrays (`files`, `tags`). */
+function stringArray(v: unknown): string[] {
+  if (!Array.isArray(v)) return []
+  return v.filter((x): x is string => typeof x === 'string')
+}
+
+/**
+ * Normalize one persisted experience entry. A hand-edited bank entry can be
+ * missing `files`/`tags` arrays (or `hitCount`) — consumers rendering/searching
+ * entries (`render` `.join(', ')`, `searchExperienceEntries` spread) must never
+ * throw or emit NaN. Returns null for non-object entries; every required field
+ * gets a safe default.
+ */
+function normalizeEntry(raw: unknown): ExperienceEntry | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const e = raw as Record<string, unknown>
+  const pattern = typeof e.pattern === 'string' ? e.pattern : ''
+  const dimension = typeof e.dimension === 'string' ? e.dimension : ''
+  const id = typeof e.id === 'string' && e.id ? e.id : `exp-${Math.random().toString(36).slice(2, 8)}`
+  if (!pattern && !dimension) return null
+  const hitCount = typeof e.hitCount === 'number' && Number.isFinite(e.hitCount) ? e.hitCount : 0
+  return {
+    id,
+    timestamp: typeof e.timestamp === 'string' ? e.timestamp : new Date().toISOString(),
+    dimension,
+    pattern,
+    description: typeof e.description === 'string' ? e.description : '',
+    verifiedFix: typeof e.verifiedFix === 'string' ? e.verifiedFix : '',
+    findingSummary: typeof e.findingSummary === 'string' ? e.findingSummary : '',
+    files: stringArray(e.files),
+    hitCount,
+    ...(typeof e.lastHitAt === 'string' ? { lastHitAt: e.lastHitAt } : {}),
+    tags: stringArray(e.tags),
+    severity: VALID_SEVERITIES.has(String(e.severity)) ? (e.severity as ExperienceEntry['severity']) : 'low',
+  }
+}
+
 /** Read the experience bank from disk. Returns empty bank if not found. */
 export function readExperienceBank(projectRoot: string): ExperienceBank {
   const filePath = path.join(projectRoot, '.iterate', EXPERIENCE_FILE)
   try {
     const content = fs.readFileSync(filePath, 'utf-8')
-    const parsed = JSON.parse(content) as ExperienceBank
+    const parsed = JSON.parse(content) as Partial<ExperienceBank>
     if (parsed && Array.isArray(parsed.entries)) {
-      return parsed
+      const entries = parsed.entries
+        .map(normalizeEntry)
+        .filter((e): e is ExperienceEntry => e !== null)
+      return {
+        entries,
+        lastUpdated: typeof parsed.lastUpdated === 'string' ? parsed.lastUpdated : emptyBank().lastUpdated,
+        totalHits:
+          typeof parsed.totalHits === 'number' && Number.isFinite(parsed.totalHits) ? parsed.totalHits : 0,
+      }
     }
   } catch {
     // File not found or invalid JSON
@@ -72,6 +120,9 @@ export function searchExperienceEntries(
   const lowerQuery = query.toLowerCase()
 
   return entries.filter((entry) => {
+    if (!entry || typeof entry !== 'object') return false
+    const rawEntry = entry as unknown as Record<string, unknown>
+    const tags = stringArray(rawEntry.tags)
     // Dimension filter
     if (opts.dimension && entry.dimension !== opts.dimension) {
       return false
@@ -79,22 +130,24 @@ export function searchExperienceEntries(
 
     // Tags filter (AND logic)
     if (opts.tags && opts.tags.length > 0) {
-      if (!opts.tags.every((t) => entry.tags.includes(t))) {
+      if (!opts.tags.every((t) => tags.includes(t))) {
         return false
       }
     }
 
-    // Text search across multiple fields
-    if (query) {
-      const searchableText = [
-        entry.pattern,
-        entry.description,
-        entry.verifiedFix,
-        entry.findingSummary,
-        entry.dimension,
-        ...entry.files,
-        ...entry.tags,
-      ].join(' ').toLowerCase()
+    // Text search across multiple fields. Guards against a hand-edited bank entry
+  // whose `files`/`tags` are missing or non-array (the spread below would
+  // otherwise throw a TypeError on a non-iterable).
+  if (query) {
+    const searchableText = [
+      entry.pattern,
+      entry.description,
+      entry.verifiedFix,
+      entry.findingSummary,
+      entry.dimension,
+      ...stringArray(entry.files),
+      ...stringArray(entry.tags),
+    ].join(' ').toLowerCase()
 
       if (!searchableText.includes(lowerQuery)) {
         return false

package/src/tools/fix.ts

@@ -126,11 +126,25 @@ export function readRegistry(projectRoot: string): FixRegistry {
   try {
     const parsed = JSON.parse(readFileSync(file, 'utf-8')) as FixRegistry
     if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.rounds)) return emptyRegistry()
-    // Defensive: a hand-edited or partially-written registry may contain a
-    // round without a `records` array — normalize instead of crashing readers.
-    parsed.rounds = parsed.rounds.filter(
-      (r) => r && typeof r === 'object' && Array.isArray(r.records),
-    )
+    // Defensive normalization: a hand-edited or partially-written registry may
+    // contain a round without a `records` array, or records that are missing
+    // their id / finding object — all of which would make readers
+    // (findFixRecord / recordsForFile / iterate_diff) throw or sum NaN.
+    parsed.rounds = parsed.rounds
+      .filter((r) => r && typeof r === 'object' && Array.isArray(r.records))
+      .map((r) => ({
+        ...r,
+        round: typeof r.round === 'number' && Number.isFinite(r.round) ? Math.floor(r.round) : 0,
+        records: r.records.filter(
+          (rec): rec is FixRecord =>
+            !!rec &&
+            typeof rec === 'object' &&
+            typeof rec.id === 'string' &&
+            !!rec.finding &&
+            typeof rec.finding === 'object',
+        ),
+      }))
+      .filter((r) => typeof r.round === 'number' && Number.isFinite(r.round))
     return parsed
   } catch {
     return emptyRegistry()
@@ -621,19 +635,25 @@ export function registerDiffTool(ctx: { tools: { register: (def: ReturnType<type
         for (const round of registry.rounds) {
           for (const r of round.records) {
             if (!r.success) continue
-            const existing = files.find((f) => f.file === r.finding.file)
+            const file = typeof r.finding.file === 'string' ? r.finding.file : ''
+            if (!file) continue
+            // Coerce defensively: a hand-edited registry record missing the
+            // numeric fields must not produce NaN in the accumulated summary.
+            const added = Number(r.linesAdded) || 0
+            const removed = Number(r.linesRemoved) || 0
+            const existing = files.find((f) => f.file === file)
             if (existing) {
-              existing.linesAdded += r.linesAdded
-              existing.linesRemoved += r.linesRemoved
+              existing.linesAdded += added
+              existing.linesRemoved += removed
               // Recompute the summary from the summed counts so a multi-fix
               // file's text does not contradict its accumulated numbers.
               existing.diffSummary = `+${existing.linesAdded}/-${existing.linesRemoved} lines`
             } else {
               files.push({
-                file: r.finding.file,
-                diffSummary: r.diffSummary,
-                linesAdded: r.linesAdded,
-                linesRemoved: r.linesRemoved,
+                file,
+                diffSummary: typeof r.diffSummary === 'string' ? r.diffSummary : `+${added}/-${removed} lines`,
+                linesAdded: added,
+                linesRemoved: removed,
               })
             }
           }

package/src/tools/history.ts

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

package/src/tools/prune.ts

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

package/src/tools/quality-gate.ts

@@ -13,6 +13,9 @@ import { resolveProjectRootForExec } from '../config-loader.ts'
 import { readQualityGate, writeQualityGate, computeQualityGate, clearQualityGate } from './quality-store.ts'
 import type { QualityGateSnapshot } from '../types.ts'
 
+/** Valid severity values (kept in sync with QualityGateSnapshot counting). */
+const VALID_SEVERITIES: ReadonlySet<string> = new Set(['critical', 'high', 'medium', 'low'])
+
 /** Validate a single finding object; returns true when well-formed. */
 function isValidFinding(raw: unknown): raw is { dimension: string; severity: string; file: string; line?: number } {
   if (!raw || typeof raw !== 'object') return false
@@ -20,6 +23,7 @@ function isValidFinding(raw: unknown): raw is { dimension: string; severity: str
   return (
     typeof f.dimension === 'string' &&
     typeof f.severity === 'string' &&
+    VALID_SEVERITIES.has(f.severity) &&
     typeof f.file === 'string' &&
     (f.line === undefined || typeof f.line === 'number')
   )

package/src/tools/quality-store.ts

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

package/src/tools/transcript.ts

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