iterate-plugin 2.10.0 → 2.12.0

package/src/tools/fix.ts

@@ -17,8 +17,8 @@
  *   - Atomicity is enforced against `config.atomic.max_lines` unless `force`.
  */
 
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { join, sep } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { loadEffectiveConfig, resolveProjectRootForExec } from '../config-loader.ts'
@@ -123,6 +123,11 @@ 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),
+    )
     return parsed
   } catch {
     return emptyRegistry()
@@ -198,11 +203,56 @@ export function resolveProjectFile(projectRoot: string, file: string): { ok: tru
   if (resolved === projectRoot || !resolved.startsWith(projectRoot + '/') && !resolved.startsWith(projectRoot + '\\')) {
     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)) {
+    let rootReal: string
+    let real: string
+    try {
+      rootReal = realpathSync(projectRoot)
+      real = realpathSync(resolved)
+    } catch {
+      return { ok: false, reason: 'failed to resolve real path for containment check' }
+    }
+    const rootPrefix = rootReal.endsWith(sep) ? rootReal : rootReal + sep
+    if (real !== rootReal && !real.startsWith(rootPrefix)) {
+      return { ok: false, reason: 'file resolves outside the project root (symlink escape)' }
+    }
+  }
   return { ok: true, resolved }
 }
 
 // ─── Shared execute helpers ──────────────────────────────────────────────────
 
+/**
+ * Minimal glob matcher for personalization.protected_paths.
+ * Supports `*` (any run of chars within one segment) and `**` (any chars,
+ * including separators). All other characters are literal. Pure, unit-testable.
+ */
+export function globMatch(path: string, pattern: string): boolean {
+  if (typeof path !== 'string' || typeof pattern !== 'string') return false
+  // Escape regex specials except our two wildcards.
+  let re = ''
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i] as string
+    if (ch === '*') {
+      const isDouble = pattern[i + 1] === '*'
+      if (isDouble) { re += '[\\s\\S]*'; i++ } else { re += '[^/\\\\]*' }
+    } else if ('.[]{}()+-^$|?'.includes(ch)) {
+      re += '\\' + ch
+    } else {
+      re += ch
+    }
+  }
+  try {
+    return new RegExp('^' + re + '$').test(path)
+  } catch {
+    return false
+  }
+}
+
 /** Read the current content of a file under the project root. */
 function readProjectFile(projectRoot: string, file: string): { ok: true; content: string } | { ok: false; reason: string } {
   const resolved = resolveProjectFile(projectRoot, file)
@@ -314,6 +364,28 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         if (typeof finding.dimension !== 'string' || finding.dimension.trim().length === 0) {
           return { ok: false, error: 'finding.dimension must be a non-empty string' }
         }
+        // The finding must reference the file being fixed — the fix id and the
+        // rollback/diff target are derived from finding.file, so a mismatch
+        // would back up/restore the WRONG file.
+        if (finding.file !== file) {
+          return { ok: false, error: `finding.file ("${finding.file}") must match the file being fixed ("${file}")` }
+        }
+        // Full finding validation, mirroring the review schema: malformed
+        // findings would produce lossy registry/log entries and a degraded id.
+        const SEVERITY_SET = new Set(['critical', 'high', 'medium', 'low'])
+        if (!SEVERITY_SET.has(finding.severity)) {
+          return { ok: false, error: 'finding.severity must be one of critical/high/medium/low' }
+        }
+        if (typeof finding.summary !== 'string' || finding.summary.trim().length === 0) {
+          return { ok: false, error: 'finding.summary must be a non-empty string' }
+        }
+        if (typeof finding.is_atomic !== 'boolean') {
+          return { ok: false, error: 'finding.is_atomic must be a boolean' }
+        }
+        if (finding.line !== undefined && finding.line !== null &&
+            (typeof finding.line !== 'number' || !Number.isInteger(finding.line) || finding.line < 0)) {
+          return { ok: false, error: 'finding.line must be a non-negative integer (0 = whole-file)' }
+        }
 
         const current = readProjectFile(projectRoot, file)
         if (!current.ok) return { ok: false, error: current.reason }
@@ -346,6 +418,30 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         const target = resolveProjectFile(projectRoot, file)
         if (!target.ok) return { ok: false, error: target.reason }
 
+        // Personalization guards (SKILL.md Phase 2): protected_paths veto the
+        // fix outright; forbidden_fixes veto fix approaches appearing in the
+        // new content. Both are security-relevant, so they are enforced here
+        // in the tool, not left to the model.
+        const pers = config.personalization as
+          | { protected_paths?: unknown; forbidden_fixes?: unknown }
+          | undefined
+        const protectedPaths = Array.isArray(pers?.protected_paths)
+          ? (pers.protected_paths as unknown[]).filter((p): p is string => typeof p === 'string' && p.length > 0)
+          : []
+        for (const pattern of protectedPaths) {
+          if (globMatch(file, pattern)) {
+            return { ok: false, error: `skipped: ${file} matches protected path "${pattern}" (personalization.protected_paths forbids modifying it)` }
+          }
+        }
+        const forbiddenFixes = Array.isArray(pers?.forbidden_fixes)
+          ? (pers.forbidden_fixes as unknown[]).filter((f): f is string => typeof f === 'string' && f.length > 0)
+          : []
+        for (const forbidden of forbiddenFixes) {
+          if (args.content.includes(forbidden)) {
+            return { ok: false, error: `fix uses a forbidden approach: "${forbidden}" appears in the new content (personalization.forbidden_fixes)` }
+          }
+        }
+
         const timestamp = new Date().toISOString()
         const backupPath = fixBackupPath(projectRoot, id, timestamp)
         try {
@@ -376,7 +472,19 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         try {
           writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(nextRegistry, null, 2), 'utf-8')
         } catch (err) {
-          return { ok: false, error: `failed to write fix registry: ${String(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
+          // back up the already-fixed content as "original". Restore the file
+          // from the backup to leave the tree exactly as it was.
+          try {
+            copyFileSync(backupPath, target.resolved)
+          } catch (restoreErr) {
+            return {
+              ok: false,
+              error: `failed to write fix registry: ${String(err)}; additionally failed to restore ${file} from backup: ${String(restoreErr)}`,
+            }
+          }
+          return { ok: false, error: `failed to write fix registry: ${String(err)} (file restored from backup)` }
         }
 
         appendDecisionEntry(projectRoot, {
@@ -485,6 +593,9 @@ export function registerDiffTool(ctx: { tools: { register: (def: ReturnType<type
             if (existing) {
               existing.linesAdded += r.linesAdded
               existing.linesRemoved += r.linesRemoved
+              // 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,

package/src/tools/prune.ts

@@ -18,7 +18,7 @@
  *   - Each deletion is logged to the decision log (when not dry-run).
  */
 
-import { existsSync, readdirSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
+import { existsSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
@@ -134,17 +134,17 @@ export function executePrune(
     errors: [] as string[],
   }
 
-  // 1. Rewrite the decision log, keeping only recent entries.
+  // 1. Rewrite the decision log, keeping only recent entries. Atomic
+  // (temp + rename) so a crash mid-write can never truncate the log.
   try {
     const entries = readDecisionEntries(projectRoot)
     const kept = entries.filter((e) => e.timestamp >= cutoff)
     result.deletedLogEntries = entries.length - kept.length
     if (result.deletedLogEntries > 0) {
-      writeFileSync(
-        join(iterateDir(projectRoot), 'decision-log.jsonl'),
-        kept.map((e) => JSON.stringify(e)).join('\n') + '\n',
-        'utf-8',
-      )
+      const logPath = join(iterateDir(projectRoot), 'decision-log.jsonl')
+      const tmpPath = `${logPath}.tmp-${Date.now()}`
+      writeFileSync(tmpPath, kept.map((e) => JSON.stringify(e)).join('\n') + '\n', 'utf-8')
+      renameSync(tmpPath, logPath)
     }
   } catch (err) {
     result.errors.push(`failed to rewrite decision log: ${String(err)}`)
@@ -175,10 +175,13 @@ export function executePrune(
   if (report.emptyRounds.length > 0) {
     try {
       let registry = readRegistry(projectRoot)
-      for (const round of report.emptyRounds) {
-        for (const rec of [...registry.rounds.find((r) => r.round === round)?.records ?? []]) {
-          registry = removeRecord(registry, rec.id)
-        }
+      const emptyRoundNos = new Set(report.emptyRounds)
+      // Drop whole empty rounds (records.length === 0) instead of only
+      // removing their records — an empty round has no records to remove, so
+      // the old loop was a no-op that still reported trimmedEmptyRounds.
+      registry = {
+        ...registry,
+        rounds: registry.rounds.filter((r) => !emptyRoundNos.has(r.round) || (r.records?.length ?? 0) > 0),
       }
       registry = recomputeRoundCounts(registry)
       writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(registry, null, 2), 'utf-8')

package/src/tools/review.ts

@@ -170,9 +170,12 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
           const rawRounds = Array.isArray(args.rounds) ? args.rounds : []
           const rounds: ReviewRound[] = rawRounds
             .map((r) => {
-              const rr = r as { round?: number; findings?: unknown }
+              const rr = r as { round?: number; findings?: unknown; readFiles?: unknown }
               const findings = Array.isArray(rr?.findings) ? (rr.findings as ReviewFinding[]) : []
-              return { round: typeof rr?.round === 'number' ? rr.round : 0, findings }
+              const readFiles = Array.isArray(rr?.readFiles)
+                ? (rr.readFiles as unknown[]).filter((f): f is string => typeof f === 'string')
+                : []
+              return { round: typeof rr?.round === 'number' ? rr.round : 0, findings, readFiles }
             })
             .filter((r: ReviewRound) => r.round > 0)
 

package/src/tools/transcript.ts

@@ -0,0 +1,334 @@
+/**
+ * src/tools/transcript.ts — `iterate_transcript` tool.
+ *
+ * Exposes the runtime-observatory manifest to the model (and, via its persisted
+ * on-disk copy, to the client observatory panel). Purely local, deterministic,
+ * and safe:
+ *
+ *   - `read`     — return the persisted transcript manifest (or a structured
+ *                  "not found" empty view). Used each round by the workflow to
+ *                  pick up steering nudges, and polled by tool-reading agents.
+ *   - `capture`  — build a fresh transcript from the review `rounds` + `report`
+ *                  and persist it. Called by the canonical scripts after the
+ *                  final aggregate so the client always sees the latest run.
+ *   - `nudge`    — set (`text`) or clear (`text: null`) steering text persisted
+ *                  for the next round's reviewers to read.
+ *
+ * All writes are persisted to `.iterate/transcript.json` via an atomic
+ * tmp+rename so a crashed writer never leaves a corrupt manifest.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import {
+  loadEffectiveConfig,
+  resolveProjectRootForExec,
+} from '../config-loader.ts'
+import { transcriptPath } from '../paths.ts'
+import { ReviewTranscriptBuilder } from '../transcript.ts'
+import { readLive } from '../live.ts'
+import type {
+  TranscriptManifest,
+  TranscriptFix,
+} from '../types.ts'
+
+/** Build per-dimension threads for one round from its (dimension-tagged) findings. */
+function captureRound(builder: ReviewTranscriptBuilder, round: unknown): void {
+  if (!round || typeof round !== 'object') return
+  const r = round as {
+    round?: unknown
+    findings?: unknown
+    readFiles?: unknown
+  }
+  const roundNo = typeof r.round === 'number' ? Math.floor(r.round) : 0
+  if (roundNo <= 0) return
+  builder.roundStart(roundNo)
+  const findings = Array.isArray(r.findings) ? r.findings : []
+  const readFiles = Array.isArray(r.readFiles) ? r.readFiles : []
+  // Group the round's findings by dimension → one reviewer thread each.
+  const byDim = new Map<string, unknown[]>()
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue
+    const rec = f as Record<string, unknown>
+    const dim = typeof rec.dimension === 'string' && rec.dimension ? rec.dimension : 'review'
+    const list = byDim.get(dim) ?? []
+    list.push(f)
+    byDim.set(dim, list)
+  }
+  if (byDim.size === 0) {
+    builder.reviewerSnapshot('review', [], readFiles)
+  } else {
+    for (const [dim, list] of byDim) builder.reviewerSnapshot(dim, list, readFiles)
+  }
+}
+
+/** Normalize the checkpoint shape if present. */
+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
+  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,
+    updatedAt: typeof c.updatedAt === 'string' ? c.updatedAt : new Date().toISOString(),
+  }
+}
+
+/** Normalize a fix record. */
+function normalizeFix(input: unknown): TranscriptFix | null {
+  if (!input || typeof input !== 'object') return null
+  const f = input as Record<string, unknown>
+  const id = typeof f.id === 'string' ? f.id : ''
+  const file = typeof f.file === 'string' ? f.file : ''
+  if (!id || !file) return null
+  return {
+    id,
+    timestamp: typeof f.timestamp === 'string' ? f.timestamp : new Date().toISOString(),
+    round: typeof f.round === 'number' ? f.round : 0,
+    file,
+    summary: typeof f.summary === 'string' ? f.summary : '',
+    linesAdded: typeof f.linesAdded === 'number' ? f.linesAdded : 0,
+    linesRemoved: typeof f.linesRemoved === 'number' ? f.linesRemoved : 0,
+    success: f.success !== false,
+  }
+}
+
+/** Register the `iterate_transcript` tool. */
+export function registerTranscriptTool(ctx: {
+  tools: { register: (def: ReturnType<typeof defineTool>) => void }
+}): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_transcript',
+      description:
+        'Runtime-observatory transcript for the iterate workflow. ' +
+        '`read` returns the current persisted transcript manifest (per-reviewer threads, ' +
+        'convergence series, findings, fixes, checkpoint, timeline, and any steering nudge ' +
+        'written for the next round). ' +
+        '`capture` builds a fresh transcript from the review `rounds` + `report` and persists it ' +
+        '(call once after the final aggregate so the UI reflects the run). ' +
+        '`nudge` sets (text) or clears (text:null) steering text the next round\'s reviewers read. ' +
+        'Purely local and deterministic — never touches source files.',
+      parameters: {
+        operation: {
+          type: 'string',
+          required: true,
+          description: '"read" to fetch the manifest, "capture" to persist one, "nudge" to set steering text.',
+          enum: ['read', 'capture', 'nudge'],
+        },
+        rounds: {
+          type: 'json',
+          description: 'For `capture`: per-round findings, each [{round, findings:[{dimension,file,line?,severity,summary,…}], readFiles:[…]}].',
+        },
+        report: {
+          type: 'json',
+          description: 'For `capture`: the ReviewReport (convergence.findingsByRound used for the trend).',
+        },
+        mode: {
+          type: 'string',
+          description: 'For `capture`: run mode ("dry-run" | "normal"). Default dry-run.',
+          enum: ['dry-run', 'normal'],
+        },
+        goal: { type: 'string', description: 'For `capture`: run goal.' },
+        maxRounds: { type: 'integer', description: 'For `capture`: round cap.' },
+        roundsExecuted: { type: 'integer', description: 'For `capture`: number of rounds actually executed.' },
+        findingsByRound: { type: 'json', description: 'For `capture`: the per-round new-findings count series (report.convergence.findingsByRound). Preferred over passing the whole report.' },
+        checkpoint: { type: 'json', description: 'For `capture`: checkpoint summary (optional).' },
+        fixes: {
+          type: 'json',
+          description: 'For `capture`: array of applied fixes [{id, file, round, summary, linesAdded, linesRemoved, success}].',
+        },
+        refReadFiles: { type: 'json', description: 'For `capture`: flat array of all read files across rounds (optional).' },
+        text: { type: 'string', description: 'For `nudge`: steering text to set (or null to clear).' },
+        path: { type: 'string', description: 'Project root directory (default: current working directory).' },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            operation: { type: 'string', required: true },
+            found: { type: 'boolean' },
+            transcript: { type: 'json' },
+            live: { type: 'json', description: 'Recent live reviewer-activity entries (newest first).' },
+            updated: { type: 'boolean' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+      },
+
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
+        if (!resolved.ok) return { operation: args.operation, error: resolved.reason }
+        const projectRoot = resolved.root
+        const file = transcriptPath(projectRoot)
+        const { config } = loadEffectiveConfig(projectRoot)
+        const approval = config.observatory?.approval ?? 'ask'
+
+        if (args.operation === 'read') {
+          const live = await readLive(projectRoot)
+          if (!existsSync(file)) {
+            return {
+              operation: 'read',
+              found: false,
+              live: live as unknown as JsonValue,
+              transcript: new ReviewTranscriptBuilder({
+                project: projectRoot,
+                approval,
+              }).serialize() as unknown as JsonValue,
+            }
+          }
+          try {
+            const raw = await readFile(file, 'utf-8')
+            const parsed = JSON.parse(raw) as unknown as TranscriptManifest
+            return {
+              operation: 'read',
+              found: true,
+              live: live as unknown as JsonValue,
+              transcript: parsed as unknown as JsonValue,
+            }
+          } catch (err) {
+            return {
+              operation: 'read',
+              found: false,
+              error: `Failed to read transcript: ${err instanceof Error ? err.message : String(err)}`,
+            }
+          }
+        }
+
+        if (args.operation === 'nudge') {
+          let manifest: TranscriptManifest | null = null
+          if (existsSync(file)) {
+            try {
+              const parsed = JSON.parse(await readFile(file, 'utf-8')) as unknown as TranscriptManifest
+              manifest = parsed
+            } catch {
+              manifest = null
+            }
+          }
+          const builder = manifest
+            ? rehydrateBuilder(manifest, approval)
+            : new ReviewTranscriptBuilder({ project: projectRoot, mode: 'normal', approval })
+          builder.setNudge(typeof args.text === 'string' && args.text.trim() ? args.text : null)
+          await persist(file, builder.serialize())
+          return {
+            operation: 'nudge',
+            updated: true,
+            transcript: builder.serialize() as unknown as JsonValue,
+          }
+        }
+
+        // capture
+        const mode = args.mode === 'normal' ? 'normal' : 'dry-run'
+        const goal = typeof args.goal === 'string' ? args.goal : ''
+        const maxRounds =
+          typeof args.maxRounds === 'number' ? Math.floor(args.maxRounds) : 0
+        const builder = new ReviewTranscriptBuilder({ project: projectRoot, mode, approval, goal, maxRounds })
+        const report = args.report as Record<string, unknown> | null | undefined
+        const reportFindings: unknown =
+          report && typeof report === 'object' && Array.isArray(report.findings)
+            ? report.findings
+            : []
+        const convergence =
+          Array.isArray(args.findingsByRound) ? (args.findingsByRound as number[])
+          : report && typeof report === 'object' && report.convergence
+            ? ((report.convergence as Record<string, unknown>).findingsByRound as number[] | undefined) ?? []
+            : []
+
+        const rounds = Array.isArray(args.rounds) ? (args.rounds as unknown[]) : []
+        for (const r of rounds) captureRound(builder, r)
+        if (rounds.length === 0) {
+          // No pre-grouped rounds: fall back to the report's flattened findings.
+          const readFiles = Array.isArray(args.refReadFiles) ? args.refReadFiles : []
+          const byDim = new Map<string, unknown[]>()
+          for (const f of reportFindings as unknown[]) {
+            if (!f || typeof f !== 'object') continue
+            const rec = f as Record<string, unknown>
+            const dim = typeof rec.dimension === 'string' && rec.dimension ? rec.dimension : 'review'
+            const list = byDim.get(dim) ?? []
+            list.push(f)
+            byDim.set(dim, list)
+          }
+          for (const [dim, list] of byDim) builder.reviewerSnapshot(dim, list, readFiles)
+        }
+
+        // Convergence series from the report (position per round).
+        for (let i = 0; i < convergence.length; i += 1) {
+          const n = convergence[i]
+          if (typeof n === 'number') builder.snapshotConvergence(i + 1, n)
+        }
+        const roundsExecuted =
+          typeof args.roundsExecuted === 'number' ? Math.floor(args.roundsExecuted) : rounds.length
+        if (roundsExecuted > 0) builder.roundStart(roundsExecuted, maxRounds)
+
+        builder.recordCheckpoint(normalizeCheckpoint(args.checkpoint))
+        if (Array.isArray(args.fixes)) {
+          for (const fx of args.fixes) {
+            const record = normalizeFix(fx)
+            if (record) builder.fix(record)
+          }
+        }
+        // Convergence "found nothing → settled" marker when the trend ends on 0.
+        const last = convergence[convergence.length - 1]
+        if (convergence.length > 0 && last === 0) builder.finish()
+
+        await persist(file, builder.serialize())
+        const live = await readLive(projectRoot)
+        return {
+          operation: 'capture',
+          found: true,
+          updated: true,
+          live: live as unknown as JsonValue,
+          transcript: builder.serialize() as unknown as JsonValue,
+        }
+      },
+    }),
+  )
+}
+
+/** Rebuild a builder from a persisted manifest so nudge edits preserve history. */
+function rehydrateBuilder(manifest: TranscriptManifest, approval: 'ask' | 'deny' | 'allow'): ReviewTranscriptBuilder {
+  const builder = new ReviewTranscriptBuilder({
+    project: manifest.project,
+    mode: manifest.mode ?? null,
+    approval,
+    goal: manifest.goal,
+    maxRounds: manifest.maxRounds,
+  })
+  for (const r of Array.isArray(manifest.rounds) ? manifest.rounds : []) {
+    builder.roundStart(r.round, manifest.maxRounds)
+    for (const t of Array.isArray(r.threads) ? r.threads : []) {
+      builder.reviewerStart(t.dimension || 'review', t.attempt || 1)
+      builder.reviewerMessage((t.messages ?? []).join('\n'))
+      builder.reviewerRead(t.readFiles ?? [])
+      for (const f of t.findings ?? []) builder.reviewerFindings([f])
+    }
+  }
+  for (let idx = 0; idx < (manifest.convergence ?? []).length; idx += 1) {
+    const n = manifest.convergence[idx]
+    if (typeof n === 'number' && n >= 0) builder.snapshotConvergence(idx + 1, n)
+  }
+  if (manifest.checkpoint) builder.recordCheckpoint(manifest.checkpoint)
+  if (Array.isArray(manifest.fixes)) for (const fx of manifest.fixes) builder.fix(fx as TranscriptFix)
+  if (Array.isArray(manifest.timeline)) for (const e of manifest.timeline) builder.decision(e)
+  builder.setNudge(manifest.nudge?.text ?? null)
+  if (!manifest.active) builder.finish()
+  return builder
+}
+
+/** Atomically persist a manifest (tmp + rename) under `.iterate/`. */
+async function persist(file: string, manifest: TranscriptManifest): Promise<void> {
+  await mkdir(dirname(file), { recursive: true })
+  const tmp = `${file}.tmp`
+  await writeFile(tmp, JSON.stringify(manifest, null, 2), 'utf-8')
+  await rename(tmp, file)
+}

package/src/tools/triage.ts

@@ -1,4 +1,4 @@
-import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
@@ -231,16 +231,19 @@ function applyEntries(
   try {
     writeFileSync(configPath, yamlText, 'utf-8')
   } catch (err) {
-    // Rollback: restore the backup (or delete the file we just created).
+    // Rollback: restore the backup, or REMOVE the file we just created when
+    // there was no prior config — an empty file left behind would poison all
+    // future config reads (empty YAML is not a valid mapping).
+    let rollbackError = ''
     try {
       if (backupPath) copyFileSync(backupPath, configPath)
-      else if (existsSync(configPath)) writeFileSync(configPath, '', 'utf-8')
-    } catch {
-      // Rollback failure is reported, not swallowed silently.
+      else if (existsSync(configPath)) rmSync(configPath, { force: true })
+    } catch (rbErr) {
+      rollbackError = `; rollback also failed: ${String(rbErr)}`
     }
     return {
       ok: false,
-      error: `Failed to write config: ${String(err)}`,
+      error: `Failed to write config: ${String(err)}${rollbackError}`,
     }
   }
 

package/src/tools/validate.ts

@@ -46,10 +46,13 @@ async function runCommand(
       },
       (error, stdout, stderr) => {
         const durationMs = Math.round(performance.now() - start)
-        // error.code is the exit code when the command ran; error.killed means timeout
+        // error.code is the exit code when the command ran; when the binary
+        // cannot be spawned Node sets error.code to a STRING ('ENOENT' etc).
+        // Coerce to a number so the integer output schema is never violated.
+        const exitCode = typeof error?.code === 'number' ? error.code : (error ? 1 : 0)
         resolve({
           command,
-          exitCode: error?.code ?? (error ? 1 : 0),
+          exitCode,
           stdout: stdout ?? '',
           stderr: stderr ?? '',
           timedOut: error?.killed === true,