iterate-plugin 3.5.3 → 3.5.5

package/lib/client.js

@@ -465,6 +465,10 @@ function normalizeTranscript(manifest) {
     phases: asArray(safeGet(src, "phases")).map((p) => typeof p === "string" ? p : ""),
     round: asNum(safeGet(src, "round")),
     maxRounds: asNum(safeGet(src, "maxRounds")),
+    // v3.5: why a FINISHED run stopped (converged / max_rounds_reached /
+    // aborted_by_validation / aborted_by_config). Required for the
+    // observatory badge to render the stop reason instead of a bare "已结束".
+    stoppedReason: src.stoppedReason === null || src.stoppedReason === void 0 ? null : asStr(safeGet(src, "stoppedReason")) || null,
     rounds,
     convergence: asArray(safeGet(src, "convergence")).map((n) => asCount(n)),
     findings: asArray(safeGet(src, "findings")).map((f) => ({ ...f })),
@@ -941,18 +945,25 @@ function computeConvergenceProgress(report) {
     report.convergence ?? {}
   );
   const totalRounds = typeof convergence.totalRounds === "number" ? convergence.totalRounds : 1;
-  const currentRounds = (
-    /** @type {Array<unknown>} */
-    (report.rounds ?? []).length
-  );
+  const currentRounds = currentRoundNumber(report);
   if (!(totalRounds > 0)) return 0;
   return Math.min(100, Math.round(currentRounds / totalRounds * 100));
 }
-function getCurrentRound(report) {
-  return (
-    /** @type {Array<unknown>} */
-    (report.rounds ?? []).length
+function currentRoundNumber(report) {
+  const rounds = (
+    /** @type {Array<Record<string, unknown>>} */
+    report.rounds ?? []
   );
+  let max = 0;
+  for (const r of rounds) {
+    if (!r || typeof r !== "object") continue;
+    const n = Number(r.round);
+    if (Number.isFinite(n) && n > max) max = n;
+  }
+  return rounds.length > 0 && max === 0 ? rounds.length : max;
+}
+function getCurrentRound(report) {
+  return currentRoundNumber(report);
 }
 function getTotalRounds(report) {
   const convergence = (
@@ -1713,6 +1724,25 @@ function severityColor(severity) {
 function severityLabel(severity) {
   return SEVERITY_LABEL[coerceSeverity(severity)];
 }
+function stoppedReasonLabel(reason) {
+  switch (reason) {
+    case "converged":
+      return "\u5DF2\u7ED3\u675F \xB7 \u5DF2\u6536\u655B\uFF08\u65E0\u65B0\u53D1\u73B0\uFF09";
+    case "max_rounds_reached":
+      return "\u5DF2\u7ED3\u675F \xB7 \u8FBE\u5230\u8F6E\u6570\u4E0A\u9650";
+    case "aborted_by_validation":
+      return "\u5DF2\u7ED3\u675F \xB7 \u9A8C\u8BC1\u5931\u8D25\u540E\u56DE\u6EDA\u505C\u6B62";
+    case "aborted_by_config":
+      return "\u5DF2\u7ED3\u675F \xB7 \u9A8C\u8BC1\u547D\u4EE4\u4E0D\u5728\u767D\u540D\u5355\uFF08\u914D\u7F6E\u9700\u4FEE\u590D\uFF09";
+    default:
+      return reason ? `\u5DF2\u7ED3\u675F \xB7 ${reason}` : "\u5DF2\u7ED3\u675F";
+  }
+}
+function runStatusText(live, manifest) {
+  if (live) return "\u8FD0\u884C\u4E2D";
+  const reason = manifest && typeof manifest.stoppedReason === "string" ? manifest.stoppedReason : "";
+  return reason ? stoppedReasonLabel(reason) : "\u5DF2\u7ED3\u675F";
+}
 function readSlots(ctx) {
   if (ctx && ctx.slots && typeof ctx.slots.inject === "function" && typeof ctx.slots.register === "function") {
     return ctx.slots;
@@ -1858,7 +1888,7 @@ function ConvergenceDashboard(props) {
     key: "phase",
     "data-live": transcript.active === true ? "" : void 0,
     title: transcript.active === true ? `\u5F53\u524D\u5904\u4E8E\u300C${phase}\u300D\u9636\u6BB5\uFF08\u8FD0\u884C\u4E2D\uFF09` : `\u6700\u8FD1\u4E00\u6B21\u6267\u884C\u505C\u7559\u5728\u300C${phase}\u300D\u9636\u6BB5\uFF08\u5DF2\u7ED3\u675F\uFF09`
-  }, `${phase} \xB7 ${transcript.active === true ? "\u8FD0\u884C\u4E2D" : "\u5DF2\u7ED3\u675F"}`) : null;
+  }, `${phase} \xB7 ${runStatusText(transcript.active === true, transcript)}`) : null;
   const taskModeTranscript = latestTranscript(session);
   const taskMode = taskModeTranscript?.taskMode;
   const taskModeChip = taskMode ? React.createElement("span", {
@@ -3171,7 +3201,7 @@ ${JSON.stringify({ operation: "nudge", text: null }, null, 2)}
         "div",
         { className: "iterate-obs-block-head" },
         React.createElement("span", {}, "\u8FD0\u884C\u63A7\u5236\u53F0"),
-        React.createElement("span", { className: "iterate-obs-badge", "data-live": live ? "" : void 0 }, live ? "\u8FD0\u884C\u4E2D" : "\u5DF2\u7ED3\u675F"),
+        React.createElement("span", { className: "iterate-obs-badge", "data-live": live ? "" : void 0 }, runStatusText(live, manifest)),
         React.createElement("span", { className: "iterate-obs-head-meta" }, `\u6279\u51C6\u7B56\u7565\uFF1A${policyLabel}`)
       ),
       React.createElement(
@@ -3767,7 +3797,7 @@ ${JSON.stringify({ operation: "clear" }, null, 2)}
       "div",
       { className: "iterate-obs-head", "data-closed": open ? void 0 : "", onClick: () => setOpen((v) => !v) },
       React.createElement("span", { className: "iterate-obs-title" }, "iterate \u89C2\u6D4B\u53F0"),
-      React.createElement("span", { className: "iterate-obs-badge", "data-live": live ? "" : void 0 }, live ? "\u8FD0\u884C\u4E2D" : "\u5DF2\u7ED3\u675F"),
+      React.createElement("span", { className: "iterate-obs-badge", "data-live": live ? "" : void 0 }, runStatusText(live, manifest)),
       React.createElement("span", { className: "iterate-obs-head-meta" }, headMeta || "runtime"),
       React.createElement("button", {
         className: "iterate-btn",

package/lib/parse.js

@@ -581,6 +581,12 @@ export function normalizeTranscript(manifest) {
     phases: asArray(safeGet(src, 'phases')).map((p) => (typeof p === 'string' ? p : '')),
     round: asNum(safeGet(src, 'round')),
     maxRounds: asNum(safeGet(src, 'maxRounds')),
+    // v3.5: why a FINISHED run stopped (converged / max_rounds_reached /
+    // aborted_by_validation / aborted_by_config). Required for the
+    // observatory badge to render the stop reason instead of a bare "已结束".
+    stoppedReason: src.stoppedReason === null || src.stoppedReason === undefined
+      ? null
+      : asStr(safeGet(src, 'stoppedReason')) || null,
     rounds,
     convergence: asArray(safeGet(src, 'convergence')).map((n) => asCount(n)),
     findings: asArray(safeGet(src, 'findings')).map((f) => ({ ...f })),
@@ -1217,12 +1223,34 @@ export function computeConvergenceProgress(report) {
   const totalRounds = typeof convergence.totalRounds === 'number'
     ? convergence.totalRounds
     : 1
-  const currentRounds = /** @type {Array<unknown>} */ (report.rounds ?? []).length
+  const currentRounds = currentRoundNumber(report)
   // Guard against an empty report (totalRounds <= 0) producing NaN.
   if (!(totalRounds > 0)) return 0
   return Math.min(100, Math.round((currentRounds / totalRounds) * 100))
 }
 
+/**
+ * The actual current round (1-indexed) carried by a report. Uses the highest
+ * per-round `round` field: a normal-mode aggregate ships ONLY the live round
+ * (`rounds: [{round: r, ...}]`), so `rounds.length` would be stuck at 1 while
+ * the run is on round 3. Dry-run aggregates ship the cumulative list, where
+ * the round numbers and the array length agree anyway.
+ *
+ * @param {Record<string, unknown>} report
+ * @returns {number}
+ */
+function currentRoundNumber(report) {
+  const rounds = /** @type {Array<Record<string, unknown>>} */ (report.rounds ?? [])
+  let max = 0
+  for (const r of rounds) {
+    if (!r || typeof r !== 'object') continue
+    const n = Number(r.round)
+    if (Number.isFinite(n) && n > max) max = n
+  }
+  // Fallback: no usable round numbers → array length (covers all-0 rounds).
+  return rounds.length > 0 && max === 0 ? rounds.length : max
+}
+
 /**
  * Get the current round number (1-indexed) from a report.
  *
@@ -1230,7 +1258,7 @@ export function computeConvergenceProgress(report) {
  * @returns {number}
  */
 export function getCurrentRound(report) {
-  return (/** @type {Array<unknown>} */ (report.rounds ?? [])).length
+  return currentRoundNumber(report)
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "3.5.3",
+  "version": "3.5.5",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness with quality command center and experience bank (v3.3). Features: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus dry-run pure-review mode, quality gate compute/persist, writable experience bank, defense events stream (record + bilingual labels), and native command buttons — with a live quality command center (F8/F9/F10 render real session data), §8 assign-fix instruction, and task_mode indicator wired end to end.",
   "type": "module",
   "license": "MIT",
@@ -37,7 +37,9 @@
         "0.1.5-alpha.1": "compatible",
         "0.1.5-alpha.2": "compatible",
         "0.1.5-rc.1": "compatible",
-        "0.1.5-rc.2": "compatible"
+        "0.1.5-rc.2": "compatible",
+        "0.1.6-alpha.1": "compatible",
+        "0.1.6-alpha.2": "compatible"
       }
     },
     "client": {
@@ -75,13 +77,14 @@
   },
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/dsh-tools": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-util-values": "0.1.5-rc.2",
-    "js-yaml": "4.3.1"
+    "@deepseek-ai/dsh-tools": "0.1.6-alpha.2",
+    "@deepseek-ai/dsh-util-values": "0.1.6-alpha.2",
+    "js-yaml": "4.3.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-jobs": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-agent": "0.1.6-alpha.2",
+    "@deepseek-ai/dsh-jobs": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-session": "0.1.6-alpha.2",
     "@types/js-yaml": "4.0.9",
     "@types/node": "22.15.0",
     "@types/react": "19.2.2",

package/src/atomic-fs.ts

@@ -54,11 +54,19 @@ function tempPathFor(filePath: string): string {
  */
 export function writeTextAtomic(filePath: string, data: string): void {
   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
   }
@@ -67,11 +75,19 @@ export function writeTextAtomic(filePath: string, data: string): void {
 /** Async variant of {@link writeTextAtomic} (same temp naming convention). */
 export async function writeTextAtomicAsync(filePath: string, data: string): Promise<void> {
   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/src/client/index.ts

@@ -244,6 +244,8 @@ interface ObsManifest {
   timeline?: ObsEntry[]
   nudge?: ObsNudge | null
   approval?: ObsApproval
+  /** Why the run ended: converged / max_rounds_reached / aborted_by_validation. */
+  stoppedReason?: string | null
 }
 
 // ─── Quality command center data types (v3.1+; mirrors src/types.ts) ────────
@@ -735,6 +737,24 @@ 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 '运行中'
+  const reason = manifest && typeof manifest.stoppedReason === 'string' ? manifest.stoppedReason : ''
+  return reason ? stoppedReasonLabel(reason) : '已结束'
+}
+
 /** Resolve the slots service: prefer the typed `ctx.slots`, fall back to `ctx.get`. */
 function readSlots(ctx: ClientContext): SlotsService | undefined {
   if (ctx && ctx.slots && typeof ctx.slots.inject === 'function' && typeof ctx.slots.register === 'function') {
@@ -940,7 +960,7 @@ function ConvergenceDashboard(props: SlotProps) {
         title: transcript.active === true
           ? `当前处于「${phase}」阶段（运行中）`
           : `最近一次执行停留在「${phase}」阶段（已结束）`,
-      }, `${phase} · ${transcript.active === true ? '运行中' : '已结束'}`)
+      }, `${phase} · ${runStatusText(transcript.active === true, transcript)}`)
     : null
 
   // v3.0: task_mode indicator (code/iterate)
@@ -2224,7 +2244,7 @@ function ObservatoryPanel(props: SlotProps) {
     return React.createElement('div', { className: 'iterate-obs-block' },
       React.createElement('div', { className: 'iterate-obs-block-head' },
         React.createElement('span', {}, '运行控制台'),
-        React.createElement('span', { className: 'iterate-obs-badge', 'data-live': live ? '' : undefined }, live ? '运行中' : '已结束'),
+        React.createElement('span', { className: 'iterate-obs-badge', 'data-live': live ? '' : undefined }, runStatusText(live, manifest)),
         React.createElement('span', { className: 'iterate-obs-head-meta' }, `批准策略：${policyLabel}`),
       ),
       React.createElement('div', { className: 'iterate-obs-block-body' },
@@ -2731,7 +2751,7 @@ function ObservatoryPanel(props: SlotProps) {
   return React.createElement('div', { 'data-iterate-root': '', 'data-iterate': 'obs', className: 'iterate-obs' },
     React.createElement('div', { className: 'iterate-obs-head', 'data-closed': open ? undefined : '', onClick: () => setOpen((v) => !v) },
       React.createElement('span', { className: 'iterate-obs-title' }, 'iterate 观测台'),
-      React.createElement('span', { className: 'iterate-obs-badge', 'data-live': live ? '' : undefined }, live ? '运行中' : '已结束'),
+      React.createElement('span', { className: 'iterate-obs-badge', 'data-live': live ? '' : undefined }, runStatusText(live, manifest)),
       React.createElement('span', { className: 'iterate-obs-head-meta' }, headMeta || 'runtime'),
       React.createElement('button', {
         className: 'iterate-btn', 'data-ghost': '',

package/src/config-loader.ts

@@ -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,7 +209,9 @@ 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')) {

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,46 @@ 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
+
+/** 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 +85,11 @@ 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 ('review' in updates) {
@@ -62,11 +105,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 +211,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 +253,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

@@ -125,8 +125,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',
@@ -364,7 +364,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})`