iterate-plugin 2.10.0 → 2.12.0

package/src/review.ts

@@ -44,9 +44,11 @@ export function sortFindings(findings: ReviewFinding[]): ReviewFinding[] {
     const rankB = SEVERITY_RANK[b.severity] ?? SEVERITY_RANK.low
     const bySeverity = rankA - rankB
     if (bySeverity !== 0) return bySeverity
-    const byFile = a.file.localeCompare(b.file)
+    // Defensive coercion: `file`/`line` can be wrong-typed when schema
+    // validation is disabled — String()/Number() keep the comparator total.
+    const byFile = String(a.file ?? '').localeCompare(String(b.file ?? ''))
     if (byFile !== 0) return byFile
-    return (a.line ?? 0) - (b.line ?? 0)
+    return (Number(a.line) || 0) - (Number(b.line) || 0)
   })
 }
 
@@ -58,9 +60,15 @@ export function normalizeSummary(summary: string): string {
     .replace(/[\s\n\t]+/g, ' ')
 }
 
-/** Dedupe key: same file + same dimension + similar summary. */
+/**
+ * Dedupe key: same file + same dimension + similar summary + explicit line.
+ * Including the line keeps two genuine issues with identical wording at
+ * different locations from collapsing into one (the line is omitted only when
+ * neither side anchors one, i.e. whole-file findings).
+ */
 export function findingKey(f: ReviewFinding): string {
-  return `${f.file}|${f.dimension}|${normalizeSummary(f.summary)}`
+  const line = typeof f.line === 'number' && f.line > 0 ? f.line : 0
+  return `${f.file}|${f.dimension}|${line}|${normalizeSummary(f.summary)}`
 }
 
 /**
@@ -129,12 +137,19 @@ export function aggregateRounds(
   const merged: ReviewFinding[] = []
 
   // Guard: round numbers are expected to be positive integers. Skip malformed
-  // entries defensively rather than letting `firstRoundByKey` key on NaN/0.
+  // entries defensively rather than letting `firstRoundByKey` key on NaN/0 or
+  // crashing on null / non-array findings.
+  // Hard ceiling: round numbers are model-authored JSON; an absurd round (e.g.
+  // 1e9) would otherwise allocate an array of that size below (OOM). Round
+  // numbers above the configured cap are clamped to the cap.
   let maxRound = 0
+  const roundCap = Math.max(1, maxReviewRounds)
   for (const round of rounds) {
+    if (!round || typeof round !== 'object') continue
     if (typeof round.round !== 'number' || !Number.isInteger(round.round) || round.round < 1) continue
+    const findings = Array.isArray(round.findings) ? round.findings : []
     if (round.round > maxRound) maxRound = round.round
-    for (const f of round.findings) {
+    for (const f of findings) {
       const key = findingKey(f)
       if (seen.has(key)) continue
       seen.add(key)
@@ -142,9 +157,11 @@ export function aggregateRounds(
       merged.push(f)
     }
   }
+  // Clamp the allocation bound so a hostile round number cannot OOM the tool.
+  const effectiveMax = Math.min(maxRound, Math.max(1, roundCap * 2))
 
   const findingsByRound: number[] = []
-  for (let r = 1; r <= maxRound; r++) {
+  for (let r = 1; r <= effectiveMax; r++) {
     let count = 0
     for (const key of firstRoundByKey.keys()) {
       if (firstRoundByKey.get(key) === r) count++
@@ -165,12 +182,18 @@ export function computeConvergence(
   const { findingsByRound } = aggregateRounds(rounds, maxReviewRounds)
   const totalRounds = rounds.length
   // `findingsByRound` is indexed by the actual round number (round r → index
-  // r-1), so convergence must read the LAST PRESENT round's count using its
-  // reported round number — not `totalRounds - 1`, which is only valid for
-  // contiguous 1..N round numbers.
-  const lastRound = totalRounds > 0 ? rounds[totalRounds - 1]!.round : 0
-  const lastRoundCount =
-    lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0
+  // r-1), sized to the highest present round (clamped). Convergence must read
+  // the HIGHEST PRESENT round's count — not the last array element (rounds
+  // may arrive unsorted) and not `totalRounds - 1` (only valid for contiguous
+  // 1..N). The count index is bounded by the array length aggregateRounds
+  // actually allocated.
+  let lastRound = 0
+  for (const round of rounds) {
+    if (!round || typeof round.round !== 'number' || !Number.isInteger(round.round) || round.round < 1) continue
+    if (round.round > lastRound) lastRound = round.round
+  }
+  const idx = Math.min(lastRound, findingsByRound.length) - 1
+  const lastRoundCount = idx >= 0 ? (findingsByRound[idx] ?? 0) : 0
   const converged = totalRounds > 0 && lastRoundCount === 0
   return {
     totalRounds,
@@ -224,8 +247,12 @@ export function buildReviewReport(input: {
 }): ReviewReport {
   // 1. Filter known-intentional per round (before cross-round dedupe).
   const filteredRounds = input.rounds.map((r) => ({
-    round: r.round,
-    findings: filterKnownIntentional(r.findings, input.knownIntentional),
+    round: typeof r?.round === 'number' ? r.round : 0,
+    findings: filterKnownIntentional(
+      Array.isArray(r?.findings) ? r.findings : [],
+      input.knownIntentional,
+    ),
+    readFiles: Array.isArray(r?.readFiles) ? r.readFiles : [],
   }))
 
   // 2. Cross-round dedupe + per-round "first seen" tracking.
@@ -262,6 +289,9 @@ export function buildReviewReport(input: {
     maxReviewRounds: input.maxReviewRounds,
     rounds: filteredRounds,
     findings: sorted,
+    // Aggregate of every round's self-reported reads, so the meta-review
+    // coverage gate can compare against the assigned inventory.
+    readFiles: ([] as string[]).concat(...filteredRounds.map((r) => r.readFiles ?? [])),
     convergence: {
       totalRounds: filteredRounds.length,
       findingsByRound,
@@ -470,8 +500,8 @@ export interface RoundSchemaValidation {
  */
 export function validateRoundsSchema(rounds: ReviewRound[]): RoundSchemaValidation[] {
   return rounds.map((r) => {
-    const issues = validateFindingsSchema(r.findings)
-    return { round: r.round, valid: issues.length === 0, issues }
+    const issues = validateFindingsSchema(Array.isArray(r?.findings) ? r.findings : [])
+    return { round: typeof r?.round === 'number' ? r.round : 0, valid: issues.length === 0, issues }
   })
 }
 
@@ -491,21 +521,27 @@ export function sanitizeRounds(
   schemaValidation: RoundSchemaValidation[] | null,
 ): ReviewRound[] {
   return rounds.map((r, i) => {
+    // Defensive: malformed rounds must never crash the deterministic core.
+    const findings = Array.isArray(r?.findings) ? r.findings : []
+    const roundNo = typeof r?.round === 'number' ? r.round : 0
+    const readFiles = Array.isArray(r?.readFiles) ? r.readFiles : []
     if (schemaValidation) {
       const issues = schemaValidation[i]?.issues ?? []
-      if (issues.some((iss) => iss.index === -1)) return { round: r.round, findings: [] }
+      if (issues.some((iss) => iss.index === -1)) return { round: roundNo, findings: [], readFiles }
       const bad = new Set(issues.map((iss) => iss.index))
       return {
-        round: r.round,
-        findings: r.findings.filter((_, fi) => !bad.has(fi)),
+        round: roundNo,
+        findings: findings.filter((_, fi) => !bad.has(fi)),
+        readFiles,
       }
     }
     return {
-      round: r.round,
-      findings: r.findings.filter(
+      round: roundNo,
+      findings: findings.filter(
         (f): f is ReviewFinding =>
           Boolean(f) && typeof f === 'object' && !Array.isArray(f),
       ),
+      readFiles,
     }
   })
 }
@@ -539,6 +575,12 @@ export function reviewerTaskPrompt(input: {
    * `changedFiles`.
    */
   scopeFiles?: string[]
+  /**
+   * Per-dimension focus guidance (from personalization.dimension_focus, or the
+   * skill's dimension definitions). Appended to the reviewer prompt so the
+   * review concentrates on the areas the user cares about.
+   */
+  focus?: string
 }): string {
   const parts: string[] = []
   parts.push(
@@ -546,6 +588,9 @@ export function reviewerTaskPrompt(input: {
     `Goal: ${input.goal}`,
     `Scope: ${input.scope === 'full' ? 'entire codebase' : 'changed files only'}.`,
   )
+  if (input.focus) {
+    parts.push(`FOCUS: ${input.focus}`)
+  }
   if (input.scopeFiles && input.scopeFiles.length > 0) {
     parts.push(
       'COVERAGE RULE (mandatory): below is the exact file inventory you are ' +
@@ -592,9 +637,9 @@ export function reviewerTaskPrompt(input: {
   parts.push(
     `Return a JSON object: {"findings": [...], "readFiles": [...]}.`,
     `Each finding: dimension (must be "${input.dimension}"), file (relative path), ` +
-      'line (REQUIRED positive integer — the exact line you READ for an ' +
-      'anchored, line-targeted issue; use 0 for whole-file/module-level ' +
-      'issues), severity (critical/high/medium/low), summary (one line), ' +
+      'line (optional; the exact line you READ for a line-targeted issue; ' +
+      '0 or omitted for whole-file/module-level issues), ' +
+      'severity (critical/high/medium/low), summary (one line), ' +
       'failure_scenario (how/when it fails, backed by the code you actually ' +
       'read), suggested_fix (the concrete fix), ' +
       `is_atomic (true if the fix is <= ${input.maxLines} lines within a SINGLE file/function, else false).`,
@@ -672,6 +717,17 @@ export function buildReviewPlan(input: {
     reviewerPrompt: string
     findingsSchema: Record<string, unknown>
   }[] = []
+  // personalization.dimension_focus: [{dimension, focus}] — appended to the
+  // matching dimension's reviewer prompt.
+  const focusMap = new Map<string, string>()
+  const pf = input.config.personalization as { dimension_focus?: { dimension?: string; focus?: string }[] } | undefined
+  if (pf && Array.isArray(pf.dimension_focus)) {
+    for (const entry of pf.dimension_focus) {
+      if (entry && typeof entry.dimension === 'string' && typeof entry.focus === 'string' && entry.focus) {
+        focusMap.set(entry.dimension, entry.focus)
+      }
+    }
+  }
   for (const d of dimensions) {
     batches.forEach((batch, index) => {
       const dimensionId = batches.length === 1 ? d : `${d}#${index + 1}`
@@ -687,6 +743,7 @@ export function buildReviewPlan(input: {
           maxLines,
           changedFiles: effectiveChangedOnly ? changedFiles : undefined,
           scopeFiles: batch,
+          focus: focusMap.get(d),
         }),
         findingsSchema: findingsSchema(),
       })

package/src/session-hooks.ts

@@ -0,0 +1,90 @@
+/**
+ * src/session-hooks.ts — dsh pipeline hooks for the iterate observatory (F8).
+ *
+ * Wires the {@link decideApproval} policy gate to dsh's `tools/pre-execute`
+ * waterfall. This is the AUTHORITATIVE approval seam for destructive iterate
+ * tools (`iterate_fix` / `iterate_rollback` / `iterate_prune` with dryRun:false):
+ *
+ *   - `allow` policy      → the call runs.
+ *   - `deny`  policy      → the call is refused (fail-closed), surfaced as an
+ *                           error to the model.
+ *   - `ask`   policy      → return `{ kind: 'ask', reason }`; dsh's own
+ *                           scheduler routes it through the `approval` service
+ *                           (see `@deepseek-ai/dsh-user-approval`), which
+ *                           prompts the human and audits an approve/deny pair
+ *                           on the session.
+ *
+ * We deliberately do NOT also add `approved` flags inside the tool bodies:
+ * the pre-execute waterfall consumes the human decision before the tool runs,
+ * so a second tool-internal gate would double-ask. This one gate is enough and
+ * stays dsh-native.
+ *
+ * Safety properties:
+ *   - Read-only tools and non-iterate tools are always allowed (the gate only
+ *     inspects the three destructive iterate toolnames).
+ *   - If the project root / observatory config cannot be resolved, the policy
+ *     degrades to `ask` (fail-safe: destructive writes always require consent).
+ */
+
+import { loadEffectiveConfig, resolveProjectRoot } from './config-loader.ts'
+import { decideApproval, isDestructiveIterateTool } from './approval-gate.ts'
+import type { Context } from '@deepseek-ai/cordis'
+import type { ToolExecution, PreToolDecision } from '@deepseek-ai/dsh-tools'
+
+/**
+ * Build the per-call approval decision for a tool execution.
+ * Returns a dsh `PreToolDecision` so the caller can short-circuit the caller.
+ */
+export function gateDecision(exec: ToolExecution): PreToolDecision {
+  // Importing the decision, and only inspecting our own tools, keeps unrelated
+  // tooling untouched. Anything we cannot classify is allowed by default.
+  if (!isDestructiveIterateTool(exec.name)) return { kind: 'allow' }
+
+  // Resolve the project root (use the call's own `path` arg, else the agent's
+  // session cwd) to read the effective observatory policy.
+  const argPath = typeof exec.arguments === 'object' && exec.arguments && !Array.isArray(exec.arguments)
+    && typeof (exec.arguments as Record<string, unknown>).path === 'string'
+    ? (exec.arguments as Record<string, unknown>).path as string
+    : undefined
+  const sessionCwd = exec.agent?.session?.header?.cwd
+  const resolved = resolveProjectRoot(argPath, sessionCwd)
+  let policy: 'ask' | 'deny' | 'allow' = 'ask'
+  if (resolved.ok) {
+    const { config } = loadEffectiveConfig(resolved.root)
+    const p = config.observatory?.approval
+    if (p === 'deny') policy = 'deny'
+    else if (p === 'allow') policy = 'allow'
+    // anything else (including a corrupt/missing `ask`) → 'ask'
+  }
+
+  const decision = decideApproval(exec, policy)
+  if (decision.kind === 'deny') return { kind: 'deny', reason: decision.reason }
+  if (decision.kind === 'ask') return { kind: 'ask', reason: decision.reason }
+  return { kind: 'allow' }
+}
+
+/**
+ * Register the `tools/pre-execute` waterfall listener that applies the
+ * observatory approval gate to every destructive iterate tool call.
+ */
+export function registerSessionHooks(ctx: Context): void {
+  ctx.on('tools/pre-execute', (exec: ToolExecution, next: () => Promise<PreToolDecision>) => {
+    // Never let a throwing gate break the pipeline — degrade to allow.
+    let decision: PreToolDecision
+    try {
+      decision = gateDecision(exec)
+    } catch {
+      return next()
+    }
+    if (decision.kind === 'ask') {
+      // Delegate the actual human-consent prompt + audit to dsh's approval
+      // service via the scheduler's `ask` path. `next()` here would short-circuit
+      // to allow, which would bypass consent — so return our ask decision.
+      return Promise.resolve(decision)
+    }
+    if (decision.kind === 'deny') {
+      return Promise.resolve(decision)
+    }
+    return next()
+  })
+}

package/src/skill-prompt.ts

@@ -23,6 +23,7 @@ You have the iterate plugin installed, which registers these tools:
 - \`iterate_status\` — summarize the current run: mode, round, fixes applied, architectural remaining, decision-log size, checkpoint presence, and whether the run was interrupted (a checkpoint left on disk means the previous run was interrupted and can be resumed)
 - \`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.
 
 ### When to use
 When the user asks to review or iterate on the project (e.g. "review this project", "iterate on error handling", "check the codebase for issues", "dry-run review", "反复审查"), run an iterate **workflow** by calling the \`workflow\` tool.
@@ -78,6 +79,14 @@ const knownIntentional = (plan.knownIntentional || [])   // config personalizati
 let known = []              // cumulative DEDUPED findings fed back to reviewers
 const rounds = []           // raw per-round findings
 
+phase('transcript')
+// Read any steering nudge written (via iterate_transcript nudge) for this run's reviewers.
+const transRead = await agent(
+  'Call iterate_transcript({operation:"read"}) and return {nudge:<transcript.nudge ? transcript.nudge.text : null>}.',
+  Object.assign({ label: 'transcript:read' }, backend)
+)
+const steering = transRead && typeof transRead.nudge === 'string' && transRead.nudge ? transRead.nudge : null
+
 phase('review')
 for (let r = 1; r <= maxRounds; r++) {
   log('round ' + r + ' of ' + maxRounds + ' — finding NEW issues only')
@@ -89,14 +98,29 @@ for (let r = 1; r <= maxRounds; r++) {
     const nudge = retries > 0
       ? '\\nSTRICT JSON REQUIRED: your previous output failed schema validation. Return ONLY a JSON object {"findings":[...]} where EVERY finding has dimension, file, line (non-negative integer; 0 = whole-file), severity (critical|high|medium|low), summary, failure_scenario, suggested_fix, is_atomic (boolean).'
       : ''
-    const raw = await parallel(dims.map(dim => () => agent(
-      'Review dimension "' + dim + '".' +
-      (attachments.length > 0 ? ' User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
-      ' Already-known findings (do NOT re-report): ' +
-      JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.',
-      Object.assign({ label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }, backend)
-    )))
-    const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
+    const raw = await parallel(dims.map(dim => () => {
+      // Pass the plan's full per-dimension reviewerPrompt (goal, COVERAGE RULE
+      // with the assigned file inventory, EVIDENCE RULE, output language) and
+      // append the round-specific context — the reviewers must receive the
+      // file inventory or the coverage machinery has nothing to enforce.
+      const meta = plan.dimensions.find(x => x.id === dim)
+      const base = (meta && typeof meta.reviewerPrompt === 'string' && meta.reviewerPrompt)
+        ? meta.reviewerPrompt
+        : 'Review dimension "' + dim + '".'
+      const extra =
+        (steering ? '\\n STEERING — read this first: ' + steering : '') +
+        (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
+        '\\n Already-known findings (do NOT re-report): ' +
+        JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.'
+      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
+    }))
+    const thisRound = {
+      round: r,
+      findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])),
+      // readFiles are threaded through so the aggregate/meta-review coverage
+      // gate can compare self-reported reads against the assigned inventory.
+      readFiles: [].concat(...raw.map(x => x && Array.isArray(x.readFiles) ? x.readFiles : [])),
+    }
     if (rounds.length >= r) rounds[r - 1] = thisRound; else rounds.push(thisRound)
     // Deterministic aggregate: cross-round dedupe + known_intentional filter + severity sort.
     agg = await agent(
@@ -143,6 +167,13 @@ const metaRes = await agent(
 const finalReport = metaRes && metaRes.finalReport ? metaRes.finalReport : null
 const metaAudit = finalReport && finalReport.metaReview ? finalReport.metaReview : null
 
+// Persist the run's observatory transcript (reviewer threads, trend, findings)
+// so the client observatory panel reflects this review. Writes ONLY .iterate/transcript.json.
+await agent(
+  'Call iterate_transcript({operation:"capture", mode:"dry-run", goal:' + JSON.stringify(report.goal) + ', maxRounds:' + maxRounds + ', roundsExecuted:' + report.convergence.totalRounds + ', findingsByRound:' + JSON.stringify(report.convergence.findingsByRound || []) + ', rounds:' + JSON.stringify(rounds.map(rr => ({ round: rr.round, findings: rr.findings, readFiles: rr.readFiles }))) + '}). Return {operation:"ok"}.',
+  Object.assign({ label: 'transcript:capture' }, backend)
+)
+
 return {
   mode: 'dry-run',
   goal: report.goal,
@@ -167,7 +198,7 @@ Key rules for dry-run:
 - Stop when a round reports 0 new findings (converged) or maxReviewRounds is reached.
 - The report (with per-round convergence stats + suggested fix priorities) is the deliverable.
 - **Meta-review**: after building the report, audit it with \`iterate_review({operation:"meta-review"})\` for internal consistency (counts, severity buckets, dimension sums, sort order, convergence math). The meta-review ALSO runs the hard code-evidence gate (default on): every finding's file/line is validated against real files on disk, so any fabricated location surfaces as a critical \`EVIDENCE_VIOLATION\` and flips the verdict to \`needs_revision\`. The \`finalReport.verdict\` is \`approved\` only when the report passes every check AND every finding anchors to real, read code; otherwise \`needs_revision\`. Surface the final report and its verdict as the closing deliverable.
-- Only a single \`report\` entry may be appended to the decision log; nothing else is written.
+- Only a single \`report\` entry may be appended to the decision log; nothing else is written to source files. The final \`iterate_transcript capture\` writes ONLY the observatory file (\`.iterate/transcript.json\`) so the client panel reflects the run — it is not a source-code write.
 
 ### Normal-mode workflow (autonomous closed loop)
 Set \`args.mode = "normal"\`. Loop: resume → plan → parallel review ×N → atomic fixes via \`iterate_fix\` → validate → rollback on failure → checkpoint → loop → auto-stop when zero findings remain.
@@ -225,10 +256,23 @@ let fixedCount = (checkpoint && typeof checkpoint.fixedCount === 'number') ? che
 let converged = false
 let abortedByValidation = false
 let failedCommands = []
+const fixRecords = []        // observatory fix records collected round by round
+
+// Read any steering nudge intended for this run's reviewers.
+const transRead = await agent(
+  'Call iterate_transcript({operation:"read"}) and return {nudge:<transcript.nudge ? transcript.nudge.text : null>}.',
+  Object.assign({ label: 'transcript:read' }, backend)
+)
+const steering = transRead && typeof transRead.nudge === 'string' && transRead.nudge ? transRead.nudge : null
 
 phase('loop')
 for (let r = startRound; r <= maxRounds; r++) {
   log('round ' + r + ' of ' + maxRounds + ' — review current state, fix atomics via iterate_fix, validate')
+  // Audit-trail: record the round start (SKILL.md Phase 4 requires per-round records).
+  await agent(
+    'Call iterate_decision_log({operation:"append", type:"round_start", round:' + r + ', data:{maxRounds:' + maxRounds + ', fixedSoFar:' + fixedCount + '}})',
+    Object.assign({ label: 'log:start:r' + r }, backend)
+  )
   let agg = null
   let schemaInvalid = false
   let retries = 0
@@ -237,13 +281,25 @@ for (let r = startRound; r <= maxRounds; r++) {
     const nudge = retries > 0
       ? '\\nSTRICT JSON REQUIRED: your previous output failed schema validation. Return ONLY a JSON object {"findings":[...]} where EVERY finding has dimension, file, line (non-negative integer; 0 = whole-file), severity (critical|high|medium|low), summary, failure_scenario, suggested_fix, is_atomic (boolean).'
       : ''
-    const raw = await parallel(dims.map(dim => () => agent(
-      'Review dimension "' + dim + '" on the CURRENT code state (previous atomic findings are fixed). ' +
-      (attachments.length > 0 ? ' User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
-      'Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.',
-      Object.assign({ label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }, backend)
-    )))
-    const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
+    const raw = await parallel(dims.map(dim => () => {
+      // Pass the plan's full per-dimension reviewerPrompt (COVERAGE RULE with
+      // the assigned file inventory, EVIDENCE RULE, output language) plus the
+      // round-specific context.
+      const meta = plan.dimensions.find(x => x.id === dim)
+      const base = (meta && typeof meta.reviewerPrompt === 'string' && meta.reviewerPrompt)
+        ? meta.reviewerPrompt
+        : 'Review dimension "' + dim + '" on the CURRENT code state (previous atomic findings are fixed).'
+      const extra =
+        (steering ? '\\n STEERING — read this first: ' + steering : '') +
+        (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
+        '\\n Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.'
+      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
+    }))
+    const thisRound = {
+      round: r,
+      findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])),
+      readFiles: [].concat(...raw.map(x => x && Array.isArray(x.readFiles) ? x.readFiles : [])),
+    }
     if (rounds.length >= r) rounds[r - 1] = thisRound; else rounds.push(thisRound)
 
     // Deterministic dedupe / known_intentional filter / severity sort for this round.
@@ -279,12 +335,14 @@ for (let r = startRound; r <= maxRounds; r++) {
       'Apply the fixes for ' + file + ' using iterate_fix. For EACH finding in this list, ' +
       'read the current file, compute the edited full content (change <= ' + atomicMaxLines + ' lines), and call ' +
       'iterate_fix({ file: "' + file + '", content: <full new file content>, finding: <that finding>, round: ' + r + ' }). ' +
-      'Apply the findings IN ORDER. After all fixes, call iterate_diff({ file: "' + file + '" }) to verify the accumulated diff. ' +
-      'Findings: ' + JSON.stringify(byFile[file]) + '. Return the array of {id, ok, error} per iterate_fix call.',
+      'Apply the findings IN ORDER. After all fixes, call iterate_diff({ file: "' + file + '" }) to verify the accumulated diff and ' +
+      'read its line statistics (lines added/removed). ' +
+      'Findings: ' + JSON.stringify(byFile[file]) + '. Return the array of {id, ok, error, file, linesAdded, linesRemoved} per iterate_fix call ' +
+      '(id/ok required; put the file-wide line stats from iterate_diff on each record, or on the last record and 0 elsewhere).',
       Object.assign({ label: 'fix:' + file, phase: 'fix', schema: {
         type: 'object', additionalProperties: false,
         properties: {
-          fixes: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { id: { type: 'string' }, ok: { type: 'boolean' }, error: { type: 'string' } }, required: ['id', 'ok'] } }
+          fixes: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { id: { type: 'string' }, ok: { type: 'boolean' }, error: { type: 'string' }, file: { type: 'string' }, linesAdded: { type: 'integer' }, linesRemoved: { type: 'integer' } }, required: ['id', 'ok'] } }
         },
         required: ['fixes'] } }, backend)
     )))
@@ -292,6 +350,17 @@ for (let r = startRound; r <= maxRounds; r++) {
       if (res && Array.isArray(res.fixes)) {
         for (const fx of res.fixes) {
           if (fx && fx.ok === true) { fixedCount += 1; roundFixIds.push(fx.id) }
+          // Collect fix records for the observatory transcript (defensive defaults).
+          const fixFileKeys = Object.keys(byFile)
+          fixRecords.push({
+            id: fx && typeof fx.id === 'string' ? fx.id : '',
+            file: fx && typeof fx.file === 'string' ? fx.file : (fixFileKeys.length === 1 ? fixFileKeys[0] : ''),
+            round: r,
+            summary: '',
+            linesAdded: fx && typeof fx.linesAdded === 'number' ? fx.linesAdded : 0,
+            linesRemoved: fx && typeof fx.linesRemoved === 'number' ? fx.linesRemoved : 0,
+            success: !!(fx && fx.ok === true),
+          })
         }
       }
     }
@@ -374,6 +443,19 @@ if (!abortedByValidation) {
     { label: 'checkpoint:clear' }
   )
 }
+// Persist the run's observatory transcript (threads, trend, fixes, checkpoint)
+// so the client observatory panel reflects the run. Writes ONLY .iterate/transcript.json.
+const obsCheckpoint = abortedByValidation ? null : {
+  mode: 'normal',
+  round: rounds.length,
+  maxRounds: maxRounds,
+  fixedCount: fixedCount,
+  resumeCount: effectiveResumeCount,
+}
+await agent(
+  'Call iterate_transcript({operation:"capture", mode:"normal", goal:' + JSON.stringify(plan.goal) + ', maxRounds:' + maxRounds + ', roundsExecuted:' + rounds.length + ', findingsByRound:' + JSON.stringify(rounds.map(rr => (rr.findings && rr.findings.length) ? rr.findings.length : 0)) + ', fixes:' + JSON.stringify(fixRecords) + ', checkpoint:' + JSON.stringify(obsCheckpoint) + ', rounds:' + JSON.stringify(rounds.map(rr => ({ round: rr.round, findings: rr.findings, readFiles: rr.readFiles }))) + '}). Return {operation:"ok"}.',
+  { label: 'transcript:capture' }
+)
 return {
   mode: 'normal',
   goal: plan.goal,

package/src/tools/checkpoint.ts

@@ -9,7 +9,7 @@
  * Checkpoint layout: `.iterate/checkpoint.json`.
  */
 
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { resolveProjectRootForExec } from '../config-loader.ts'
@@ -107,7 +107,9 @@ export function computeStatus(input: {
     totalRounds,
     fixedCount,
     architecturalCount,
-    findingsCount: checkpoint?.findings.length ?? 0,
+    // A checkpoint may predate the `findings` field (or be hand-edited) — a
+    // missing findings must degrade to 0, never throw.
+    findingsCount: Array.isArray(checkpoint?.findings) ? checkpoint.findings.length : 0,
     totalDecisionLogEntries: entries.length,
     hasCheckpoint: checkpoint !== null,
     // A checkpoint left on disk means the previous run was interrupted before
@@ -209,7 +211,12 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
           }
           try {
             mkdirSync(iterateDir(projectRoot), { recursive: true })
-            writeFileSync(checkpointPath(projectRoot), JSON.stringify(checkpoint, null, 2), 'utf-8')
+            // 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)
           } catch (err) {
             return { operation: 'save', ok: false, error: `failed to write checkpoint: ${String(err)}` }
           }

package/src/tools/context.ts

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync } from 'node:fs'
+import { readFileSync, existsSync, statSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { defineTool } from '@deepseek-ai/dsh-tools'
@@ -263,7 +263,8 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
           return { found: false, error: resolved.reason, searched: [] }
         }
         const projectRoot = resolved.root
-        const requested = (args.files ?? '')
+        // Guard: `files` must be a comma-separated string (model-controlled).
+        const requested = (typeof args.files === 'string' ? args.files : '')
           .split(',')
           .map((s) => s.trim().toLowerCase())
           .filter(Boolean)
@@ -295,7 +296,17 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
           // are all supported.
           const skillRoot = findSkillRoot(PLUGIN_SRC_DIR)
           const candidates: string[] = []
-          if (args.skillDir) candidates.push(args.skillDir)
+          // skillDir is a model-controlled path; only honor it when it is an
+          // existing directory (resolve it first) — otherwise fall through to
+          // the auto-detected root / project root.
+          if (typeof args.skillDir === 'string' && args.skillDir.trim()) {
+            try {
+              const dir = resolve(args.skillDir)
+              if (existsSync(dir) && statSync(dir).isDirectory()) candidates.push(dir)
+            } catch {
+              // unreadable/invalid skillDir — skip it
+            }
+          }
           if (skillRoot) candidates.push(skillRoot)
           candidates.push(projectRoot)
           result.searched = candidates

package/src/tools/decision-log.ts

@@ -52,12 +52,19 @@ function logPath(projectRoot: string): string {
 
 /**
  * Append one entry to the decision log (JSONL format).
- * Returns the entry count after appending.
+ * Returns the entry count after appending. Never throws — a disk failure is
+ * surfaced through `error` so callers (fix/prune) can report the audit-trail
+ * miss without failing the mutation they already performed.
  */
-export function appendDecisionEntry(projectRoot: string, entry: DecisionLogEntry): { count: number; path: string } {
-  const filePath = logPath(projectRoot)
-  const line = JSON.stringify(entry) + '\n'
-  appendFileSync(filePath, line, 'utf-8')
+export function appendDecisionEntry(projectRoot: string, entry: DecisionLogEntry): { count: number; path: string; error?: string } {
+  let filePath: string
+  try {
+    filePath = logPath(projectRoot)
+    const line = JSON.stringify(entry) + '\n'
+    appendFileSync(filePath, line, 'utf-8')
+  } catch (err) {
+    return { count: -1, path: join(projectRoot, LOG_DIR, LOG_FILE), error: `failed to append decision log: ${String(err)}` }
+  }
   // Count entries
   let count = 0
   try {
@@ -71,19 +78,29 @@ export function appendDecisionEntry(projectRoot: string, entry: DecisionLogEntry
 
 /**
  * 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[] {
   const filePath = join(projectRoot, LOG_DIR, LOG_FILE)
   if (!existsSync(filePath)) return []
+  let content: string
   try {
-    const content = readFileSync(filePath, 'utf-8')
-    return content
-      .split('\n')
-      .filter((l) => l.trim().length > 0)
-      .map((l) => JSON.parse(l) as DecisionLogEntry)
+    content = readFileSync(filePath, 'utf-8')
   } catch {
     return []
   }
+  const out: DecisionLogEntry[] = []
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed.length === 0) continue
+    try {
+      out.push(JSON.parse(trimmed) as DecisionLogEntry)
+    } catch {
+      // skip the corrupt line, keep the rest
+    }
+  }
+  return out
 }
 
 /**