iterate-plugin 3.7.0 → 3.9.0

package/lib/parse.js

@@ -2281,8 +2281,17 @@ export function stoppedReasonLabel(reason, lang = 'zh') {
     schema_invalid: 'Done \u00b7 repeated schema validation failures in review output',
     no_usable_reviewer_output: 'Done \u00b7 no usable review output',
   }
-  if (lang === 'en') return en[reason] ?? (reason ? `Done \u00b7 ${reason}` : 'Done')
-  return zh[reason] ?? (reason ? `已结束 · ${reason}` : '已结束')
+  // Object.hasOwn, NOT `zh[reason]`: a model/hand-edited `stoppedReason` of
+  // `__proto__` / `constructor` / `toString` would otherwise resolve through
+  // the PROTOTYPE CHAIN to Object.prototype or a function (never a string) and
+  // crash React ("Objects are not valid as a React child") when the badge
+  // renders it. An own-key hit is the only way to return a table value; any
+  // other value degrades to a plain text label.
+  const table = lang === 'en' ? en : zh
+  if (typeof reason === 'string' && Object.hasOwn(table, reason)) return table[reason]
+  const text = typeof reason === 'string' && reason !== '' ? reason : ''
+  if (lang === 'en') return text ? `Done \u00b7 ${text}` : 'Done'
+  return text ? `已结束 · ${text}` : '已结束'
 }
 
 // ─── Completion notification ────────────────────────────────────────────────
@@ -2391,8 +2400,9 @@ export function buildConfigEditGuide() {
     '---------------------',
     '配置文件：项目根目录 iterate.config.yaml。',
     '',
-    '⚠ 未配置 validation.commands 时迭代不被保护：每轮 validate 拿到空结果会被当作',
-    '  “验证通过”，等于在没有任何测试保护的情况下继续收敛。第一次启动迭代前，',
+    '⚠ 未配置 validation.commands 时迭代不被保护：该轮会直接中止（fail-closed），',
+    '  空验证结果/验证未执行绝不当作“验证通过”，运行以 converged_unverified /',
+    '  aborted_by_config 收尾而不是 plain converged。第一次启动迭代前，',
     '  请先给 validation.commands 配上至少一条真实命令（如 npm test）。',
     '',
     '可编辑字段：',
@@ -2789,14 +2799,19 @@ function pickExportExtras(extra) {
  * One row per round: findings raised, findings fixed, severity mix and the
  * validation command outcomes recorded on the manifest.
  *
+ * `fixed` counts SUCCESSFUL fixes applied in that round, taken from the
+ * transcript's `fixes` (each `{ round, success }`) — the review `findings`
+ * schema carries no `status`, so reading `f.status` here always yielded 0.
+ *
  * Cross-*session* comparison is intentionally out of scope — that is what the
  * #4 pull instruction is for (see `buildDiskSnapshotInstruction`).
  *
  * @param {unknown} report
  * @param {unknown} validations
+ * @param {unknown} [fixes] transcript fixes (`{round, success}[]`) for the fixed counts
  * @returns {Array<{round: number, findings: number, fixed: number, severities: Record<string, number>, validations: Array<{command: string, exitCode: number|null, allowed: boolean}>}>}
  */
-export function buildRoundComparison(report, validations) {
+export function buildRoundComparison(report, validations, fixes) {
   const rounds = new Map()
   const rowsFor = (round) => {
     const n = Number(round)
@@ -2814,7 +2829,15 @@ export function buildRoundComparison(report, validations) {
     row.findings += 1
     const sev = typeof f.severity === 'string' && f.severity ? f.severity : 'unknown'
     row.severities[sev] = (row.severities[sev] || 0) + 1
-    if (f.status === 'fixed') row.fixed += 1
+  }
+
+  // Fixed counts come from applied fixes (real data), not a finding `status`
+  // the findings schema never produces.
+  const fixList = Array.isArray(fixes) ? fixes : []
+  for (const fx of fixList) {
+    if (!fx || typeof fx !== 'object') continue
+    if ((/** @type {Record<string, unknown>} */ (fx)).success !== true) continue
+    rowsFor((/** @type {Record<string, unknown>} */ (fx)).round).fixed += 1
   }
 
   const vals = Array.isArray(validations) ? validations : []

package/package.json

@@ -1,17 +1,16 @@
 {
   "name": "iterate-plugin",
-  "version": "3.7.0",
+  "version": "3.9.0",
   "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",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jingzhao-l/iterate-skill.git",
-    "directory": "harness/iterate-plugin"
+    "url": "https://github.com/jingzhao-l/iterate-plugin.git"
   },
-  "homepage": "https://github.com/jingzhao-l/iterate-skill/tree/main/harness/iterate-plugin",
+  "homepage": "https://github.com/jingzhao-l/iterate-plugin#readme",
   "bugs": {
-    "url": "https://github.com/jingzhao-l/iterate-skill/issues"
+    "url": "https://github.com/jingzhao-l/iterate-plugin/issues"
   },
   "keywords": [
     "dsh-plugin",
@@ -47,7 +46,12 @@
         "0.2.0-rc.1": "compatible",
         "0.2.0-rc.2": "compatible",
         "0.2.1-alpha.1": "compatible",
-        "0.2.1-alpha.2": "compatible"
+        "0.2.1-alpha.2": "compatible",
+        "0.2.1-alpha.3": "compatible",
+        "0.2.1-alpha.4": "compatible",
+        "0.2.1-alpha.5": "compatible",
+        "0.2.1-rc.1": "compatible",
+        "0.2.1-rc.2": "compatible"
       }
     },
     "client": {
@@ -84,15 +88,35 @@
     "test:validate": "tsx --test test/validate.test.ts"
   },
   "dependencies": {
-    "@deepseek-ai/cordis": "4.0.5-alpha.1",
-    "@deepseek-ai/dsh-tools": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-util-values": "0.2.1-alpha.2",
     "js-yaml": "4.3.2"
   },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5-alpha.2",
+    "@deepseek-ai/dsh-session": "0.1.1-rc.1 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.1-rc.1 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2",
+    "@deepseek-ai/dsh-util-values": "0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-util-values": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-jobs": "0.2.1-alpha.2",
-    "@deepseek-ai/dsh-session": "0.2.1-alpha.2",
+    "@deepseek-ai/cordis": "4.0.5",
+    "@deepseek-ai/dsh-agent": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-jobs": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-util-values": "0.2.1-rc.2",
     "@types/js-yaml": "4.0.9",
     "@types/node": "22.15.0",
     "@types/react": "19.2.2",
@@ -104,6 +128,7 @@
     "typescript": "5.9.3"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20",
+    "dsh": ">=0.1.1-rc.1"
   }
 }

package/src/client/i18n.ts

@@ -253,6 +253,12 @@ export const EN: Record<string, string> = {
     'Export every observatory panel as JSON (downloads first, falls back to copying)',
   已导出: 'Exported',
   '导出 JSON': 'Export JSON',
+  '导出报告': 'Export report',
+  '导出可粘贴进 PR 的 Markdown 运行报告（优先下载，失败则复制）':
+    'Export a PR-pasteable Markdown run report (download first, copy on failure)',
+  '导出 SARIF': 'Export SARIF',
+  '导出 SARIF 2.1.0（供 CI / GitHub Code Scanning 消费）':
+    'Export SARIF 2.1.0 for CI / GitHub Code Scanning',
   '观测台页签（快捷键 1-9 / 0 / -）': 'Observatory tabs (keys 1-9 / 0 / -)',
   '{a0}（按 {a1} 切换）': '{a0} (press {a1})',
   '{a0}（按 - 切换）': '{a0} (press -)',

package/src/client/index.ts

@@ -108,6 +108,13 @@ import {
   configValueByPath, // #8b: current value of the selected dotted key
   DISK_SNAPSHOT_SOURCES, // #4/#3: read-side tools listed by the pull instruction
 } from '../../lib/parse.js'
+// v3.9: report export — shared with the `iterate_report` tool so the button
+// and the tool can never produce different reports.
+import {
+  renderRunReportMarkdown, // Markdown run report (PR-pasteable)
+  renderRunReportSarif, // SARIF 2.1.0 log (CI / Code Scanning)
+  runReportFilename, // deterministic download filename
+} from '../report-render.ts'
 import {
   configureLangStorage,
   detectLang,
@@ -1054,9 +1061,22 @@ function ConvergenceDashboard(props: SlotProps) {
   }, [session])
   const report = latestReport(session)
 
+  // Mount-time suppression: opening a session that ALREADY has a report mounts
+  // this component with that report, and an effect keyed on the report hash
+  // fires immediately — popping a stale "Round X 完成" bubble for work that did
+  // not just complete. Track the first key this instance sees and skip it; only
+  // a subsequent round progression pulses.
+  const pulseSeenRef = React.useRef<string | null>(null)
   React.useEffect(() => {
     if (!report) return
     const cur = getCurrentRound(report)
+    const key = hashReport(report) + ':' + String(cur)
+    if (pulseSeenRef.current === null) {
+      pulseSeenRef.current = key
+      return
+    }
+    if (pulseSeenRef.current === key) return
+    pulseSeenRef.current = key
     const conv = report.convergence
     emitRoundPulse(cur, conv?.converged === true)
     setPulseKey((k) => k + 1)
@@ -1406,6 +1426,11 @@ function TriagePanel(props: SlotProps) {
   }
 
   // ── Keyboard shortcuts (y / n / a on the selected finding, ↑/↓ to move) ──
+  // Multi-instance scoping: every turn that has a report mounts its OWN triage
+  // panel. Keying off `document.querySelector('[data-iterate="triage"]')` would
+  // return only the FIRST one, so y/n/a/↑/↓ silently dead whenever focus sits
+  // in a later panel. A per-component ref points at THIS instance's root.
+  const rootRef = React.useRef<HTMLDivElement | null>(null)
   React.useEffect(() => {
     const doc = typeof document !== 'undefined' ? document : null
     if (!doc) return
@@ -1417,10 +1442,10 @@ function TriagePanel(props: SlotProps) {
       const t = ev.target as HTMLElement | null
       if (t && (t.tagName === 'INPUT' || t.tagName === 'TEXTAREA' || t.tagName === 'SELECT')) return
       if (t && typeof t.isContentEditable === 'boolean' && t.isContentEditable) return
-      // Only act when focus is INSIDE the triage panel. Everything else keeps
+      // Only act when focus is INSIDE THIS panel. Everything else keeps
       // standard behavior (↑/↓ page scroll, typing in the composer), so we do
       // not hijack document-level keys just because a report is mounted.
-      const rootEl = doc.querySelector('[data-iterate="triage"]')
+      const rootEl = rootRef.current
       if (!rootEl) return
       const activeEl = doc.activeElement as HTMLElement | null
       if (!activeEl) return
@@ -1584,7 +1609,7 @@ function TriagePanel(props: SlotProps) {
     )
   })
 
-  return React.createElement('div', { 'data-iterate-root': '', 'data-iterate': 'triage', className: 'iterate-triage' },
+  return React.createElement('div', { ref: rootRef, 'data-iterate-root': '', 'data-iterate': 'triage', className: 'iterate-triage' },
     React.createElement('div', { className: 'iterate-triage-head' },
       React.createElement('span', { role: 'heading', 'aria-level': 3 }, tf(`Iterate · Findings 分诊 ({a0}/{a1})`, { a0: filtered.length, a1: findings.length })),
       React.createElement('span', { className: 'iterate-triage-hint' }, t('y=修复 · n=跳过 · a=已知有意 · ↑/↓ 选择')),
@@ -2390,6 +2415,30 @@ function ObservatoryPanel(props: SlotProps) {
     })
   }
 
+  /** v3.9: export the run as a portable report — Markdown (PR-pasteable) or
+   *  SARIF 2.1.0 (CI / GitHub Code Scanning). Rendered from the SAME shared
+   *  data model as the `iterate_report` tool, so the button and the tool can
+   *  never disagree. Download-first with a copy fallback, like `exportObservatory`. */
+  const exportReport = (format: 'markdown' | 'sarif') => {
+    if (!manifest) return
+    const extra = { qualityGate, experienceBank, defenseEvents }
+    const content = format === 'sarif'
+      ? JSON.stringify(renderRunReportSarif(manifest, extra), null, 2)
+      : renderRunReportMarkdown(manifest, extra, { lang: getLang() })
+    const filename = runReportFilename(format)
+    const key = `report-${format}`
+    const flash = () => {
+      setCopiedKey(key)
+      if (copyTimer.current) clearTimeout(copyTimer.current)
+      copyTimer.current = setTimeout(() => setCopiedKey((cur) => (cur === key ? null : cur)), 1600)
+    }
+    if (downloadTextFile(filename, content)) { flash(); return }
+    copyText(content).then((ok) => {
+      if (!ok) { setCopyFailText(content); return }
+      flash()
+    })
+  }
+
   /** Force every thread open (or closed) and drop per-thread state. */
   const setAllThreads = (mode: 'all' | 'none') => {
     setThreadMode(mode)
@@ -2525,7 +2574,7 @@ function ObservatoryPanel(props: SlotProps) {
     // client has no filesystem access, so `iterate_history` aggregates have to
     // be echoed back into the session first).
     const report = latestReport(session)
-    const comparison = buildRoundComparison(report, manifest.validations || [])
+    const comparison = buildRoundComparison(report, manifest.validations || [], manifest.fixes || [])
     const comparisonTable = comparison.length === 0
       ? null
       : React.createElement('table', { className: 'iterate-obs-table' },
@@ -3431,6 +3480,19 @@ function ObservatoryPanel(props: SlotProps) {
               onClick: exportObservatory,
               title: t('将观测台全部数据导出为 JSON（优先下载，失败则复制）'),
             }, copiedKey === 'export' ? t('已导出') : t('导出 JSON')),
+            // v3.9: portable report export — Markdown for a PR body, SARIF for
+            // CI / GitHub Code Scanning. Rendered from the same data model as
+            // the `iterate_report` tool.
+            React.createElement('button', {
+              className: 'iterate-btn', 'data-copied': copiedKey === 'report-markdown' ? '' : undefined,
+              onClick: () => exportReport('markdown'),
+              title: t('导出可粘贴进 PR 的 Markdown 运行报告（优先下载，失败则复制）'),
+            }, copiedKey === 'report-markdown' ? t('已导出') : t('导出报告')),
+            React.createElement('button', {
+              className: 'iterate-btn', 'data-copied': copiedKey === 'report-sarif' ? '' : undefined,
+              onClick: () => exportReport('sarif'),
+              title: t('导出 SARIF 2.1.0（供 CI / GitHub Code Scanning 消费）'),
+            }, copiedKey === 'report-sarif' ? t('已导出') : t('导出 SARIF')),
             // Gap #4: `.iterate/` artifacts are unreachable from the browser;
             // this copies the one instruction that makes the model echo them
             // into the session stream (which is what every panel scans).

package/src/file-lock.ts

@@ -30,6 +30,7 @@
 import {
   closeSync,
   existsSync,
+  fstatSync,
   mkdirSync,
   openSync,
   readFileSync,
@@ -40,7 +41,14 @@ import {
 import { join } from 'node:path'
 
 const LOCK_DIR = '.iterate'
-const DEFAULT_WAIT_MS = 5000
+// Bounded wait before degrading to "proceed unlocked". `acquireProjectLock`
+// spins on `Atomics.wait`, which BLOCKS the single plugin thread for the whole
+// budget — so a long default wedges unrelated tool calls and the UI heartbeat
+// whenever a sibling process holds the lock. Healthy holders release in
+// microseconds, so 1000ms is very generous; anything slower is treated as
+// contention and degrades to the historical unlocked behavior rather than
+// stalling the event loop for five seconds.
+const DEFAULT_WAIT_MS = 1000
 const DEFAULT_STALE_MS = 10000
 const POLL_MS = 25
 
@@ -80,19 +88,28 @@ function lockFileName(name: string): string {
   return `.${name}.lock`
 }
 
+/** Outcome of a checked acquisition: whether the lock was actually TAKEN. */
+export interface AcquireLockResult {
+  acquired: boolean
+  release: () => void
+}
+
 /**
- * Acquire an advisory lock named `name` inside `<projectRoot>/.iterate/`.
+ * Acquire an advisory lock named `name` inside `<projectRoot>/.iterate/`,
+ * reporting whether it was actually taken.
  *
- * Returns a release function: always callable, idempotent, never throws.
- * A no-op (but callable) release is returned when the lock directory cannot be
- * created or the wait times out — callers then proceed unlocked, which is the
- * historical best-effort behavior, rather than failing the operation.
+ * The returned release function is always callable, idempotent, and never
+ * throws. `acquired:false` (with a no-op release) is returned when the lock
+ * directory cannot be created or the wait times out — callers then proceed
+ * unlocked, which is the historical best-effort behavior, rather than failing
+ * the operation. Callers that MUST hold the mutex (e.g. a log rewrite that
+ * renames the file) branch on `acquired` and refuse to run unlocked.
  */
-export function acquireProjectLock(
+export function acquireProjectLockChecked(
   projectRoot: string,
   name: string,
   options: LockOptions = {},
-): () => void {
+): AcquireLockResult {
   const waitMs = Number.isFinite(options.waitMs) && (options.waitMs ?? 0) >= 0
     ? (options.waitMs as number)
     : DEFAULT_WAIT_MS
@@ -105,7 +122,7 @@ export function acquireProjectLock(
     try {
       mkdirSync(dir, { recursive: true })
     } catch {
-      return () => {}
+      return { acquired: false, release: () => {} }
     }
   }
   const lockPath = join(dir, lockFileName(name))
@@ -115,7 +132,7 @@ export function acquireProjectLock(
     try {
       fd = openSync(lockPath, 'wx')
     } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') return () => {}
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') return { acquired: false, release: () => {} }
       // Lock exists — steal it when the owner is gone or the lock is ancient.
       let stale = false
       try {
@@ -136,11 +153,20 @@ export function acquireProjectLock(
         }
         continue
       }
-      if (Date.now() - start > waitMs) return () => {}
+      if (Date.now() - start > waitMs) return { acquired: false, release: () => {} }
       sleepSync(POLL_MS)
       continue
     }
-    // Owned the lock: stamp the holder pid, then release once on return.
+    // Owned the lock: capture the created inode (for the ownership-checked
+    // release), stamp the holder pid, then release once on return.
+    let ino = 0
+    try {
+      ino = fstatSync(fd).ino
+    } catch {
+      // inode unavailable on this filesystem — the release falls back to the
+      // pid-stamp check only.
+      ino = 0
+    }
     try {
       writeSync(fd, String(process.pid))
     } catch {
@@ -151,10 +177,26 @@ export function acquireProjectLock(
     } catch {
       // best-effort
     }
-    return makeLockRelease(lockPath)
+    return { acquired: true, release: makeLockRelease(lockPath, ino) }
   }
 }
 
+/**
+ * Acquire an advisory lock named `name` inside `<projectRoot>/.iterate/`.
+ *
+ * Returns a release function: always callable, idempotent, never throws.
+ * A no-op (but callable) release is returned when the lock directory cannot be
+ * created or the wait times out — callers then proceed unlocked, which is the
+ * historical best-effort behavior, rather than failing the operation.
+ */
+export function acquireProjectLock(
+  projectRoot: string,
+  name: string,
+  options: LockOptions = {},
+): () => void {
+  return acquireProjectLockChecked(projectRoot, name, options).release
+}
+
 /**
  * Build the release function for a lock file this process just acquired.
  *
@@ -168,7 +210,25 @@ export function acquireProjectLock(
  *
  * Always callable, idempotent, and never throws.
  */
-export function makeLockRelease(lockPath: string): () => void {
+/**
+ * Build the release function for a lock file this process just acquired.
+ *
+ * Advisory locks here are STOLEN when the recorded owner dies or the mtime
+ * goes ancient: the steal unlinks our file and creates a new one stamped with
+ * the STEALER's pid. An unguarded release would then unlink the new holder's
+ * lock — turning our release into a double-release that admits a third process
+ * into a "held" critical section. So the release re-reads the stamp and only
+ * unlinks a file that is still ours: same pid (or unstamped) AND, when we know
+ * the inode we created, the SAME inode still at the path. The inode check closes
+ * the read-then-unlink window where the stamp check alone could race a steal
+ * (our pid is alive, but the file was already replaced between the two calls).
+ *
+ * Always callable, idempotent, and never throws.
+ *
+ * @param lockPath - the lock file path.
+ * @param ino - the inode captured at acquisition (0 = unknown; skip the check).
+ */
+export function makeLockRelease(lockPath: string, ino?: number): () => void {
   let released = false
   return () => {
     if (released) return
@@ -183,6 +243,16 @@ export function makeLockRelease(lockPath: string): () => void {
     // A stamp naming another pid means the lock was stolen and reassigned:
     // it is no longer ours to delete.
     if (raw !== '' && Number(raw) !== process.pid) return
+    // The path must still refer to the file WE created. A stealer unlinked our
+    // file and created a fresh one; that replacement carries a different inode,
+    // so unlinking by path would delete the NEW holder's lock.
+    if (typeof ino === 'number' && ino !== 0) {
+      try {
+        if (statSync(lockPath).ino !== ino) return
+      } catch {
+        return // vanished mid-release — nothing of ours left
+      }
+    }
     try {
       unlinkSync(lockPath)
     } catch {

package/src/git-scope.ts

@@ -22,7 +22,7 @@
  */
 
 import { execFile } from 'node:child_process'
-import { existsSync, statSync } from 'node:fs'
+import { lstatSync, realpathSync } from 'node:fs'
 import { join, sep } from 'node:path'
 
 /** A resolved changed-only scope result. */
@@ -113,6 +113,15 @@ export function parseChangedFiles(stdout: string): string[] {
  * Keep only entries that resolve to an existing regular file under `root`.
  * Traversal-safe: rejects absolute paths and any relative path that would
  * escape `root` via `..` (resolved against the root before stat).
+ *
+ * Symlink handling: `statSync` (and `existsSync`) FOLLOW symlinks, so a git
+ * entry that is a link to a file OUTSIDE the project would pass a path-only
+ * containment check and enter the changed-only scope. Such a file is then
+ * rejected by the evidence gate (realpath out of bounds → `file_not_found`),
+ * so every finding on it would fail closed as `EVIDENCE_VIOLATION` forever —
+ * a permanent false positive for repos with dotfile or shared-config links.
+ * `lstatSync` distinguishes the link itself; a link whose REAL target escapes
+ * `root` is dropped here instead.
  */
 export function filterExistingFiles(root: string, files: string[]): string[] {
   const out: string[] = []
@@ -122,7 +131,17 @@ export function filterExistingFiles(root: string, files: string[]): string[] {
     const candidate = join(root, rel)
     if (!candidate.startsWith(rootPrefix) && candidate !== root) continue
     try {
-      if (existsSync(candidate) && statSync(candidate).isFile()) out.push(rel)
+      const st = lstatSync(candidate)
+      if (st.isFile()) {
+        out.push(rel)
+        continue
+      }
+      if (!st.isSymbolicLink()) continue
+      // A link whose real target stays inside the project is a legitimate,
+      // reviewable file; one that escapes is excluded from scope (fail-closed
+      // at the source instead of as a permanent evidence violation).
+      const real = realpathSync(candidate)
+      if (real === root || real.startsWith(rootPrefix)) out.push(rel)
     } catch {
       // Unreadable entry (e.g. a broken symlink) is not a valid review target.
       continue

package/src/index.ts

@@ -2,16 +2,18 @@
  * iterate-plugin — dsh plugin for the iterate autonomous closed-loop workflow
  *
  * Architecture:
- * - The plugin registers 17 tools (14 original + 3 v3.0 quality command center tools)
+ * - The plugin registers 18 tools (14 original + 3 v3.0 quality command center
+ *   tools + 1 v3.9 report export)
  *   Original: config, validate, decision-log, context, review, triage, fix, diff,
  *   rollback, checkpoint, status, history, prune, transcript
  *   v3.0: experience, quality_gate, defense_events
+ *   v3.9: report
  * - The plugin injects a system prompt section teaching the iterate workflow pattern
  * - The model (prompted by the skill) writes a workflow script using dsh's `workflow` tool
  * - The workflow script uses `agent()` / `parallel()` / `phase()` / `log()` to orchestrate
- * - Subagents use the 17 tools to do real work (read config, run validation, log decisions,
+ * - Subagents use the 18 tools to do real work (read config, run validation, log decisions,
  *   review, triage, apply/rollback/fixing, checkpoint, status, history, prune, transcript,
- *   query experience bank, check quality gates, query defense events)
+ *   query experience bank, check quality gates, query defense events, export a report)
  * - A `tools/pre-execute` hook gates destructive iterate calls behind human approval
  *   (F8 observatory approval policy: ask / deny / allow).
  *
@@ -23,7 +25,7 @@
  *
  * Key files:
  * - src/index.ts      — Plugin entry: register tools + inject skill prompt
- * - src/tools/        — 17 tool implementations (14 original + 3 v3.0)
+ * - src/tools/        — 18 tool implementations (14 original + 3 v3.0 + 1 v3.9)
  * - src/config-loader.ts — YAML config loading
  * - src/types.ts     — Shared types
  */
@@ -43,6 +45,7 @@ import { registerTranscriptTool } from './tools/transcript.ts'
 import { registerExperienceBankTool } from './tools/experience-bank.ts'
 import { registerQualityGateTool } from './tools/quality-gate.ts'
 import { registerDefenseEventsTool } from './tools/defense-events.ts'
+import { registerReportTool } from './tools/report.ts'
 import { registerSessionHooks } from './session-hooks.ts'
 import { registerLiveCapture } from './live.ts'
 import { installWorkingDirectoryContext } from './working-directory.ts'
@@ -92,6 +95,8 @@ export function apply(ctx: Context): void {
     ['iterate_experience', () => registerExperienceBankTool(ctx)],
     ['iterate_quality_gate', () => registerQualityGateTool(ctx)],
     ['iterate_defense_events', () => registerDefenseEventsTool(ctx)],
+    // v3.9: PR-ready / CI-ready report export
+    ['iterate_report', () => registerReportTool(ctx)],
   ]
   for (const [toolName, register] of toolRegistrations) {
     try {