iterate-plugin 3.5.6 → 3.6.0

package/src/meta-review.ts

@@ -15,9 +15,9 @@
  */
 
 import type { ReviewFinding, ReviewReport } from './types.ts'
-import type { EvidenceAudit } from './evidence.ts'
+import type { EvidenceAudit, FindingEvidence } from './evidence.ts'
 import type { CoverageResult } from './review-scope.ts'
-import { sortFindings } from './review.ts'
+import { isValidRoundNumber, sortFindings } from './review.ts'
 
 /** A single defect found while auditing a review report. */
 export interface MetaReviewIssue {
@@ -84,6 +84,56 @@ export const META_REVIEW_CHECKS = 10
  */
 export const COVERAGE_LIST_TRUNCATE = 10
 
+/**
+ * Hard sanity ceiling on a reported round number.
+ *
+ * `rounds[].round` is model/JSON-authored and only needs to be a number to
+ * reach this audit. Round-gap detection enumerates `min..max` of the PRESENT
+ * round numbers, so an absurd value (rounds `{1, 1e15}` or a round of
+ * `Infinity`) used to turn a linear check into an effectively-infinite loop —
+ * a trivial CPU/memory denial of service (and one ROUND_GAP issue per missing
+ * round). Anything above this ceiling is rejected as an invalid round
+ * (ROUND_NUMBER) and excluded from gap enumeration instead of being walked.
+ * Generously above any real run: `config.max_rounds` is capped at 100.
+ */
+export const MAX_REVIEW_ROUND_NUMBER = 1000
+
+/**
+ * Max individual ROUND_GAP issues emitted per audit. The remainder is folded
+ * into a single "+N more" issue so a wide-but-legal gap can never flood the
+ * issue list (each issue carries a detail string).
+ */
+export const MAX_ROUND_GAP_REPORTS = 50
+
+/**
+ * Hard bound on the round-gap enumeration span. Below
+ * MAX_REVIEW_ROUND_NUMBER on purpose: even a legal range (e.g. round 1 plus
+ * round 1000) is too wide for per-number gap reporting to mean anything, so
+ * it collapses to ONE "range too wide" issue instead of ~1000 iterations and
+ * ~1000 issues. Together with the round-number ceiling this makes the
+ * enumeration O(MAX_ROUND_GAP_SPAN) no matter what reaches it.
+ */
+export const MAX_ROUND_GAP_SPAN = 500
+
+/** Bounded, non-throwing list preview for issue detail strings. */
+function previewList(values: readonly unknown[], max = 20): string {
+  const shown = values
+    .slice(0, max)
+    .map((v) => (typeof v === 'number' ? String(v) : typeof v === 'string' ? v : '[object]'))
+    .join(', ')
+  return values.length > max ? `${shown}, … (+${values.length - max} more)` : shown
+}
+
+/** Bounded, non-throwing object preview (a hostile round may be circular). */
+function previewRound(r: unknown): string {
+  if (r === null || typeof r !== 'object') return String(r)
+  const roundNo = (r as { round?: unknown }).round
+  const findings = (r as { findings?: unknown }).findings
+  return `{round: ${String(roundNo)}, findings: ${
+    Array.isArray(findings) ? `array(${findings.length})` : typeof findings
+  }}`
+}
+
 /**
  * Audit a ReviewReport for internal consistency.
  *
@@ -154,7 +204,9 @@ export function metaReviewReport(report: ReviewReport): MetaReviewResult {
   >
   for (const f of findings) {
     const s = f?.severity as ReviewFinding['severity'] | undefined
-    if (s && s in sevCounts) sevCounts[s]++
+    // hasOwn, not `in`: `'__proto__' in sevCounts` is true via inheritance,
+    // and an out-of-spec severity must simply not be bucketed.
+    if (s && Object.hasOwn(sevCounts, s)) sevCounts[s]++
   }
   const bucketSum = sevCounts.critical + sevCounts.high + sevCounts.medium + sevCounts.low
   const declaredSeveritySum =
@@ -217,20 +269,22 @@ export function metaReviewReport(report: ReviewReport): MetaReviewResult {
       'CONVERGENCE_SUM',
       'high',
       'convergence.findingsByRound does not sum to totalFindings',
-      `findingsByRound ${JSON.stringify(findingsByRound)} sums to ${convSum}, ` +
+      `findingsByRound [${previewList(findingsByRound)}] sums to ${convSum}, ` +
         `but totalFindings is ${total}.`,
     )
   }
   // `findingsByRound` is indexed by the actual round number (round r → index
-  // r-1), so the "last round" is the LAST RECORDED round's reported number, not
-  // the array's last index (the array is sized to the highest round, which only
-  // equals the record count for contiguous 1..N round numbers). Read the flag
-  // consistency the same way buildReviewReport/computeConvergence set it.
+  // r-1), so the "last round" is the HIGHEST VALID round number, not the
+  // array's last element (buildReviewReport sorts its round list, but this
+  // audit runs on arbitrary JSON, and a malformed trailing round — `1.5`,
+  // `Infinity` — must not be used as an index: Math.min(1.5, len) - 1 is
+  // fractional and reads `undefined` → 0 new → a false CONVERGENCE_FLAG).
   const reportRounds = Array.isArray(report.rounds) ? report.rounds : []
-  const lastRecordedRound =
-    reportRounds.length > 0 && typeof reportRounds[reportRounds.length - 1]?.round === 'number'
-      ? reportRounds[reportRounds.length - 1]!.round
-      : null
+  let lastRecordedRound: number | null = null
+  for (const r of reportRounds) {
+    if (!r || typeof r !== 'object' || !isValidRoundNumber(r.round)) continue
+    if (lastRecordedRound === null || r.round > lastRecordedRound) lastRecordedRound = r.round
+  }
   const lastRoundNew =
     lastRecordedRound !== null && lastRecordedRound > 0
       // Over-cap rounds are FOLDED by aggregateRounds into the final slot, so a
@@ -254,12 +308,21 @@ export function metaReviewReport(report: ReviewReport): MetaReviewResult {
   const rounds = Array.isArray(report.rounds) ? report.rounds : []
   const seenRounds = new Set<number>()
   for (const [index, r] of rounds.entries()) {
-    if (!r || typeof r.round !== 'number' || r.round < 1) {
+    // Reject everything the deterministic core would refuse: a missing,
+    // non-integer, non-finite or absurdly large round number. This is also
+    // the DoS guard for ROUND_GAP below — a round of `Infinity`/1e15 would
+    // otherwise be treated as a legitimate endpoint of the enumeration range.
+    if (
+      !r ||
+      typeof r !== 'object' ||
+      !isValidRoundNumber(r.round) ||
+      r.round > MAX_REVIEW_ROUND_NUMBER
+    ) {
       add(
         'ROUND_NUMBER',
         'medium',
-        'A round has a missing or non-positive round number',
-        `round: ${JSON.stringify(r)}`,
+        'A round has a missing, non-integer or out-of-range round number',
+        `round: ${previewRound(r)} (round numbers must be integers in 1..${MAX_REVIEW_ROUND_NUMBER})`,
       )
       continue
     }
@@ -283,13 +346,42 @@ export function metaReviewReport(report: ReviewReport): MetaReviewResult {
   if (present.length > 0) {
     const min = present[0]!
     const max = present[present.length - 1]!
-    for (let i = min; i <= max; i++) {
-      if (!seenRounds.has(i)) {
+    const span = max - min + 1
+    const presentPreview = previewList(present, 20)
+    // Hard bound on the enumeration: `min`/`max` come from untrusted round
+    // numbers, so an unguarded `for (i = min; i <= max; i++)` over
+    // {1, 1e15} is an effectively-infinite loop (CPU DoS) that would also
+    // push ~1e15 issues. Rounds above MAX_REVIEW_ROUND_NUMBER are rejected
+    // above, which keeps `span` bounded on its own; this guard stays as the
+    // belt-and-braces backstop so the walk is O(MAX_ROUND_GAP_SPAN) no
+    // matter what reaches it.
+    if (span > MAX_ROUND_GAP_SPAN) {
+      add(
+        'ROUND_GAP',
+        'medium',
+        `Round sequence ${min}..${max} is too wide to audit for gaps`,
+        `${span} round numbers spanned; only rounds present were accepted: ${presentPreview}.`,
+      )
+    } else {
+      const missing: number[] = []
+      for (let i = min; i <= max; i++) {
+        if (!seenRounds.has(i)) missing.push(i)
+      }
+      for (const m of missing.slice(0, MAX_ROUND_GAP_REPORTS)) {
+        add(
+          'ROUND_GAP',
+          'medium',
+          `Round ${m} is missing from the round sequence`,
+          `rounds present: ${presentPreview}.`,
+        )
+      }
+      if (missing.length > MAX_ROUND_GAP_REPORTS) {
         add(
           'ROUND_GAP',
           'medium',
-          `Round ${i} is missing from the round sequence`,
-          `rounds present: ${present.join(', ')}.`,
+          `${missing.length - MAX_ROUND_GAP_REPORTS} more rounds are missing (list capped)`,
+          `${missing.length} of the ${span} numbers in ${min}..${max} are absent; only the first ` +
+            `${MAX_ROUND_GAP_REPORTS} are listed individually. rounds present: ${presentPreview}.`,
         )
       }
     }
@@ -304,6 +396,37 @@ export function metaReviewReport(report: ReviewReport): MetaReviewResult {
   }
 }
 
+/**
+ * Human-readable reason for a failed evidence attestation.
+ *
+ * `file_too_large` / `binary_file` are DISTINCT from `line_out_of_range` (see
+ * evidence.ts): the file EXISTS but cannot be line-addressed, so saying
+ * "does not exist" would send the reader looking for a missing file.
+ */
+function describeEvidenceViolation(v: FindingEvidence): string {
+  switch (v.error) {
+    case 'file_too_large':
+      return `${v.file} is too large to line-address (over the evidence size cap)`
+    case 'binary_file':
+      return `${v.file} is a binary (NUL-containing) file that cannot be line-addressed`
+    case 'line_out_of_range':
+      return v.lineTotal !== undefined && v.lineTotal !== null
+        ? `${v.line} is beyond this file's ${v.lineTotal} lines`
+        : `${v.file} is not a regular line-addressable file (directory/device/FIFO)`
+    default:
+      return `${v.file} does not exist at all (verifiable read required)`
+  }
+}
+
+/** Headline for a failed evidence attestation (matches the detail above). */
+function evidenceViolationSummary(v: FindingEvidence): string {
+  const unaddressable = v.error === 'file_too_large' || v.error === 'binary_file'
+  const head = unaddressable
+    ? 'Finding cannot be anchored to line-addressable code'
+    : 'Finding references non-existent code'
+  return `${head}: ${v.file}${v.line ? `:${v.line}` : ''}`
+}
+
 /**
  * Build the final review report: pair the source report with its meta-review
  * verdict and a rolled-up summary. Pure and deterministic.
@@ -356,34 +479,28 @@ export function buildFinalReviewReport(
     if (evidence.results.some((r) => r.error !== undefined)) {
       for (const violation of evidence.results) {
         if (violation.error === undefined) continue
-        const detail =
-          violation.error === 'line_out_of_range'
-            ? violation.lineTotal !== undefined && violation.lineTotal !== null
-              ? `${violation.line} is beyond this file's ${violation.lineTotal} lines`
-              : `${violation.file} is a binary/unreadable file not line-addressable`
-            : `${violation.file} does not exist at all (verifiable read required)`
+        const detail = describeEvidenceViolation(violation)
+        const summary = evidenceViolationSummary(violation)
         let roundHint = ''
         if (report && violation.file) {
           // Try to attribute the poisoned finding to the round that first
-          // surfaced it (best-effort; report rounds carry it).
-          for (const r of report.rounds ?? []) {
-            const matched = (r.findings ?? []).some(
+          // surfaced it (best-effort; report rounds carry it). `rounds` is
+          // untrusted JSON, so a null entry must not throw here.
+          for (const r of (Array.isArray(report.rounds) ? report.rounds : []) ?? []) {
+            const findings = Array.isArray(r?.findings) ? r.findings : []
+            const matched = findings.some(
               (fnd) => !!fnd && fnd?.file === violation.file && fnd?.line === violation.line,
             )
             if (matched) {
-              roundHint = ` (round ${r.round})`
+              roundHint = ` (round ${String(r.round)})`
               break
             }
           }
         }
-        const summary =
-          `Finding references non-existent code: ${violation.file}` +
-          (violation.line ? `:${violation.line}` : '') +
-          roundHint
         meta.issues.push({
           code: 'EVIDENCE_VIOLATION',
           severity: 'critical',
-          summary,
+          summary: summary + roundHint,
           detail: detail + '. Review results must anchor to real, read code.',
         })
       }

package/src/method-scope.ts

@@ -94,7 +94,11 @@ const SIGNATURE_PATTERNS: Array<{ kind: string; re: RegExp; nameIndex: number }>
  * Returns a sorted array of `{ name, line }` (1-based line numbers).
  */
 export function collectMethodSignatures(text: string): MethodSignature[] {
-  const lines = text.split('\n')
+  // Defensive: callers hand in file content read from disk / tool args, which
+  // may be missing or wrong-typed when a fix record is malformed. A non-string
+  // would throw on `.split` inside the atomic-fix gate.
+  const source = typeof text === 'string' ? text : ''
+  const lines = source.split('\n')
   const out: MethodSignature[] = []
   // Set lookup instead of scanning the growing array (O(S²) → O(S)).
   const seen = new Set<string>()
@@ -119,7 +123,7 @@ export function collectMethodSignatures(text: string): MethodSignature[] {
 
 /** Number of physical lines in `text` (a trailing newline does not add a line). */
 export function countTextLines(text: string): number {
-  if (text === '') return 0
+  if (typeof text !== 'string' || text === '') return 0
   const parts = text.split('\n')
   return parts[parts.length - 1] === '' ? parts.length - 1 : parts.length
 }
@@ -131,10 +135,13 @@ export function countTextLines(text: string): number {
  * span runs to the final non-blank line of the file.
  */
 export function collectMethodSpans(text: string): MethodSpan[] {
-  const signatures = collectMethodSignatures(text)
+  // Same non-string guard as collectMethodSignatures: this runs inside the
+  // atomic-fix gate on content that may be missing.
+  const source = typeof text === 'string' ? text : ''
+  const signatures = collectMethodSignatures(source)
   if (signatures.length === 0) return []
-  const lines = text.split('\n')
-  const lineCount = countTextLines(text)
+  const lines = source.split('\n')
+  const lineCount = countTextLines(source)
 
   /** Last non-blank line at or before `candidate`. */
   function trimBlank(endCandidate: number, floor: number): number {
@@ -162,6 +169,19 @@ function intersects(spanStart: number, spanEnd: number, regionStart: number, reg
   return spanStart <= regionEnd && spanEnd >= regionStart
 }
 
+/**
+ * True when a hunk's coordinates are usable for span intersection.
+ *
+ * `hunks` is a `ChangedRegion[]` that reaches this gate from a diff computed
+ * on tool-arg content; a malformed entry (`NaN`, `Infinity`, a negative or
+ * fractional line number) would build a `NaN`/negative region that either
+ * matches every method or none, silently wrong-sizing the adjacent-method
+ * verdict. Non-finite and negative starts/counts are simply skipped.
+ */
+function isValidRegion(start: number, count: number): boolean {
+  return Number.isInteger(start) && start >= 0 && Number.isInteger(count) && count >= 1
+}
+
 /**
  * Count the distinct methods a set of diff hunks touches.
  *
@@ -179,12 +199,15 @@ export function countTouchedMethods(
   after: string,
   hunks: ChangedRegion[],
 ): number {
-  if (hunks.length === 0) return 0
+  // A non-array `hunks` (malformed fix record / tool arg) is "nothing
+  // changed", matching the empty-hunk case — never a throw in the fix gate.
+  if (!Array.isArray(hunks) || hunks.length === 0) return 0
   const beforeSpans = collectMethodSpans(before)
   const afterSpans = collectMethodSpans(after)
   const touched = new Set<string>()
   for (const h of hunks) {
-    if (h.oldLines > 0) {
+    if (!h || typeof h !== 'object') continue
+    if (h.oldLines > 0 && isValidRegion(h.oldStart, h.oldLines)) {
       const oldEnd = h.oldStart + h.oldLines - 1
       for (const s of beforeSpans) {
         if (intersects(s.startLine, s.endLine, h.oldStart, oldEnd)) {
@@ -192,7 +215,7 @@ export function countTouchedMethods(
         }
       }
     }
-    if (h.newLines > 0) {
+    if (h.newLines > 0 && isValidRegion(h.newStart, h.newLines)) {
       const newEnd = h.newStart + h.newLines - 1
       for (const s of afterSpans) {
         if (intersects(s.startLine, s.endLine, h.newStart, newEnd)) {

package/src/review-scope.ts

@@ -23,6 +23,13 @@
 
 import { readdirSync } from 'node:fs'
 import { join, relative } from 'node:path'
+// Single source of truth for the whole-file line sentinel: evidence.ts's gate
+// and this module's inventory filters must agree on what `0` means. Evidence
+// imports neither this module nor review.ts, so the edge is acyclic (review.ts
+// → review-scope.ts → evidence.ts → types.ts).
+import { WHOLE_FILE_LINE } from './evidence.ts'
+
+export { WHOLE_FILE_LINE }
 
 export interface CoverageResult {
   assigned: string[]
@@ -32,9 +39,6 @@ export interface CoverageResult {
   ratio: number
 }
 
-/** Relative-scope sentinel for whole-module findings. */
-export const WHOLE_FILE_LINE = 0
-
 /** Source extensions a full-scope walk includes. */
 const SOURCE_EXTENSIONS = new Set([
   '.py', '.pyi', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
@@ -100,13 +104,18 @@ export function collectScopeFiles(
   root: string,
   opts: { scope: 'full' | 'changed-only'; changedFiles?: string[] },
 ): string[] {
+  // `opts` / `scope` come from tool args: a missing or malformed options
+  // object must degrade to a full walk, never throw inside the inventory step.
+  if (!opts || typeof opts !== 'object') return collectFull(root)
   if (opts.scope === 'changed-only') return collectChanged(opts.changedFiles ?? [])
   return collectFull(root)
 }
 
 function collectChanged(changedFiles: string[]): string[] {
+  // A non-array `changedFiles` (JSON arg) must not be iterated char-by-char.
+  const list = Array.isArray(changedFiles) ? changedFiles : []
   const out = new Set<string>()
-  for (const rel of changedFiles) {
+  for (const rel of list) {
     if (typeof rel !== 'string' || !rel.trim()) continue
     if (rel === String(WHOLE_FILE_LINE)) continue
     const cleaned = normalizePath(rel)
@@ -156,9 +165,18 @@ function collectFull(root: string): string[] {
 /** Split `files` into stable batches, keeping directory runs together. */
 export function chunkFiles(files: string[], perChunk?: number): string[][] {
   // Number.isFinite: NaN fails `perChunk < 1` and would yield one unbounded
-  // chunk (current.length >= NaN is never true).
-  const size = Number.isFinite(perChunk) && (perChunk as number) >= 1 ? (perChunk as number) : DEFAULT_SCOPE_CHUNK_SIZE
-  const ordered = [...files].sort()
+  // chunk (current.length >= NaN is never true). Math.floor: a fractional
+  // size (2.5) made chunks alternate between 2 and 3 members — the caller's
+  // "files per batch" is a count, so it must be an integer.
+  const size =
+    Number.isFinite(perChunk) && (perChunk as number) >= 1
+      ? Math.floor(perChunk as number)
+      : DEFAULT_SCOPE_CHUNK_SIZE
+  // A non-array / sparse-free copy: callers pass tool-arg JSON, and sort()
+  // on a non-array (or `rel.includes` on a number) would throw.
+  const ordered = (Array.isArray(files) ? files : [])
+    .filter((rel): rel is string => typeof rel === 'string')
+    .sort()
   const chunks: string[][] = []
   let current: string[] = []
   let lastDir: string | undefined
@@ -186,11 +204,16 @@ export function computeCoverage(
   assigned: string[],
   readFiles?: string[] | null,
 ): CoverageResult {
+  // Both lists are JSON-arg-derived: `for...of` over a bare number throws and
+  // over a bare string iterates single characters into the read set. Anything
+  // non-array behaves like "nothing" (empty inventory / nothing read).
+  const assignedList = Array.isArray(assigned) ? assigned : []
+  const readList = Array.isArray(readFiles) ? readFiles : []
   const readNorm = new Set<string>()
-  for (const p of readFiles ?? []) {
+  for (const p of readList) {
     if (typeof p === 'string' && p) readNorm.add(normalizePath(p))
   }
-  const assignedSorted = [...assigned].sort()
+  const assignedSorted = [...assignedList].filter((rel): rel is string => typeof rel === 'string').sort()
   const covered = assignedSorted.filter((rel) => readNorm.has(normalizePath(rel)))
   const uncovered = assignedSorted.filter((rel) => !readNorm.has(normalizePath(rel)))
   const rawRatio =
@@ -198,7 +221,7 @@ export function computeCoverage(
   const ratio = Math.round(rawRatio * 1000) / 1000
   return {
     assigned: assignedSorted,
-    read: [...new Set((readFiles ?? []).filter((p): p is string => typeof p === 'string'))].sort(),
+    read: [...new Set(readList.filter((p): p is string => typeof p === 'string'))].sort(),
     covered,
     uncovered,
     ratio,

package/src/review.ts

@@ -54,9 +54,46 @@ export function sortFindings(findings: ReviewFinding[]): ReviewFinding[] {
   })
 }
 
+/**
+ * Hard ceiling on the round cap the aggregation math will honor.
+ *
+ * Mirrors `MAX_MAX_ROUNDS` in `config-loader.ts` (the config bomb guard) —
+ * `test/review.test.ts` asserts the two constants stay in sync. The tool
+ * boundary only clamps the LOWER bound of `maxReviewRounds`, so an absurd
+ * caller value (1e15) would otherwise drive the `findingsByRound` allocation
+ * bound (`roundCap * 2`) straight into OOM territory.
+ */
+export const MAX_REVIEW_ROUNDS_CAP = 100
+
+/**
+ * Clamp an untrusted round cap to `[1, MAX_REVIEW_ROUNDS_CAP]`.
+ *
+ * Non-finite / non-numeric input (`NaN`, `Infinity`, a string) collapses to
+ * 1 — the smallest sane cap. Without this, `Math.max(1, NaN)` stayed `NaN`
+ * and `new Array(NaN)` threw `RangeError` out of `aggregateRounds`.
+ */
+export function clampMaxReviewRounds(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return 1
+  return Math.min(MAX_REVIEW_ROUNDS_CAP, Math.max(1, Math.floor(value)))
+}
+
+/**
+ * True when `n` is a round number the deterministic core accepts: a positive
+ * integer. Shared by `aggregateRounds` / `computeConvergence` /
+ * `buildReviewReport` (and re-read by the meta-review audit) so every reader
+ * of "the last round" agrees on which round numbers count — a fractional
+ * (`1.5`) or non-finite round is simply "not a round", never a convergence
+ * input that could be mis-indexed into `findingsByRound`.
+ */
+export function isValidRoundNumber(n: unknown): n is number {
+  return typeof n === 'number' && Number.isInteger(n) && n >= 1
+}
+
 /** Normalize a summary so near-identical duplicates collapse to one key. */
 export function normalizeSummary(summary: string): string {
-  return summary
+  // Coerce: `summary` is model-authored JSON when schema validation is off,
+  // so a numeric summary must not crash `.trim()` inside the dedupe key.
+  return String(summary ?? '')
     .trim()
     .toLowerCase()
     .replace(/[\s\n\t]+/g, ' ')
@@ -69,8 +106,14 @@ export function normalizeSummary(summary: string): string {
  * neither side anchors one, i.e. whole-file findings).
  */
 export function findingKey(f: ReviewFinding): string {
-  const line = typeof f.line === 'number' && f.line > 0 ? f.line : 0
-  return `${f.file}|${f.dimension}|${line}|${normalizeSummary(f.summary)}`
+  // Defensive reads: with `output_schema_validation: false` a finding may
+  // carry wrong-typed fields (and `f` itself may be a null list element), and
+  // this key feeds the dedupe Set on EVERY round — it must never throw.
+  const src = (f ?? {}) as Partial<ReviewFinding>
+  const line = typeof src.line === 'number' && src.line > 0 ? src.line : 0
+  return `${String(src.file ?? '')}|${String(src.dimension ?? '')}|${line}|${normalizeSummary(
+    src.summary as string,
+  )}`
 }
 
 /**
@@ -81,6 +124,9 @@ export function dedupeFindings(findings: ReviewFinding[]): ReviewFinding[] {
   const seen = new Set<string>()
   const out: ReviewFinding[] = []
   for (const f of findings) {
+    // A null / array entry (hostile or schema-validation-off JSON) must never
+    // reach `summarize`, which reads `f.severity` unguarded.
+    if (!f || typeof f !== 'object' || Array.isArray(f)) continue
     const key = findingKey(f)
     if (seen.has(key)) continue
     seen.add(key)
@@ -99,9 +145,16 @@ export function filterKnownIntentional(
   findings: ReviewFinding[],
   known: KnownIntentional[] | undefined,
 ): ReviewFinding[] {
-  if (!known || known.length === 0) return findings
+  // `known` is config/arg JSON: a non-array truthy value must behave like
+  // "no entries", never reach `known.some` and throw.
+  if (!Array.isArray(known) || known.length === 0) return findings
   return findings.filter((f) => {
+    // A null / non-object finding has no file/dimension to match on; drop it
+    // here so it can never crash the comparator (aggregateRounds drops it too,
+    // so the report's counts stay consistent either way).
+    if (!f || typeof f !== 'object' || Array.isArray(f)) return false
     const matched = known.some((k) => {
+      if (!k || typeof k !== 'object') return false
       const sameFile = k.file === f.file
       const sameDim = k.dimension === f.dimension
       if (!sameFile || !sameDim) return false
@@ -145,13 +198,21 @@ export function aggregateRounds(
   // 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) {
+  // Upper-bounded too: `Math.max(1, NaN)` used to stay NaN and blow up in
+  // `new Array(effectiveMax)`, and an unbounded cap scaled the allocation
+  // bound to whatever the caller asked for.
+  const roundCap = clampMaxReviewRounds(maxReviewRounds)
+  for (const round of Array.isArray(rounds) ? rounds : []) {
     if (!round || typeof round !== 'object') continue
-    if (typeof round.round !== 'number' || !Number.isInteger(round.round) || round.round < 1) continue
+    if (!isValidRoundNumber(round.round)) continue
     const findings = Array.isArray(round.findings) ? round.findings : []
     if (round.round > maxRound) maxRound = round.round
     for (const f of findings) {
+      // Null / non-object elements (schema validation off) would crash
+      // `findingKey`; dropping them here keeps `findingsByRound` summing to
+      // exactly the returned findings list (the meta-review's CONVERGENCE_SUM
+      // check reads that equality).
+      if (!f || typeof f !== 'object' || Array.isArray(f)) continue
       const key = findingKey(f)
       if (seen.has(key)) continue
       seen.add(key)
@@ -185,8 +246,9 @@ export function computeConvergence(
   rounds: ReviewRound[],
   maxReviewRounds: number,
 ): ReviewReport['convergence'] {
-  const { findingsByRound } = aggregateRounds(rounds, maxReviewRounds)
-  const totalRounds = rounds.length
+  const list = Array.isArray(rounds) ? rounds : []
+  const { findingsByRound } = aggregateRounds(list, maxReviewRounds)
+  const totalRounds = list.length
   // `findingsByRound` is indexed by the actual round number (round r → index
   // r-1), sized to the highest present round (clamped). Convergence must read
   // the HIGHEST PRESENT round's count — not the last array element (rounds
@@ -194,13 +256,15 @@ export function computeConvergence(
   // 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
+  for (const round of list) {
+    if (!isValidRoundNumber(round?.round)) 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
+  // `lastRound === 0` means NO round carried an interpretable number: claiming
+  // `converged` there would bless a report the core could not actually read.
+  const converged = totalRounds > 0 && lastRound > 0 && lastRoundCount === 0
   return {
     totalRounds,
     findingsByRound,
@@ -222,7 +286,15 @@ function summarize(findings: ReviewFinding[]): ReviewReport['summary'] {
     high: 0,
     medium: 0,
     low: 0,
-    byDimension: {},
+    // NULL-PROTOTYPE map: a model-authored `dimension` of `__proto__` or
+    // `constructor` would otherwise resolve against Object.prototype — the
+    // `__proto__` setter silently discards a primitive value and `constructor`
+    // string-concatenates the Object function — so the counter never
+    // accumulated and the meta-review's DIMENSION_SUM check false-positived.
+    // A null-prototype object has no inherited accessors, so every dimension
+    // (including those three names) is a plain own data property and
+    // JSON-serializes normally.
+    byDimension: Object.create(null) as Record<string, number>,
   }
   for (const f of findings) {
     if (f.severity === 'critical') summary.critical++
@@ -252,7 +324,8 @@ export function buildReviewReport(input: {
   fixedCount?: number
 }): ReviewReport {
   // 1. Filter known-intentional per round (before cross-round dedupe).
-  const filteredRounds = input.rounds
+  const inputRounds = Array.isArray(input.rounds) ? input.rounds : []
+  const filteredRounds = inputRounds
     .map((r) => ({
       round: typeof r?.round === 'number' ? r.round : 0,
       findings: filterKnownIntentional(
@@ -284,7 +357,11 @@ export function buildReviewReport(input: {
   //    non-contiguous round sets would otherwise read the wrong count).
   let lastRound = 0
   for (const r of filteredRounds) {
-    if (typeof r.round === 'number' && r.round > lastRound) lastRound = r.round
+    // Same validity rule as aggregateRounds: a fractional / NaN round is not
+    // a round, so it must never be used as an index into `findingsByRound`
+    // (Math.min(1.5, len) - 1 = 0.5 → reads `undefined` → counts as 0 new →
+    // a round that really did report findings would be read as "converged").
+    if (isValidRoundNumber(r.round) && r.round > lastRound) lastRound = r.round
   }
   // `lastRound` can exceed the array length when over-cap rounds were FOLDED
   // into the last slot (see aggregateRounds). Read the same clamped index
@@ -293,7 +370,7 @@ export function buildReviewReport(input: {
   const idx = Math.min(lastRound, findingsByRound.length) - 1
   const lastRoundCount =
     lastRound > 0 && idx >= 0 ? (findingsByRound[idx] ?? 0) : 0
-  const converged = filteredRounds.length > 0 && lastRoundCount === 0
+  const converged = filteredRounds.length > 0 && lastRound > 0 && lastRoundCount === 0
 
   // Attach the normal-mode fix count to the summary (dry-run leaves it absent).
   const computed = summarize(sorted)
@@ -858,7 +935,9 @@ export function buildReviewPlan(input: {
     goal,
     scope,
     dimensions: dimensionTasks,
-    maxReviewRounds: input.maxReviewRounds,
+    // Clamped with the SAME rule aggregateRounds honors, so the cap this plan
+    // advertises is never a number the aggregation math would silently clamp.
+    maxReviewRounds: clampMaxReviewRounds(input.maxReviewRounds),
     knownIntentional: input.knownIntentional ?? [],
     changedFiles: effectiveChangedOnly ? changedFiles : [],
     fallbackToFull,