iterate-plugin 3.5.4 → 3.5.6

package/dist/atomic-fs.js

@@ -48,12 +48,21 @@ function tempPathFor(filePath) {
  */
 export function writeTextAtomic(filePath, data) {
     const tmp = tempPathFor(filePath);
-    writeFileSync(tmp, data, 'utf-8');
+    try {
+        writeFileSync(tmp, data, 'utf-8');
+    }
+    catch (err) {
+        // The write itself failed (disk full, permission, …): the temp file may
+        // already be partially written, so remove it before propagating — a
+        // failed write must never litter the directory either.
+        cleanupTemp(tmp);
+        throw err;
+    }
     try {
         renameSync(tmp, filePath);
     }
     catch (err) {
-        // Best-effort temp cleanup so a failed write never litters the directory.
+        // Best-effort temp cleanup so a failed rename never litters the directory.
         cleanupTemp(tmp);
         throw err;
     }
@@ -61,12 +70,21 @@ export function writeTextAtomic(filePath, data) {
 /** Async variant of {@link writeTextAtomic} (same temp naming convention). */
 export async function writeTextAtomicAsync(filePath, data) {
     const tmp = tempPathFor(filePath);
-    await writeFile(tmp, data, 'utf-8');
+    try {
+        await writeFile(tmp, data, 'utf-8');
+    }
+    catch (err) {
+        // The write itself failed (disk full, permission, …): the temp file may
+        // already be partially written, so remove it before propagating — a
+        // failed write must never litter the directory either.
+        await cleanupTempAsync(tmp);
+        throw err;
+    }
     try {
         await rename(tmp, filePath);
     }
     catch (err) {
-        // Best-effort temp cleanup so a failed write never litters the directory.
+        // Best-effort temp cleanup so a failed rename never litters the directory.
         await cleanupTempAsync(tmp);
         throw err;
     }

package/dist/config-loader.js

@@ -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';
@@ -10,7 +10,10 @@ export function loadConfig(projectRoot) {
     try {
         const content = readFileSync(join(projectRoot, 'iterate.config.yaml'), 'utf-8');
         const parsed = yaml.load(content);
-        if (!parsed || typeof parsed !== 'object')
+        // 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;
     }
@@ -141,7 +144,7 @@ export function flattenCommands(commands) {
  */
 export function validateConfig(config) {
     const errors = [];
-    if (!config || typeof config !== 'object') {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
         errors.push('root');
         return errors;
     }
@@ -190,13 +193,35 @@ export function validateConfig(config) {
  *      the DSH runtime injects per-session env into tool sub-processes).
  */
 export function resolveProjectRoot(input, sessionCwd) {
-    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/dist/config-write.js

@@ -9,8 +9,8 @@
  * The security posture mirrors the triage tool: never overwrite a malformed
  * 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.js";
 /** Config file name (must match config-loader). */
@@ -19,6 +19,41 @@ export const CONFIG_FILE = 'iterate.config.yaml';
 export function configBackupSuffix(now = new Date()) {
     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, keep = MAX_CONFIG_BACKUPS) {
+    const removed = [];
+    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).
@@ -40,8 +75,35 @@ export function validateConfigUpdates(updates) {
         }
     }
     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;
+        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']) {
+                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) {
@@ -59,11 +121,11 @@ export function validateConfigUpdates(updates) {
             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}`);
             }
         }
     }
@@ -164,7 +226,10 @@ export function readRawConfig(configPath) {
     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;
@@ -201,5 +266,9 @@ export function writeConfigFile(projectRoot, config) {
         }
         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/dist/evidence.js

@@ -83,14 +83,45 @@ export function verifyLineBounds(line, text) {
     if (line === undefined || line === null || line === WHOLE_FILE_LINE) {
         return { inBounds: true, lineTotal };
     }
-    if (line < 1)
+    // 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 };
 }
 /** Verify a single finding's location against the real filesystem. */
 export function verifyFinding(root, input, opts = {}) {
-    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)) {
         return {

package/dist/git-scope.js

@@ -89,7 +89,10 @@ function decodeQuotedPath(content) {
 }
 export function parseChangedFiles(stdout) {
     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')
@@ -147,9 +150,15 @@ export function decideScope(changedFiles) {
  * Uses execFile (no shell), so a model-controlled branch name can never be
  * interpreted as shell syntax.
  */
-export function runGit(args, cwd) {
+export function runGit(args, cwd, opts = {}) {
     return new Promise((resolve) => {
-        execFile('git', args, { cwd, timeout: 30_000, maxBuffer: 10 * 1024 * 1024, env: { ...process.env, PAGER: 'cat' } }, (error, stdout, stderr) => {
+        execFile('git', args, {
+            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 });
         });
@@ -161,7 +170,7 @@ export function runGit(args, cwd) {
  * `full`-scope result with `error` set — the reviewer must never crash the
  * plan because git is unavailable.
  */
-export async function resolveChangedFiles(root, targetBranch) {
+export async function resolveChangedFiles(root, targetBranch, opts = {}) {
     // 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.
     if (typeof targetBranch !== 'string' || targetBranch.trim() === '' || targetBranch.startsWith('-')) {
@@ -174,7 +183,7 @@ export async function resolveChangedFiles(root, targetBranch) {
     }
     // -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/dist/jobs.js

@@ -16,6 +16,20 @@
  * - The registry is memory-only and panel rows are read-only (no progress
  *   updates), so these jobs are completion records, not control channels.
  */
+/**
+ * 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) {
+    try {
+        return ctx?.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
@@ -29,7 +43,7 @@
  * @returns the registry-issued job id, or `null` when unavailable.
  */
 export async function runWithJob(ctx, kind, label, fn) {
-    const jobs = ctx?.jobs;
+    const jobs = safeJobs(ctx);
     if (!jobs || typeof jobs.start !== 'function') {
         return { result: await fn(), jobId: null };
     }

package/dist/live.js

@@ -36,6 +36,45 @@ export const LIVE_MAX_BYTES = 64 * 1024;
 export function liveFilePath(projectRoot) {
     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.resolve();
+function enqueueLiveWrite(task) {
+    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, entry) {
+    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) {
     const cwd = exec.agent?.session?.header?.cwd;
@@ -95,28 +134,6 @@ export function classifyTool(name, args, projectRoot) {
         target = name;
     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, entry) {
-    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) {
     const file = liveFilePath(projectRoot);

package/dist/meta-review.js

@@ -99,7 +99,7 @@ export function metaReviewReport(report) {
     if (dimSum !== total) {
         add('DIMENSION_SUM', 'high', 'byDimension counts do not sum to totalFindings', `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', 'medium', `Finding references unknown dimension "${invalidDim.dimension}"`, `dimension "${invalidDim.dimension}" is not in report.dimensions ` +
             `(${dimensions.join(', ') || 'none'}).`);
@@ -129,7 +129,11 @@ export function metaReviewReport(report) {
         ? reportRounds[reportRounds.length - 1].round
         : 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) {
@@ -227,7 +231,7 @@ export function buildFinalReviewReport(report, opts = {}) {
                     // 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((fnd) => fnd.file === violation.file && fnd.line === violation.line);
+                        const matched = (r.findings ?? []).some((fnd) => !!fnd && fnd?.file === violation.file && fnd?.line === violation.line);
                         if (matched) {
                             roundHint = ` (round ${r.round})`;
                             break;

package/dist/review-scope.js

@@ -57,10 +57,14 @@ function normalizePath(path) {
         if (part === '' || part === '.')
             continue;
         if (part === '..') {
-            if (parts.length > 0)
+            // 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); // no root segment to pop — keep the leading '..'
+                parts.push(part);
             continue;
         }
         parts.push(part);

package/dist/review.js

@@ -28,19 +28,20 @@ export const SEVERITY_RANK = {
 export function sortFindings(findings) {
     return [...findings].sort((a, b) => {
         // Guard against an out-of-spec severity string (e.g. from a model that
-        // bypassed the schema): treat it as the least severe so NaN never enters
-        // the comparator and ordering stays deterministic.
-        const rankA = SEVERITY_RANK[a.severity] ?? SEVERITY_RANK.low;
-        const rankB = SEVERITY_RANK[b.severity] ?? SEVERITY_RANK.low;
+        // bypassed the schema) AND against a null list element (model-authored
+        // JSON): treat both as the least severe so NaN never enters the
+        // comparator and ordering stays deterministic.
+        const rankA = SEVERITY_RANK[a?.severity] ?? SEVERITY_RANK.low;
+        const rankB = SEVERITY_RANK[b?.severity] ?? SEVERITY_RANK.low;
         const bySeverity = rankA - rankB;
         if (bySeverity !== 0)
             return bySeverity;
         // 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 ?? ''));
+        const byFile = String(a?.file ?? '').localeCompare(String(b?.file ?? ''));
         if (byFile !== 0)
             return byFile;
-        return (Number(a.line) || 0) - (Number(b.line) || 0);
+        return (Number(a?.line) || 0) - (Number(b?.line) || 0);
     });
 }
 /** Normalize a summary so near-identical duplicates collapse to one key. */
@@ -143,14 +144,17 @@ export function aggregateRounds(rounds, maxReviewRounds) {
     }
     // 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 = [];
-    for (let r = 1; r <= effectiveMax; r++) {
-        let count = 0;
-        for (const key of firstRoundByKey.keys()) {
-            if (firstRoundByKey.get(key) === r)
-                count++;
-        }
-        findingsByRound.push(count);
+    const findingsByRound = new Array(effectiveMax).fill(0);
+    for (const key of firstRoundByKey.keys()) {
+        const firstRound = firstRoundByKey.get(key) ?? 1;
+        // Fold rounds BEYOND the allocation bound into the highest slot instead of
+        // dropping them: a finding first seen in an over-cap round was previously
+        // invisible to `findingsByRound`, so a run whose final rounds exceeded the
+        // cap looked "converged" even though a real round found new issues. Folding
+        // keeps the counts truthful (the sum still equals totalFindings) while the
+        // memory bound stays fixed.
+        const idx = Math.min(firstRound, effectiveMax) - 1;
+        findingsByRound[idx] = (findingsByRound[idx] || 0) + 1;
     }
     return { findings: dedupeFindings(merged), findingsByRound, firstRoundByKey };
 }
@@ -245,7 +249,12 @@ export function buildReviewReport(input) {
         if (typeof r.round === 'number' && r.round > lastRound)
             lastRound = r.round;
     }
-    const lastRoundCount = lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0;
+    // `lastRound` can exceed the array length when over-cap rounds were FOLDED
+    // into the last slot (see aggregateRounds). Read the same clamped index
+    // computeConvergence uses, so a real over-cap round is never mis-read as 0
+    // new findings (which would falsely report "converged").
+    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;
     // Attach the normal-mode fix count to the summary (dry-run leaves it absent).
     const computed = summarize(sorted);
@@ -516,6 +525,9 @@ export function attachmentClause(attachments) {
 export function reviewerTaskPrompt(input) {
     const parts = [];
     parts.push(`You are the "${input.dimension}" reviewer for the iterate review.`, `Goal: ${input.goal}`, `Scope: ${input.scope === 'full' ? 'entire codebase' : 'changed files only'}.`);
+    if (input.effort) {
+        parts.push(`Reasoning effort for this review pass: ${input.effort}.`);
+    }
     if (input.focus) {
         parts.push(`FOCUS: ${input.focus}`);
     }
@@ -573,6 +585,11 @@ export function buildReviewPlan(input) {
     const language = input.config.language === 'zh' ? 'Chinese (中文)' : 'English';
     const goal = input.config.goal ?? '';
     const configuredScope = input.config.review?.scope ?? 'full';
+    const reasoningEffort = input.config.reasoning_effort === 'low' ||
+        input.config.reasoning_effort === 'medium' ||
+        input.config.reasoning_effort === 'high'
+        ? input.config.reasoning_effort
+        : null;
     const dimensions = Array.isArray(input.config.dimensions) ? input.config.dimensions : [];
     const maxLines = input.config.atomic?.max_lines ?? 20;
     const changedFiles = Array.isArray(input.changedFiles) ? input.changedFiles : [];
@@ -631,6 +648,7 @@ export function buildReviewPlan(input) {
                     scopeFiles: batch,
                     focus: focusMap.get(d),
                     attachments,
+                    effort: reasoningEffort ?? undefined,
                 }),
                 findingsSchema: findingsSchema(),
             });
@@ -646,5 +664,6 @@ export function buildReviewPlan(input) {
         changedFiles: effectiveChangedOnly ? changedFiles : [],
         fallbackToFull,
         attachments,
+        reasoningEffort,
     };
 }