iterate-plugin 3.5.4 → 3.5.6

package/src/client/index.ts

@@ -81,6 +81,7 @@ import {
   latestPhase,
   SEVERITY_LABEL,
   SEVERITY_COLOR,
+  stoppedReasonLabel,
 } from '../../lib/parse.js'
 
 // ─── Module contract ─────────────────────────────────────────────────────────
@@ -737,17 +738,6 @@ function severityLabel(severity: string | undefined): string {
   return SEVERITY_LABEL[coerceSeverity(severity)]
 }
 
-/** Human label for WHY a finished run stopped (transcript manifest). */
-function stoppedReasonLabel(reason: string | null | undefined): string {
-  switch (reason) {
-    case 'converged': return '已结束 · 已收敛（无新发现）'
-    case 'max_rounds_reached': return '已结束 · 达到轮数上限'
-    case 'aborted_by_validation': return '已结束 · 验证失败后回滚停止'
-    case 'aborted_by_config': return '已结束 · 验证命令不在白名单（配置需修复）'
-    default: return reason ? `已结束 · ${reason}` : '已结束'
-  }
-}
-
 /** Badge text for the run's live/finished state, annotated with the stop reason. */
 function runStatusText(live: boolean, manifest: ObsManifest | null | undefined): string {
   if (live) return '运行中'
@@ -785,6 +775,7 @@ let slotsSvc: SlotsService | undefined = undefined
 let themeSvc: ThemeService | undefined = undefined
 let storage: ReturnType<typeof createStorage> | null = null
 let themeDisposer: (() => void) | null = null
+let themeListener: (() => void) | null = null
 let themeEnabled = true
 const roundPulseListeners: Array<(payload: { round: number; converged: boolean }) => void> = []
 
@@ -814,6 +805,33 @@ function clearThemeSkin(): void {
   }
 }
 
+/**
+ * Register the theme/change hook exactly once per client lifecycle.
+ * The listener is tracked so a re-`apply()` (hot reload / re-mount) never
+ * stacks a second copy — every new registration first drops the previous
+ * one, and `ctx.effect` pairs it off when the client unmounts.
+ */
+function registerThemeListener(ctx: ClientContext): void {
+  if (typeof ctx.on !== 'function') return
+  if (themeListener) {
+    try { themeListener() } catch { /* noop */ }
+    themeListener = null
+  }
+  const off = ctx.on('theme/change', () => {
+    if (themeEnabled) applyThemeSkin()
+  })
+  // `ctx.on` may return void (no unsubscribe support) — only track a callback.
+  themeListener = typeof off === 'function' ? off : null
+  if (typeof ctx.effect === 'function') {
+    ctx.effect(() => {
+      if (themeListener) {
+        try { themeListener() } catch { /* noop */ }
+        themeListener = null
+      }
+    })
+  }
+}
+
 /** Persist + apply the theme preference. */
 function setThemeEnabled(enabled: boolean): void {
   themeEnabled = enabled
@@ -2826,15 +2844,20 @@ export function apply(ctx: ClientContext): void {
   themeEnabled = savedTheme === null ? true : savedTheme === '1'
   if (themeEnabled) applyThemeSkin()
 
-  // 3. Inject styles (independent of slots / React availability).
+  // 3. Inject styles (independent of slots / React availability). Guarded so a
+  // re-`apply()` never appends a duplicate <style>: the tag is keyed by a
+  // `dataset.iterateLock` marker instead of relying on the CSS content.
   if (typeof document !== 'undefined' && document.createElement && document.head) {
-    const style = document.createElement('style')
-    style.dataset.plugin = PLUGIN_TAG
-    style.dataset.pluginCss = 'iterate-main'
-    style.textContent = ITERATE_CSS
-    document.head.appendChild(style)
-    if (typeof ctx.effect === 'function') {
-      ctx.effect(() => { try { style.remove() } catch { /* noop */ } })
+    if (!document.head.querySelector('style[data-iterate-lock="1"]')) {
+      const style = document.createElement('style')
+      style.dataset.iterateLock = '1'
+      style.dataset.plugin = PLUGIN_TAG
+      style.dataset.pluginCss = 'iterate-main'
+      style.textContent = ITERATE_CSS
+      document.head.appendChild(style)
+      if (typeof ctx.effect === 'function') {
+        ctx.effect(() => { try { style.remove() } catch { /* noop */ } })
+      }
     }
   }
 
@@ -2889,9 +2912,7 @@ export function apply(ctx: ClientContext): void {
   }
 
   // 6: keep theme toggle state consistent across theme/change events.
-  if (typeof ctx.on === 'function') {
-    ctx.on('theme/change', () => {
-      if (themeEnabled) applyThemeSkin()
-    })
-  }
+  // Registered through registerThemeListener so repeated apply() and client
+  // unmounts never leak a second listener.
+  registerThemeListener(ctx)
 }

package/src/config-loader.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, resolve, sep } from 'node:path'
 import yaml from 'js-yaml'
@@ -12,7 +12,10 @@ export function loadConfig(projectRoot: string): IterateConfig | null {
   try {
     const content = readFileSync(join(projectRoot, 'iterate.config.yaml'), 'utf-8')
     const parsed = yaml.load(content) as Record<string, unknown>
-    if (!parsed || typeof parsed !== 'object') return null
+    // A YAML sequence root (e.g. a list of findings or a `- foo` file) must
+    // not masquerade as a config object — treating it as one would merge its
+    // indices into the config (config bomb). Reject it, not coerce it.
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
     return parsed as unknown as IterateConfig
   } catch {
     return null
@@ -158,7 +161,7 @@ export function flattenCommands(
  */
 export function validateConfig(config: unknown): string[] {
   const errors: string[] = []
-  if (!config || typeof config !== 'object') {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
     errors.push('root')
     return errors
   }
@@ -206,13 +209,33 @@ export type ProjectRootResult = { ok: true; root: string } | { ok: false; reason
  *      the DSH runtime injects per-session env into tool sub-processes).
  */
 export function resolveProjectRoot(input?: string, sessionCwd?: string): ProjectRootResult {
-  const raw = (input ?? '').trim()
+  // A non-string input (number, array, …) from a hostile tool invocation must
+  // be treated as "no explicit path" instead of crashing on `.trim()`.
+  const raw = (typeof input === 'string' ? input : '').trim()
   // A NUL byte can never name a real path and makes `resolve()` (and every
   // downstream fs call) throw — treat it as unsafe input, not a throw path.
   if (raw.includes('\0')) {
     return { ok: false, reason: 'Refusing project root containing NUL bytes.' }
   }
-  const root = raw ? resolve(raw) : resolve(effectiveCwd(sessionCwd))
+  const rootLexical = raw ? resolve(raw) : resolve(effectiveCwd(sessionCwd))
+  // Collapse symlinks (documented contract: "collapsing `..` and symlinks") —
+  // a path through a symlinked directory must resolve to its REAL location so
+  // two aliases of the same project share one `.iterate/` state, and tools can
+  // never read outside the resolved root via a link. Only when the path
+  // exists: a not-yet-created target (dirs created through the tools) keeps
+  // the lexical path so the caller can still write into it. The filesystem
+  // root check runs against the NORMALIZED path, so a symlink to `/` is
+  // refused too.
+  let root = rootLexical
+  try {
+    if (existsSync(rootLexical)) {
+      const real = realpathSync(rootLexical)
+      if (real) root = real
+    }
+  } catch {
+    // realpath can throw on a broken link or a permission fence — keep the
+    // lexical path (existing behavior) rather than failing the resolution.
+  }
   if (!root || root === sep) {
     return { ok: false, reason: 'Refusing filesystem root as project root.' }
   }

package/src/config-write.ts

@@ -10,8 +10,8 @@
  * config, always back up before writing, roll back on failure.
  */
 
-import { copyFileSync, existsSync, readFileSync, rmSync } from 'node:fs'
-import { join } from 'node:path'
+import { copyFileSync, existsSync, readFileSync, readdirSync, rmSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
 import yaml from 'js-yaml'
 import { writeTextAtomic } from './atomic-fs.ts'
 
@@ -23,6 +23,49 @@ export function configBackupSuffix(now = new Date()): string {
   return now.toISOString().replace(/[:.]/g, '-')
 }
 
+/** Upper bound on configurable iteration rounds (config bomb guard). */
+export const MAX_MAX_ROUNDS = 100
+
+/** Upper bound on `atomic.max_lines` (a single fix never needs more). */
+export const MAX_ATOMIC_MAX_LINES = 10_000
+
+/** Upper bound on `atomic.max_adjacent_methods`. */
+export const MAX_MAX_ADJACENT_METHODS = 200
+
+/** Upper bound on `reviewer.scope_chunk_size` (files per reviewer task batch). */
+export const MAX_SCOPE_CHUNK_SIZE = 1000
+
+/** Keep at most this many timestamped config backups (older ones are removed). */
+export const MAX_CONFIG_BACKUPS = 5
+
+/**
+ * Bound the timestamped config backups: after a fresh one is written, delete
+ * every older `config.bak-*` file beyond the newest `keep`. Best-effort — a
+ * filesystem failure here must never fail the write that just succeeded.
+ * @returns the absolute paths of the backups that were removed.
+ */
+export function pruneOldConfigBackups(
+  configPath: string,
+  keep = MAX_CONFIG_BACKUPS,
+): string[] {
+  const removed: string[] = []
+  try {
+    const dir = dirname(configPath)
+    const prefix = `${basename(configPath)}.bak-`
+    const matches = existsSync(dir)
+      ? readdirSync(dir).filter((f) => f.startsWith(prefix)).sort()
+      : []
+    const doomed = matches.slice(0, Math.max(0, matches.length - keep))
+    for (const f of doomed) {
+      rmSync(join(dir, f), { force: true })
+      removed.push(join(dir, f))
+    }
+  } catch {
+    // Best-effort cleanup — never surface a cleanup failure.
+  }
+  return removed
+}
+
 /**
  * Validate a partial config update.
  * Returns an array of error strings (empty when the update is valid).
@@ -45,8 +88,40 @@ export function validateConfigUpdates(updates: Record<string, unknown>): string[
     }
   }
   if ('max_rounds' in updates) {
-    if (typeof updates.max_rounds !== 'number' || !Number.isInteger(updates.max_rounds) || updates.max_rounds < 1) {
-      errors.push('updates.max_rounds must be a positive integer')
+    if (
+      typeof updates.max_rounds !== 'number' || !Number.isInteger(updates.max_rounds) ||
+      updates.max_rounds < 1 || updates.max_rounds > MAX_MAX_ROUNDS
+    ) {
+      errors.push(`updates.max_rounds must be an integer between 1 and ${MAX_MAX_ROUNDS}`)
+    }
+  }
+  if ('reasoning_effort' in updates) {
+    if (
+      updates.reasoning_effort !== undefined &&
+      updates.reasoning_effort !== 'low' &&
+      updates.reasoning_effort !== 'medium' &&
+      updates.reasoning_effort !== 'high'
+    ) {
+      errors.push('updates.reasoning_effort must be "low", "medium", or "high"')
+    }
+  }
+  if ('reviewer' in updates) {
+    const rv = updates.reviewer as Record<string, unknown> | undefined
+    if (!rv || typeof rv !== 'object') {
+      errors.push('updates.reviewer must be an object')
+    } else {
+      for (const boolKey of ['output_schema_validation', 'evidence_validation', 'coverage_validation'] as const) {
+        if (rv[boolKey] !== undefined && typeof rv[boolKey] !== 'boolean') {
+          errors.push(`updates.reviewer.${boolKey} must be a boolean`)
+        }
+      }
+      if (
+        rv.scope_chunk_size !== undefined &&
+        (typeof rv.scope_chunk_size !== 'number' || !Number.isInteger(rv.scope_chunk_size) ||
+          rv.scope_chunk_size < 1 || rv.scope_chunk_size > MAX_SCOPE_CHUNK_SIZE)
+      ) {
+        errors.push(`updates.reviewer.scope_chunk_size must be an integer between 1 and ${MAX_SCOPE_CHUNK_SIZE}`)
+      }
     }
   }
   if ('review' in updates) {
@@ -62,11 +137,11 @@ export function validateConfigUpdates(updates: Record<string, unknown>): string[
     if (!a || typeof a !== 'object') {
       errors.push('updates.atomic must be an object')
     } else {
-      if (a.max_lines !== undefined && (typeof a.max_lines !== 'number' || !Number.isInteger(a.max_lines) || a.max_lines < 1)) {
-        errors.push('updates.atomic.max_lines must be a positive integer')
+      if (a.max_lines !== undefined && (typeof a.max_lines !== 'number' || !Number.isInteger(a.max_lines) || a.max_lines < 1 || a.max_lines > MAX_ATOMIC_MAX_LINES)) {
+        errors.push(`updates.atomic.max_lines must be an integer between 1 and ${MAX_ATOMIC_MAX_LINES}`)
       }
-      if (a.max_adjacent_methods !== undefined && (typeof a.max_adjacent_methods !== 'number' || a.max_adjacent_methods < 0)) {
-        errors.push('updates.atomic.max_adjacent_methods must be a non-negative number')
+      if (a.max_adjacent_methods !== undefined && (typeof a.max_adjacent_methods !== 'number' || a.max_adjacent_methods < 0 || a.max_adjacent_methods > MAX_MAX_ADJACENT_METHODS)) {
+        errors.push(`updates.atomic.max_adjacent_methods must be a number between 0 and ${MAX_MAX_ADJACENT_METHODS}`)
       }
     }
   }
@@ -168,7 +243,10 @@ export function readRawConfig(configPath: string): Record<string, unknown> {
   } catch {
     throw new Error('existing iterate.config.yaml is not a valid YAML mapping')
   }
-  if (!parsed || typeof parsed !== 'object') {
+  // A YAML sequence root (array) must not masquerade as a config object —
+  // `typeof [] === 'object'`, so the presence check alone would accept a
+  // config file that is actually a list. Writing over it would destroy data.
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
     throw new Error('existing iterate.config.yaml is not a valid YAML mapping')
   }
   return parsed as Record<string, unknown>
@@ -207,5 +285,9 @@ export function writeConfigFile(
     return { ok: false, error: `failed to write config: ${String(err)}${rollbackError}` }
   }
 
+  // Success: bound the accumulation of timestamped backups so a long-lived
+  // project never collects an unbounded pile of config snapshots.
+  if (backupPath) pruneOldConfigBackups(configPath)
+
   return { ok: true, backupPath }
 }

package/src/evidence.ts

@@ -115,7 +115,11 @@ export function verifyLineBounds(
   if (line === undefined || line === null || line === WHOLE_FILE_LINE) {
     return { inBounds: true, lineTotal }
   }
-  if (line < 1) return { inBounds: false, lineTotal }
+  // Only a positive INTEGER is a valid line anchor. A fractional line (e.g.
+  // 3.7 from a bypassed schema) or a negative value is out of bounds — a
+  // fractional line "within" the file would otherwise be accepted and poison
+  // the evidence trail with a location nothing can jump to.
+  if (line < 1 || !Number.isInteger(line)) return { inBounds: false, lineTotal }
   return { inBounds: line <= lineTotal, lineTotal }
 }
 
@@ -125,8 +129,36 @@ export function verifyFinding(
   input: Locatable,
   opts: { readSet?: Set<string> } = {},
 ): FindingEvidence {
-  const relFile = input.file ?? ''
+  // A null element / non-object finding (hostile or model-authored JSON) must
+  // be reported as poisoned evidence, never crash `path.resolve` downstream.
+  if (!input || typeof input !== 'object') {
+    return {
+      file: '',
+      line: null,
+      lineTotal: null,
+      resolvedPath: null,
+      verified: false,
+      error: 'file_not_found',
+    }
+  }
+  // A non-string `file` (number, object, …) would make `resolve` throw
+  // ERR_INVALID_ARG_TYPE — coerce to "" so it fails closed as not-found.
+  const relFile = typeof input.file === 'string' ? input.file : ''
   const line = typeof input.line === 'number' ? input.line : null
+
+  // "" resolves to the project ROOT (resolve(root, '') === root), which then
+  // trips the not-a-regular-file branch as `line_out_of_range` — but there is
+  // no file reference at all. Report it as `file_not_found` upfront.
+  if (relFile === '') {
+    return {
+      file: '',
+      line,
+      lineTotal: null,
+      resolvedPath: null,
+      verified: false,
+      error: 'file_not_found',
+    }
+  }
   const resolved = resolveWithin(root, relFile)
 
   if (resolved === null || !existsSync(resolved)) {

package/src/git-scope.ts

@@ -90,7 +90,10 @@ function decodeQuotedPath(content: string): string {
 
 export function parseChangedFiles(stdout: string): string[] {
   if (stdout.includes('\0')) {
-    return stdout.split('\0').map((s) => s.trim()).filter((s) => s.length > 0)
+    // NUL mode: git emits exact names with no surrounding whitespace, so any
+    // trim would CORRUPT a filename that legitimately starts/ends with spaces
+    // (git supports such names). Split and drop only the trailing empty entry.
+    return stdout.split('\0').filter((s) => s.length > 0)
   }
   return stdout
     .split('\n')
@@ -152,12 +155,19 @@ export function decideScope(changedFiles: string[]): {
 export function runGit(
   args: string[],
   cwd: string,
+  opts: { signal?: AbortSignal } = {},
 ): Promise<{ ok: boolean; stdout: string; stderr: string; exitCode: number }> {
   return new Promise((resolve) => {
     execFile(
       'git',
       args,
-      { cwd, timeout: 30_000, maxBuffer: 10 * 1024 * 1024, env: { ...process.env, PAGER: 'cat' } },
+      {
+        cwd,
+        timeout: 30_000,
+        maxBuffer: 10 * 1024 * 1024,
+        env: { ...process.env, PAGER: 'cat' },
+        signal: opts.signal,
+      },
       (error, stdout, stderr) => {
         const exitCode = error ? (typeof error.code === 'number' ? error.code : 1) : 0
         resolve({ ok: exitCode === 0, stdout: stdout ?? '', stderr: stderr ?? '', exitCode })
@@ -175,6 +185,7 @@ export function runGit(
 export async function resolveChangedFiles(
   root: string,
   targetBranch: string,
+  opts: { signal?: AbortSignal } = {},
 ): Promise<GitScopeResult> {
   // Option-injection guard: a branch name starting with '-' would be parsed by
   // git as an option (e.g. --output=...), not a ref. Reject it outright.
@@ -188,7 +199,7 @@ export async function resolveChangedFiles(
   }
   // -z: NUL-delimited names — machine-safe for any filename (spaces, quotes,
   // non-ASCII), and never confused with option-like content.
-  const { ok, stdout, stderr } = await runGit(['diff', '--name-only', '-z', targetBranch, '--'], root)
+  const { ok, stdout, stderr } = await runGit(['diff', '--name-only', '-z', targetBranch, '--'], root, opts)
   if (!ok) {
     const reason = stderr.trim() || `git diff --name-only -z ${targetBranch} failed`
     return { scope: 'full', changedFiles: [], fallbackToFull: true, error: reason }

package/src/jobs.ts

@@ -39,6 +39,20 @@ interface JobsLike {
   }): string
 }
 
+/**
+ * Read `ctx.jobs` defensively: the dsh plugin context can be a Proxy whose
+ * `jobs` getter throws (or is missing) when no job registry is present. A
+ * Proxy throw on property access must degrade to "no jobs", never crash the
+ * tool execution we are about to wrap.
+ */
+function safeJobs(ctx: unknown): JobsLike | undefined {
+  try {
+    return (ctx as { jobs?: JobsLike } | undefined)?.jobs
+  } catch {
+    return undefined
+  }
+}
+
 /**
  * Run `fn` wrapped in a dsh background job, settling it completed/failed
  * with the execution's outcome. When the host exposes no job registry (or
@@ -57,7 +71,7 @@ export async function runWithJob<T>(
   label: string,
   fn: () => Promise<T> | T,
 ): Promise<{ result: T; jobId: string | null }> {
-  const jobs = (ctx as { jobs?: JobsLike } | undefined)?.jobs
+  const jobs = safeJobs(ctx)
   if (!jobs || typeof jobs.start !== 'function') {
     return { result: await fn(), jobId: null }
   }

package/src/live.ts

@@ -68,6 +68,47 @@ export function liveFilePath(projectRoot: string): string {
   return join(projectRoot, '.iterate', 'transcript-live.ndjson')
 }
 
+/**
+ * Module-level in-process queue serializing live-feed writes. The trim path
+ * (read → rewrite → append) is a read-modify-write: two concurrent tool
+ * results could interleave and one's rewrite would silently drop the other's
+ * freshly-appended line. Chaining every append onto one tail makes the whole
+ * read+rewrite+append atomic within the process (the only realistic mode for
+ * the plugin); cross-process racing remains a theoretical hazard, but the
+ * cap-trim makes a lost line a cosmetic issue, not a correctness one.
+ */
+let liveWriteQueue: Promise<void> = Promise.resolve()
+
+function enqueueLiveWrite(task: () => Promise<void>): Promise<void> {
+  const next = liveWriteQueue.then(task, task)
+  liveWriteQueue = next.catch(() => {})
+  return next
+}
+
+/** Append one activity record to the project's live feed (byte-capped). */
+export function appendLive(projectRoot: string, entry: LiveActivityEntry): Promise<void> {
+  return enqueueLiveWrite(async () => {
+    const file = liveFilePath(projectRoot)
+    const line = JSON.stringify(entry) + '\n'
+    await mkdir(join(projectRoot, '.iterate'), { recursive: true })
+    // Amortized O(1): only read+rewrite when the file has grown past the cap.
+    try {
+      const st = await stat(file).catch(() => null)
+      if (st && st.size > LIVE_MAX_BYTES) {
+        const raw = await readFile(file, 'utf-8')
+        const lines = raw.split('\n').filter(Boolean)
+        const tail = lines.slice(-LIVE_MAX_ENTRIES)
+        // Atomic rewrite (unique temp + rename) so a crash mid-trim never
+        // truncates the live feed; the temp file is prunable by iterate_prune.
+        await writeTextAtomicAsync(file, tail.join('\n') + '\n')
+      }
+      await appendFile(file, line, 'utf-8')
+    } catch {
+      // Fire-and-forget: never let live capture break a tool call.
+    }
+  })
+}
+
 /** Resolve the project root a tool execution belongs to, if any. */
 function projectRootOf(exec: ToolExecution): string | null {
   const cwd = exec.agent?.session?.header?.cwd
@@ -130,28 +171,6 @@ export function classifyTool(
   return { ts: new Date().toISOString(), type, tool: name, target }
 }
 
-/** Append one activity record to the project's live feed (byte-capped). */
-export async function appendLive(projectRoot: string, entry: LiveActivityEntry): Promise<void> {
-  const file = liveFilePath(projectRoot)
-  const line = JSON.stringify(entry) + '\n'
-  await mkdir(join(projectRoot, '.iterate'), { recursive: true })
-  // Amortized O(1): only read+rewrite when the file has grown past the cap.
-  try {
-    const st = await stat(file).catch(() => null)
-    if (st && st.size > LIVE_MAX_BYTES) {
-      const raw = await readFile(file, 'utf-8')
-      const lines = raw.split('\n').filter(Boolean)
-      const tail = lines.slice(-LIVE_MAX_ENTRIES)
-      // Atomic rewrite (unique temp + rename) so a crash mid-trim never
-      // truncates the live feed; the temp file is prunable by iterate_prune.
-      await writeTextAtomicAsync(file, tail.join('\n') + '\n')
-    }
-    await appendFile(file, line, 'utf-8')
-  } catch {
-    // Fire-and-forget: never let live capture break a tool call.
-  }
-}
-
 /** Read the live feed (newest first), capped at the last LIVE_MAX_ENTRIES. */
 export async function readLive(projectRoot: string): Promise<LiveActivityEntry[]> {
   const file = liveFilePath(projectRoot)

package/src/meta-review.ts

@@ -184,7 +184,7 @@ export function metaReviewReport(report: ReviewReport): MetaReviewResult {
       `byDimension sums to ${dimSum}, but totalFindings is ${total}.`,
     )
   }
-  const invalidDim = findings.find((f) => !dimensions.includes(f?.dimension))
+  const invalidDim = findings.find((f) => !!f && !dimensions.includes(f?.dimension))
   if (invalidDim) {
     add(
       'DIMENSION_UNKNOWN',
@@ -233,7 +233,11 @@ export function metaReviewReport(report: ReviewReport): MetaReviewResult {
       : null
   const lastRoundNew =
     lastRecordedRound !== null && lastRecordedRound > 0
-      ? Number(findingsByRound[lastRecordedRound - 1] ?? 0)
+      // Over-cap rounds are FOLDED by aggregateRounds into the final slot, so a
+      // reported round number may exceed the array length — read the SAME
+      // clamped index buildReviewReport/computeConvergence use, or a real
+      // over-cap round would be mis-read as 0 new (flag mismatch).
+      ? Number(findingsByRound[Math.min(lastRecordedRound, findingsByRound.length) - 1] ?? 0)
       : null
   const expectedConverged = lastRoundNew === 0
   if (report.convergence?.converged !== expectedConverged) {
@@ -364,7 +368,7 @@ export function buildFinalReviewReport(
           // surfaced it (best-effort; report rounds carry it).
           for (const r of report.rounds ?? []) {
             const matched = (r.findings ?? []).some(
-              (fnd) => fnd.file === violation.file && fnd.line === violation.line,
+              (fnd) => !!fnd && fnd?.file === violation.file && fnd?.line === violation.line,
             )
             if (matched) {
               roundHint = ` (round ${r.round})`

package/src/review-scope.ts

@@ -72,8 +72,12 @@ function normalizePath(path: string): string {
   for (const part of cleaned.split(SEP)) {
     if (part === '' || part === '.') continue
     if (part === '..') {
-      if (parts.length > 0) parts.pop()
-      else parts.push(part) // no root segment to pop — keep the leading '..'
+      // Mirrors Python `os.path.normpath`: a leading `..` is preserved and a
+      // second `..` is NEVER collapsed into a bare `/` away — otherwise a
+      // traversal like `../../evil` folds into the single segment `evil` and
+      // the escape becomes undetectable downstream.
+      if (parts.length > 0 && parts[parts.length - 1] !== '..') parts.pop()
+      else parts.push(part)
       continue
     }
     parts.push(part)