iterate-plugin 3.5.7 → 3.6.0

package/lib/parse.js

@@ -2,7 +2,10 @@
  * lib/parse.js — Pure logic for iterate client UI.
  *
  * Framework-agnostic, DOM-free, single-file, testable with Node.js assert.
- * Every function is exported for unit test coverage.
+ * Every scan / normalize / compute helper is exported for unit test coverage;
+ * only micro plumbing stays module-private (the safeGet/safeKeys proxy-safe
+ * readers, the guarded JSON string coercion, and the three one-line predicate
+ * wrappers over findFirstInObject), each exercised through its caller.
  *
  * @module iterate-ui/parse
  */
@@ -56,6 +59,27 @@ function safeKeys(o) {
   }
 }
 
+/**
+ * Coerce a possibly STRING-encoded node (tool results and message contents
+ * arrive as raw JSON text) into its parsed object/array form. Only strings
+ * whose trimmed body starts with `{` or `[` are parsed, so plain
+ * conversational text is never fed to JSON.parse; unparseable text passes
+ * through untouched and the caller decides what a still-raw string means.
+ *
+ * @param {unknown} v
+ * @returns {unknown}
+ */
+function coerceJsonNode(v) {
+  if (typeof v !== 'string') return v
+  const t = v.trim()
+  if (!t.startsWith('{') && !t.startsWith('[')) return v
+  try {
+    return JSON.parse(t)
+  } catch {
+    return v
+  }
+}
+
 // ─── Interruption / resume + image attachment detection ──────────────────────
 
 /**
@@ -270,13 +294,17 @@ export function scanSessionForReport(session) {
       const call = calls[i]
       if (!call) continue
       if (safeGet(call, 'tool') === 'iterate_review' || String(safeGet(call, 'tool') ?? '').endsWith('iterate_review')) {
-        const result = safeGet(call, 'result')
+        // Results may arrive as STRING-encoded JSON (arbitrary session text).
+        const result = coerceJsonNode(safeGet(call, 'result'))
         if (result && typeof result === 'object') {
           const r = /** @type {Record<string, unknown>} */ (result)
           const report = safeGet(r, 'report')
-          if (report && typeof report === 'object') {
-            return /** @type {Record<string, unknown>} */ (report)
-          }
+          // Only a VALIDATED report wins here: a junk `result.report` must
+          // neither reach normalizeReport nor shadow a real report nested
+          // deeper in the same result (or an older, valid call).
+          if (isReviewReport(report)) return report
+          const found = findReportInObject(result)
+          if (found) return found
         }
       }
     }
@@ -291,8 +319,29 @@ export function scanSessionForReport(session) {
       const msgCalls = msg && Array.isArray(safeGet(msg, 'tool_calls')) ? safeGet(msg, 'tool_calls') : null
       if (!msg || !msgCalls) continue
       const calls = /** @type {Array<Record<string, unknown>>} */ (msgCalls)
-      for (const call of calls) {
+      // Reverse: within a single assistant message the LAST tool call is the
+      // most recent one — two parallel iterate_review results must resolve to
+      // the newer report, not the older ("Prefers the most recent one").
+      for (let j = calls.length - 1; j >= 0; j--) {
+        const call = calls[j]
         if (!call) continue
+        // Result surface (same shape the quality-gate / defense scanners read):
+        // `{ name|tool, result }` message tool calls. Without this branch a
+        // report carried on `tool_calls[].result` was only reachable through
+        // the generic content fallback, so the dashboard could stay empty
+        // while F8–F10 filled from the very same message.
+        const callName = String(safeGet(call, 'name') ?? safeGet(call, 'tool') ?? '')
+        if (callName === 'iterate_review' || callName.endsWith('iterate_review')) {
+          for (const key of ['result', 'response', 'message']) {
+            const node = coerceJsonNode(safeGet(call, key))
+            if (!node || typeof node !== 'object') continue
+            const r = /** @type {Record<string, unknown>} */ (node)
+            const report = safeGet(r, 'report')
+            if (isReviewReport(report)) return report
+            const found = findReportInObject(node)
+            if (found) return found
+          }
+        }
         const fn = safeGet(call, 'function')
         if (fn && typeof fn === 'object') {
           const f = /** @type {Record<string, unknown>} */ (fn)
@@ -348,7 +397,7 @@ export function isTranscriptManifest(obj) {
  * @param {unknown} source
  * @returns {Record<string, unknown> | null}
  */
-function attachLive(manifest, source) {
+export function attachLive(manifest, source) {
   if (!manifest || typeof manifest !== 'object') return manifest
   const live = source && typeof source === 'object' ? safeGet(source, 'live') : undefined
   if (!Array.isArray(live)) return manifest
@@ -372,7 +421,7 @@ function attachLive(manifest, source) {
  * @param {number} [depth]
  * @returns {Record<string, unknown> | null}
  */
-function extractTranscript(obj, seen, depth) {
+export function extractTranscript(obj, seen, depth) {
   if (depth === undefined) depth = 0
   if (depth > 20) return null
   if (typeof obj === 'string') {
@@ -503,10 +552,29 @@ export function scanSessionForTranscript(session) {
       // Prefer the explicit tool-call surface first, then generic content.
       const calls = safeGet(msg, 'tool_calls')
       if (Array.isArray(calls)) {
-        for (const call of calls) {
+        // Reverse: the last tool call in one message is the most recent —
+        // two parallel iterate_transcript results must resolve to the newer
+        // manifest ("Prefers the most recent one").
+        const callList = /** @type {Array<Record<string, unknown>>} */ (calls)
+        for (let j = callList.length - 1; j >= 0; j--) {
+          const call = callList[j]
           if (!call) continue
-          const args = safeGet(call, 'arguments')
-          if (typeof args === 'string') {
+          // OpenAI-style calls nest the payload under `function.arguments`
+          // (a JSON string) — the shape scanSessionForReport already reads.
+          // Missing it here meant a manifest echoed only in that surface was
+          // invisible to the observatory (F1–F7 stayed empty).
+          const fn = safeGet(call, 'function')
+          const candidates = [
+            // Result surface first: `{ name|tool, result }` message tool calls
+            // (the same shape scanSessionForQualityGate already accepts).
+            safeGet(call, 'result'),
+            safeGet(call, 'response'),
+            safeGet(call, 'message'),
+            safeGet(call, 'arguments'),
+            fn && typeof fn === 'object' ? safeGet(/** @type {Record<string, unknown>} */ (fn), 'arguments') : undefined,
+          ]
+          for (const args of candidates) {
+            if (args === undefined || args === null) continue
             const found = extractTranscript(args)
             if (found) return found
           }
@@ -520,6 +588,38 @@ export function scanSessionForTranscript(session) {
   return null
 }
 
+/**
+ * Normalize the `validations` array the transcript capture carries (contract:
+ * `{round, command, exitCode, allowed, rejectReason?}` — one row per
+ * validation command run in a round). Defensive like every other normalizer:
+ * junk rows are dropped, missing fields degrade to safe defaults, and the
+ * input is never mutated.
+ *
+ * @param {unknown} raw
+ * @returns {Array<{ round: number, command: string, exitCode: number | null, allowed: boolean, rejectReason?: string }>}
+ */
+export function normalizeValidations(raw) {
+  if (!Array.isArray(raw)) return []
+  const out = []
+  for (const v of /** @type {unknown[]} */ (raw)) {
+    if (!v || typeof v !== 'object') continue
+    const rec = /** @type {Record<string, unknown>} */ (v)
+    const roundRaw = Number(rec.round)
+    const exitRaw = rec.exitCode
+    const command = typeof rec.command === 'string' ? rec.command : String(rec.command ?? '')
+    if (!command) continue
+    const rejectReason = typeof rec.rejectReason === 'string' ? rec.rejectReason : ''
+    out.push({
+      round: Number.isFinite(roundRaw) && roundRaw > 0 ? Math.floor(roundRaw) : 0,
+      command,
+      exitCode: typeof exitRaw === 'number' && Number.isFinite(exitRaw) ? exitRaw : null,
+      allowed: rec.allowed === true,
+      ...(rejectReason ? { rejectReason } : {}),
+    })
+  }
+  return out
+}
+
 /**
  * Normalize a TranscriptManifest into a plain, JSON-safe object so rendering
  * never touches a live cordis proxy (which can throw on property reads). Every
@@ -599,6 +699,9 @@ export function normalizeTranscript(manifest) {
     })),
     checkpoint,
     timeline: asArray(safeGet(src, 'timeline')).map((t) => ({ ...t })),
+    // #6: per-round validation rows (command / exitCode / allowed), captured
+    // by the workflow and persisted through `iterate_transcript capture`.
+    validations: normalizeValidations(safeGet(src, 'validations')),
     nudge,
     approval: ap && typeof ap === 'object'
       ? { active: asBool(safeGet(ap, 'active')), policy: asStr(safeGet(ap, 'policy')) || 'ask' }
@@ -675,7 +778,10 @@ export function isDefenseEventsResult(obj) {
 
 /**
  * Shared deep-find: first node in `obj` (circular + depth guarded) satisfying a
- * predicate, with the same traversal semantics as findReportInObject.
+ * predicate, with the same traversal semantics as findReportInObject. String
+ * nodes are parsed when they carry a JSON payload (`{...}` / `[...]`), so
+ * STRING-encoded tool results / message contents are as visible to the
+ * scanSessionFor* scanners as object nodes.
  *
  * @param {unknown} obj
  * @param {(o: Record<string, unknown>) => boolean} predicate
@@ -683,8 +789,15 @@ export function isDefenseEventsResult(obj) {
  * @param {number} [maxDepth=20]
  * @returns {Record<string, unknown> | null}
  */
-function findFirstInObject(obj, predicate, seen, maxDepth = 20) {
+export function findFirstInObject(obj, predicate, seen, maxDepth = 20) {
   if (maxDepth <= 0) return null
+  // Guarded JSON.parse for string nodes; a plain / unparseable string has
+  // nothing to scan. Keeps the same depth (one hop per parse) and seen guards.
+  if (typeof obj === 'string') {
+    const parsed = coerceJsonNode(obj)
+    if (parsed === obj) return null // not (parseable) JSON text
+    return findFirstInObject(parsed, predicate, seen, maxDepth - 1)
+  }
   if (!obj || typeof obj !== 'object') return null
 
   const s = seen || new Set()
@@ -730,16 +843,23 @@ function findDefenseResultInObject(obj) {
 
 /**
  * Return the raw result/message node of the most recent execution of `toolName`
- * in a session snapshot. Scans `session.toolCalls` (reverse chronological,
- * matching the harness's in-memory stream shape) and falls back to
- * `session.messages[].content` (assistant tool-call blocks). Returns the raw
- * node (object or string) or null.
+ * in a session snapshot whose subtree actually contains a match for `find`.
+ * Scans `session.toolCalls` (reverse chronological, matching the harness's
+ * in-memory stream shape), then `session.messages[].tool_calls` (assistant
+ * tool-call blocks), then falls back to `session.messages[].content` — the
+ * content fallback loops newest→oldest and only accepts a message whose
+ * content embeds a match, so a conversational closing message can never
+ * shadow an earlier message's embedded result. A junk LATEST result is
+ * skipped (an older valid one still surfaces) because `find` gates every
+ * candidate. Returns the raw node (object or string) or null.
  *
  * @param {unknown} session
  * @param {string} toolName
+ * @param {(node: unknown) => Record<string, unknown> | null} find deep-find
+ *   predicate identifying a usable match inside a candidate node
  * @returns {unknown}
  */
-function latestToolResultNode(session, toolName) {
+export function latestToolResultNode(session, toolName, find) {
   if (!session || typeof session !== 'object') return null
 
   const s = /** @type {Record<string, unknown>} */ (session)
@@ -753,9 +873,9 @@ function latestToolResultNode(session, toolName) {
       const tool = String(safeGet(call, 'tool') ?? '')
       if (tool !== toolName && !tool.endsWith(toolName)) continue
       const result = safeGet(call, 'result')
-      if (result !== undefined && result !== null) return result
+      if (result !== undefined && result !== null && find(result)) return result
       const message = safeGet(call, 'message')
-      if (message !== undefined && message !== null) return message
+      if (message !== undefined && message !== null && find(message)) return message
     }
   }
 
@@ -765,8 +885,8 @@ function latestToolResultNode(session, toolName) {
     // Assistant tool-call variant: the tool result may live on the call object
     // inside message.tool_calls rather than on session.toolCalls. Scan every
     // message for a matching call (newest-first) before falling back to the
-    // last message's raw content — a conversational closing message must not
-    // shadow an earlier message's real tool result.
+    // raw contents — a conversational closing message must not shadow an
+    // earlier message's real tool result.
     for (let i = msgs.length - 1; i >= 0; i--) {
       const msg = msgs[i]
       if (!msg) continue
@@ -779,17 +899,23 @@ function latestToolResultNode(session, toolName) {
         const name = String(safeGet(call, 'name') ?? safeGet(call, 'tool') ?? '')
         if (name !== toolName && !name.endsWith(toolName)) continue
         const result = safeGet(call, 'result') ?? safeGet(call, 'response') ?? safeGet(call, 'message')
-        if (result !== undefined && result !== null) return result
+        if (result !== undefined && result !== null && find(result)) return result
+        // `function.arguments` is deliberately NOT consulted here: it holds the
+        // CALL INPUT, and rendering an input as a stored result would show an
+        // `iterate_experience add` payload as if it were bank content. Inputs
+        // are not results — only result/response/message surfaces count.
       }
     }
-    // Fallback: the last message's raw content (pre-existing behavior — a
-    // plain conversational string yields null upstream, but an embedded JSON
-    // body is still worth surfacing for the deep-scan finders).
+    // Content fallback: loop messages newest→oldest and return the first
+    // content whose subtree actually embeds a match (the deep-scan finders
+    // see inside STRING-encoded JSON payloads too). An unmatched newest
+    // message must not shadow an older message's embedded result.
     for (let i = msgs.length - 1; i >= 0; i--) {
       const msg = msgs[i]
       if (!msg) continue
       const content = safeGet(msg, 'content')
-      if (content !== undefined && content !== null) return content
+      if (content === undefined || content === null) continue
+      if (find(content)) return content
     }
   }
 
@@ -848,7 +974,7 @@ export function normalizeQualityGateSnapshot(raw) {
  * @returns {Record<string, unknown> | null}
  */
 export function scanSessionForQualityGate(session) {
-  const node = latestToolResultNode(session, 'iterate_quality_gate')
+  const node = latestToolResultNode(session, 'iterate_quality_gate', findQualityGateInObject)
   if (node === null) return null
   const found = findQualityGateInObject(node)
   if (!found) return null
@@ -907,7 +1033,7 @@ export function normalizeExperienceBankResult(raw) {
  * @returns {Record<string, unknown> | null}
  */
 export function scanSessionForExperienceBank(session) {
-  const node = latestToolResultNode(session, 'iterate_experience')
+  const node = latestToolResultNode(session, 'iterate_experience', findExperienceResultInObject)
   if (node === null) return null
   const found = findExperienceResultInObject(node)
   if (!found) return null
@@ -971,7 +1097,7 @@ export function normalizeDefenseEventsResult(raw) {
  * @returns {Record<string, unknown> | null}
  */
 export function scanSessionForDefenseEvents(session) {
-  const node = latestToolResultNode(session, 'iterate_defense_events')
+  const node = latestToolResultNode(session, 'iterate_defense_events', findDefenseResultInObject)
   if (node === null) return null
   const found = findDefenseResultInObject(node)
   if (!found) return null
@@ -1122,9 +1248,12 @@ export function extractVerdict(runSummary) {
  * @returns {Record<string, unknown>}
  */
 export function normalizeReport(report) {
+  // Session/model text is arbitrary: `findings` / `rounds` may arrive as a
+  // NON-ARRAY junk value ({} / string / number) — coerce at every ingestion
+  // point so downstream map/iteration never throws `... is not iterable`.
   const convergence = /** @type {Record<string, unknown>} */ (report.convergence ?? {})
-  const rounds = /** @type {Array<unknown>} */ (report.rounds ?? [])
-  const findings = /** @type {Array<Record<string, unknown>>} */ (report.findings ?? [])
+  const rounds = /** @type {Array<unknown>} */ (Array.isArray(report.rounds) ? report.rounds : [])
+  const findings = /** @type {Array<Record<string, unknown>>} */ (Array.isArray(report.findings) ? report.findings : [])
 
   // Normalize convergence
   const totalRounds =
@@ -1132,6 +1261,16 @@ export function normalizeReport(report) {
       ? convergence.totalRounds
       : rounds.length
 
+  // Why the run stopped: an explicit harness-provided reason always wins;
+  // the derived fallback may only be stamped when the run is actually
+  // FINISHED (flagged converged, or every budgeted round executed). An
+  // in-progress run (rounds < totalRounds, not converged) must stay null —
+  // stamping 'converged' mid-run would render a false finished badge.
+  const explicitReason =
+    typeof convergence.stoppedReason === 'string' && convergence.stoppedReason.trim()
+      ? convergence.stoppedReason
+      : null
+
   const normalizedConvergence = {
     totalRounds,
     findingsByRound: Array.isArray(convergence.findingsByRound)
@@ -1141,7 +1280,12 @@ export function normalizeReport(report) {
           return Array.isArray(rr?.findings) ? rr.findings.length : 0
         }),
     converged: convergence.converged === true,
-    stoppedReason: convergence.stoppedReason ?? (rounds.length < totalRounds ? 'converged' : 'max_rounds_reached'),
+    stoppedReason: explicitReason ??
+      (convergence.converged === true
+        ? 'converged'
+        : rounds.length >= totalRounds
+          ? 'max_rounds_reached'
+          : null),
   }
 
   // Compute summary if missing. Always build a NEW object so the input's
@@ -1186,20 +1330,31 @@ export function normalizeReport(report) {
  * @returns {{ totalFindings: number, critical: number, high: number, medium: number, low: number, byDimension: Record<string, number> }}
  */
 function computeSummaryFromFindings(findings) {
+  // Coerce: a junk (non-array) findings value must degrade to "no findings",
+  // not throw `... is not iterable` during React render.
+  const list = Array.isArray(findings) ? findings : []
   const counts = { critical: 0, high: 0, medium: 0, low: 0 }
+  // NULL-PROTOTYPE map: `dimension` comes from arbitrary review/model text, so
+  // a finding tagged `__proto__` / `constructor` / `toString` must count as an
+  // ordinary bucket instead of reading (or assigning through) the prototype
+  // chain. `{} ` would make `byDimension['__proto__'] ?? 0` return
+  // Object.prototype and produce garbage counts — mirrors review.ts, which
+  // already creates its summary map with Object.create(null).
   /** @type {Record<string, number>} */
-  const byDimension = {}
+  const byDimension = Object.create(null)
 
-  for (const f of findings) {
+  for (const f of list) {
     if (!f || typeof f !== 'object') continue
     const sev = String(f.severity ?? 'low')
-    if (sev in counts) counts[sev]++
+    // OWN-property check: `'__proto__' in counts` is true via the prototype
+    // chain, which would corrupt the tally with a non-number.
+    if (Object.prototype.hasOwnProperty.call(counts, sev)) counts[sev]++
     const dim = String(f.dimension ?? 'unknown')
     byDimension[dim] = (byDimension[dim] ?? 0) + 1
   }
 
   return {
-    totalFindings: findings.length,
+    totalFindings: list.length,
     critical: counts.critical,
     high: counts.high,
     medium: counts.medium,
@@ -1239,8 +1394,10 @@ export function computeConvergenceProgress(report) {
  * @param {Record<string, unknown>} report
  * @returns {number}
  */
-function currentRoundNumber(report) {
-  const rounds = /** @type {Array<Record<string, unknown>>} */ (report.rounds ?? [])
+export function currentRoundNumber(report) {
+  // Coerce: `rounds` may be a non-array junk value in arbitrary session text —
+  // `for...of {}` would throw `... is not iterable`.
+  const rounds = /** @type {Array<Record<string, unknown>>} */ (Array.isArray(report.rounds) ? report.rounds : [])
   let max = 0
   for (const r of rounds) {
     if (!r || typeof r !== 'object') continue
@@ -1284,12 +1441,16 @@ export function getTotalRounds(report) {
  * @returns {{ critical: number, high: number, medium: number, low: number }}
  */
 export function severityStats(report) {
-  const findings = /** @type {Array<Record<string, unknown>>} */ (report.findings ?? [])
+  // Coerce at the ingestion point: non-array `findings` degrades to [].
+  const findings = /** @type {Array<Record<string, unknown>>} */ (Array.isArray(report.findings) ? report.findings : [])
   const counts = { critical: 0, high: 0, medium: 0, low: 0 }
   for (const f of findings) {
     if (!f || typeof f !== 'object') continue
     const sev = String(f.severity ?? 'low')
-    if (sev in counts) counts[sev]++
+    // OWN-property check: a junk severity of `__proto__`/`constructor` is not
+    // a bucket and must not read through the prototype chain (`counts[sev]++`
+    // would turn into NaN and try to reassign the prototype).
+    if (Object.prototype.hasOwnProperty.call(counts, sev)) counts[sev]++
   }
   return counts
 }
@@ -1303,13 +1464,17 @@ export function severityStats(report) {
  * @returns {Record<string, Array<Record<string, unknown>>>}
  */
 export function groupByDimension(report) {
-  const findings = /** @type {Array<Record<string, unknown>>} */ (report.findings ?? [])
+  // Coerce at the ingestion point: non-array `findings` degrades to [].
+  const findings = /** @type {Array<Record<string, unknown>>} */ (Array.isArray(report.findings) ? report.findings : [])
+  // NULL-PROTOTYPE buckets: `dimension` is arbitrary model text, so
+  // `__proto__` would otherwise resolve to Object.prototype (truthy → skip the
+  // bucket assignment) and crash on `.push` — or worse, mutate the prototype.
   /** @type {Record<string, Array<Record<string, unknown>>>} */
-  const groups = {}
+  const groups = Object.create(null)
   for (const f of findings) {
     if (!f || typeof f !== 'object') continue
     const dim = String(f.dimension ?? 'unknown')
-    if (!groups[dim]) groups[dim] = []
+    if (!Object.prototype.hasOwnProperty.call(groups, dim)) groups[dim] = []
     groups[dim].push(f)
   }
   return groups
@@ -1328,7 +1493,8 @@ export const TRIAGE_VERDICTS = /** @type {const} */ (['keep', 'skip', 'ignore'])
  * @returns {Record<string, 'keep' | 'skip' | 'ignore'>}
  */
 export function buildTriageState(report) {
-  const findings = /** @type {Array<unknown>} */ (report.findings ?? [])
+  // Coerce: non-array `findings` ({} / string) must not fabricate keys.
+  const findings = /** @type {Array<unknown>} */ (Array.isArray(report.findings) ? report.findings : [])
   /** @type {Record<string, 'keep' | 'skip' | 'ignore'>} */
   const state = {}
   for (let i = 0; i < findings.length; i++) {
@@ -1347,7 +1513,9 @@ export function buildTriageState(report) {
  * @returns {string}
  */
 export function hashReport(report) {
-  const findings = /** @type {Array<Record<string, unknown>>} */ (report.findings ?? [])
+  // Coerce: non-array `findings` degrades to [] instead of throwing on the
+  // `for...of` below.
+  const findings = /** @type {Array<Record<string, unknown>>} */ (Array.isArray(report.findings) ? report.findings : [])
   // FNV-1a over EVERY finding (file|line|dimension|summary) so two different
   // reports never share a verdict store, while re-running the identical review
   // restores the same verdicts.
@@ -1416,8 +1584,27 @@ export function buildApplyInstruction(entries) {
   )
 
   return (
-    `Please call \`iterate_triage\` with the following payload to apply the triage verdicts:\n\n` +
-    `\`\`\`json\n${payload}\n\`\`\``
+    `请调用 \`iterate_triage\` 应用下面的 known_intentional 条目（粘贴后由模型调用 ` +
+    `\`iterate_triage\` 的 \`operation: "apply"\` 写入配置：自动去重、写入前备份、失败自动回滚）：\n\n` +
+    `\`\`\`json\n${payload}\n\`\`\`\n\n` +
+    `写入完成后请复制面板的「回读已写入条目」指令（\`iterate_triage\` \`operation: "list"\`）核对结果。`
+  )
+}
+
+/**
+ * Copy-back instruction for the triage write-back loop: after an `apply`, the
+ * user needs the stored entries echoed back so the panel's "待写回" count has a
+ * confirmation step (copy → apply → read back).
+ *
+ * @returns {string}
+ */
+export function buildTriageReadbackInstruction() {
+  return (
+    '请调用 `iterate_triage` 回读当前已写入配置的 known_intentional 条目，' +
+    '并把每条的 file / line / dimension / reason 原样列出来供我核对：\n\n' +
+    '```json\n' +
+    `${JSON.stringify({ operation: 'list' }, null, 2)}\n` +
+    '```'
   )
 }
 
@@ -1430,10 +1617,12 @@ export function buildApplyInstruction(entries) {
  * @returns {Array<{ file: string, line?: number, dimension: string, reason: string }>}
  */
 export function collectIgnoredEntries(triageState, findings) {
+  // Coerce: a non-array findings value must never index string characters.
+  const list = Array.isArray(findings) ? findings : []
   const entries = []
   for (const [idx, verdict] of Object.entries(triageState)) {
     if (verdict !== 'ignore') continue
-    const finding = findings[Number(idx)]
+    const finding = list[Number(idx)]
     if (!finding) continue
     entries.push({
       file: String(finding.file ?? ''),
@@ -1447,6 +1636,342 @@ export function collectIgnoredEntries(triageState, findings) {
   return entries
 }
 
+// ─── Paste-able instruction payloads (copy-to-command contract) ─────────────
+//
+// The browser client cannot call harness tools, so every action button copies
+// a text the user pastes back into the session. These builders are the SINGLE
+// source of truth for those payloads (src/client/index.ts imports them), and
+// every payload is written against the real parameter schema declared in
+// src/tools/*.ts so test/parse.test.ts can assert field alignment.
+
+/** Placeholder the model must replace with the NEW full file content. */
+const CONTENT_PLACEHOLDER = '<由模型填写：修复后的完整文件内容>'
+/** Placeholder the model must replace with the current iteration round. */
+const ROUND_PLACEHOLDER = '<由模型填写：当前迭代轮次（≥1 的整数）>'
+
+/**
+ * Startup instructions copied by the empty-dashboard CTA.
+ *
+ * dsh exposes NO command / slash-command registration surface to plugins: the
+ * cordis Context services are `tools`, `systemPrompt`, `sessions`, `jobs`,
+ * `agents`, `llm`, `sandbox`, `sandboxPolicy`, `approval`, `sessionProjections`
+ * and `ptcRuntime` — there is no `ctx.command` / prompt-command registry, and
+ * `cordis.patch.yml` only inserts the bundle. So `/iterate` never existed as a
+ * command; the CTA instead copies natural-language instructions that the model
+ * resolves through the `workflow` tool exactly as the skill prompt teaches
+ * ("When the user asks to review or iterate on the project … run an iterate
+ * workflow by calling the `workflow` tool", mode normal / dry-run).
+ *
+ * @type {string}
+ */
+export const START_INSTRUCTION_FULL =
+  '开始一次完整迭代（审查 → 修复 → 验证 → 复盘）：请调用 `workflow` 工具运行 iterate 工作流，' +
+  'mode: "normal"，按系统提示的 Iterate Workflow 执行 plan → 多线程并行评审 → 分诊 → 原子修复 → 每轮验证 → 循环直至收敛或达到 max_rounds → 终报并 `iterate_transcript` capture。' +
+  '开跑前先 `iterate_config({operation:"read"})` 检查 validation.commands：若为空，先停下来提示我用 `iterate_config` 写入验证命令，否则本轮迭代不受任何测试保护。'
+
+/**
+ * Dry-run (review-only) startup instruction — mirrors the skill prompt's
+ * "review only / dry run / 不要改文件 → mode: dry-run" branch.
+ *
+ * @type {string}
+ */
+export const START_INSTRUCTION_REVIEW_ONLY =
+  '开始一次仅评审（dry-run，不修改任何文件）：请调用 `workflow` 工具运行 iterate 工作流，' +
+  'mode: "dry-run"，按系统提示的 Iterate Workflow 执行 plan → 多线程并行评审 → 分诊 → `iterate_review aggregate` / `meta-review` 终报并 `iterate_transcript` capture；' +
+  '全程不要调用 `iterate_fix` / `iterate_rollback`。'
+
+/** The registered startup instruction set the client CTA copies from. */
+export const START_INSTRUCTIONS = {
+  full: START_INSTRUCTION_FULL,
+  reviewOnly: START_INSTRUCTION_REVIEW_ONLY,
+}
+
+/** Normalize an arbitrary finding-ish node into the payload field set. */
+function fixFindingPayload(finding) {
+  const f = finding && typeof finding === 'object' ? finding : {}
+  const file = String(f.file ?? '')
+  return {
+    file,
+    ...(typeof f.line === 'number' && f.line > 0 ? { line: f.line } : {}),
+    dimension: String(f.dimension ?? ''),
+    severity: String(f.severity ?? ''),
+    summary: String(f.summary ?? ''),
+    ...(f.failure_scenario ? { failure_scenario: String(f.failure_scenario) } : {}),
+    ...(f.suggested_fix ? { suggested_fix: String(f.suggested_fix) } : {}),
+  }
+}
+
+/**
+ * Staged `iterate_fix` instruction for ONE finding.
+ *
+ * The tool schema (`src/tools/fix.ts`) requires `file` / `content` / `finding`
+ * / `round`; a raw JSON blob without `content` + `round` made the model guess
+ * the two hardest values, so the payload now names every required field and
+ * marks the two the model must fill in (`content` = the full NEW file, `round`
+ * = the current round) instead of pretending to ship a complete call.
+ *
+ * @param {Record<string, unknown>} finding
+ * @param {{ round?: number } | null} [opts] current round, when known by the UI
+ * @returns {string}
+ */
+export function buildFixInstruction(finding, opts) {
+  const payload = fixFindingPayload(finding)
+  if (!payload.file) return ''
+  const round = opts && Number.isInteger(opts.round) ? opts.round : null
+  const call = {
+    file: payload.file,
+    content: CONTENT_PLACEHOLDER,
+    finding: payload,
+    round: round !== null ? round : ROUND_PLACEHOLDER,
+  }
+  return [
+    '请修复下面这一个 finding。`iterate_fix` 一次只接受一个 finding，且 file / content / finding / round 四个参数全部必填：',
+    `步骤 1：读取 \`${payload.file}\`，按 finding 生成修复后的【完整文件内容】（content 占位必须换成真实文件内容）。`,
+    `步骤 2：调用 \`iterate_fix\`，把 content 与 round 填成真实值${round !== null ? `（本轮 round = ${round}）` : ''}：`,
+    '```json',
+    JSON.stringify(call, null, 2),
+    '```',
+    '需要超过 atomic 行数上限时，另加 "force": true。',
+  ].join('\n')
+}
+
+/**
+ * Batch assign instruction: N findings, but `iterate_fix` has NO array
+ * parameter — the payload says so explicitly ("一次一个").
+ *
+ * @param {Array<Record<string, unknown>>} findings
+ * @returns {string}
+ */
+export function buildAssignFixesInstruction(findings) {
+  const list = (Array.isArray(findings) ? findings : [])
+    .filter((f) => f && typeof f === 'object')
+  if (list.length === 0) return ''
+  const payload = list.map((f) => fixFindingPayload(f)).filter((p) => p.file)
+  if (payload.length === 0) return ''
+  return [
+    `请修复下面这 ${payload.length} 个 findings。注意：\`iterate_fix\` 每次只处理【一个】finding（没有数组入参），请逐个调用 iterate_fix——一次一个 finding，处理完一个再发起下一个，绝不要把整批数组当作参数传入。`,
+    '每个 finding 都走同样的两步：① 读取文件生成修复后的完整 content；② 调用 iterate_fix（file / content / finding / round 必填，content 与 round 由你填写）。',
+    '待修复清单：',
+    '```json',
+    JSON.stringify(payload, null, 2),
+    '```',
+  ].join('\n')
+}
+
+/**
+ * Architectural-fix approval instruction: `force: true` exists on the tool,
+ * but the four required fields still apply — the old text implied a lone
+ * `force` flag was enough.
+ *
+ * @param {Array<Record<string, unknown>>} [findings] optional scoped findings
+ * @returns {string}
+ */
+export function buildArchitecturalFixInstruction(findings) {
+  const list = (Array.isArray(findings) ? findings : []).filter((f) => f && typeof f === 'object')
+  const lines = [
+    '请批准并执行架构型修复（允许超过 atomic 行数上限）：对每个架构型 finding 逐个调用 `iterate_fix`，一次一个 finding，并显式设置 `"force": true`；',
+    'file / content / finding / round 四个必填参数一个都不能少（content = 修复后的完整文件内容，round = 当前迭代轮次，两者由你填写）。',
+  ]
+  if (list.length > 0) {
+    lines.push('本项目剩余架构型 finding：', '```json', JSON.stringify(list.map((f) => fixFindingPayload(f)), null, 2), '```')
+  }
+  return lines.join('\n')
+}
+
+/**
+ * `iterate_checkpoint` resume payload. The tool's `mode` / `round` /
+ * `maxRounds` / `fixedCount` are SAVE-only inputs; `resume` takes nothing but
+ * `operation`, and `maxRounds: null` was an invalid-integer field.
+ *
+ * @returns {string}
+ */
+export function buildCheckpointResumeInstruction() {
+  return (
+    '请调用 `iterate_checkpoint` 从断点恢复迭代（加载断点并把 resumeCount +1）：\n\n' +
+    '```json\n' +
+    `${JSON.stringify({ operation: 'resume' }, null, 2)}\n` +
+    '```'
+  )
+}
+
+/**
+ * `iterate_checkpoint` clear payload (stale checkpoint reset).
+ *
+ * @returns {string}
+ */
+export function buildCheckpointClearInstruction() {
+  return (
+    '请调用 `iterate_checkpoint` 清除当前断点：\n\n' +
+    '```json\n' +
+    `${JSON.stringify({ operation: 'clear' }, null, 2)}\n` +
+    '```'
+  )
+}
+
+/**
+ * `iterate_quality_gate` query instruction with explicit JSON args — the old
+ * plain-prose version had no `operation` and occasionally lost the enum.
+ *
+ * @returns {string}
+ */
+export function buildQualityGateQueryInstruction() {
+  return (
+    '请调用 `iterate_quality_gate` 查询当前质量门禁状态（读取磁盘上持久化的证书）：\n\n' +
+    '```json\n' +
+    `${JSON.stringify({ operation: 'read' }, null, 2)}\n` +
+    '```'
+  )
+}
+
+/**
+ * `iterate_quality_gate` clear payload (reset a stale FAIL certificate).
+ *
+ * @returns {string}
+ */
+export function buildQualityGateClearInstruction() {
+  return (
+    '请调用 `iterate_quality_gate` 清除当前质量门禁证书：\n\n' +
+    '```json\n' +
+    `${JSON.stringify({ operation: 'clear' }, null, 2)}\n` +
+    '```'
+  )
+}
+
+/**
+ * `iterate_rollback` payload for one applied fix id.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function buildRollbackInstruction(id) {
+  return (
+    '请调用 `iterate_rollback` 回滚以下修复：\n\n' +
+    '```json\n' +
+    `${JSON.stringify({ id: String(id || '') }, null, 2)}\n` +
+    '```'
+  )
+}
+
+/**
+ * `iterate_experience` list instruction (F9 empty state + header button).
+ *
+ * @returns {string}
+ */
+export function buildExperienceListInstruction() {
+  return (
+    '请调用 `iterate_experience` 列出经验银行中的所有经验，并把完整返回结果回显到会话里：\n\n' +
+    '```json\n' +
+    `${JSON.stringify({ operation: 'list' }, null, 2)}\n` +
+    '```'
+  )
+}
+
+/**
+ * `iterate_defense_events` list instruction (F10 empty state + header button).
+ *
+ * @returns {string}
+ */
+export function buildDefenseEventsListInstruction() {
+  return (
+    '请调用 `iterate_defense_events` 列出全部防御事件，并把完整返回结果回显到会话里：\n\n' +
+    '```json\n' +
+    `${JSON.stringify({ operation: 'list' }, null, 2)}\n` +
+    '```'
+  )
+}
+
+/**
+ * Disk snapshot pull instruction (#4): the browser client has no filesystem
+ * access, so the only way to fill the panels from `.iterate/` is to ask the
+ * model to call the read-side tools and echo their FULL results back into the
+ * session stream (which is exactly what the session scanners consume).
+ *
+ * @returns {string}
+ */
+export function buildDiskSnapshotInstruction() {
+  const lines = [
+    '请从磁盘拉取 iterate 快照：逐个调用下面的只读工具，并把每个工具的【完整返回结果】原样回显到会话里（不要只给摘要——插件面板靠这些回显填充）：',
+  ]
+  DISK_SNAPSHOT_SOURCES.forEach((s, i) => {
+    lines.push(`${i + 1}. \`${s.tool}\`（${s.label}）：${JSON.stringify(s.args)}`)
+  })
+  lines.push('回显后，观测台实时流 / F2 跨轮对比 / F5 断点 / F8 质量门禁 / F9 经验银行 / F10 防御事件会自动读取这些结果。')
+  return lines.join('\n')
+}
+
+/**
+ * Read-side tools whose results fill the client panels, with the exact
+ * argument objects their schemas accept (all operations are optional-input).
+ * @type {Array<{ tool: string, args: Record<string, unknown>, label: string }>}
+ */
+export const DISK_SNAPSHOT_SOURCES = [
+  { tool: 'iterate_status', args: {}, label: '运行状态汇总' },
+  { tool: 'iterate_transcript', args: { operation: 'read' }, label: 'transcript 观测清单' },
+  { tool: 'iterate_quality_gate', args: { operation: 'read' }, label: '质量门禁证书' },
+  { tool: 'iterate_experience', args: { operation: 'list' }, label: '经验银行' },
+  { tool: 'iterate_defense_events', args: { operation: 'list' }, label: '防御事件流' },
+  { tool: 'iterate_history', args: {}, label: '决策日志与修复注册表（跨轮/跨会话对比）' },
+]
+
+/**
+ * Whether `toolName` has actually been called in this session snapshot — the
+ * difference between "磁盘无数据" (we pulled it and it is empty) and "尚未拉取"
+ * (we never asked the model to read it).
+ *
+ * @param {unknown} session
+ * @param {string} toolName
+ * @returns {boolean}
+ */
+export function toolCalledInSession(session, toolName) {
+  if (!session || typeof session !== 'object' || typeof toolName !== 'string' || !toolName) return false
+  const s = /** @type {Record<string, unknown>} */ (session)
+
+  const toolCalls = safeGet(s, 'toolCalls')
+  if (Array.isArray(toolCalls)) {
+    for (const call of /** @type {unknown[]} */ (toolCalls)) {
+      if (!call || typeof call !== 'object') continue
+      const t = String(safeGet(/** @type {Record<string, unknown>} */ (call), 'tool') ?? '')
+      if (t === toolName || t.endsWith(toolName)) return true
+    }
+  }
+
+  const messages = safeGet(s, 'messages')
+  if (Array.isArray(messages)) {
+    for (const msg of /** @type {unknown[]} */ (messages)) {
+      if (!msg || typeof msg !== 'object') continue
+      const calls = safeGet(/** @type {Record<string, unknown>} */ (msg), 'tool_calls')
+      if (!Array.isArray(calls)) continue
+      for (const call of /** @type {unknown[]} */ (calls)) {
+        if (!call || typeof call !== 'object') continue
+        const c = /** @type {Record<string, unknown>} */ (call)
+        const name = String(safeGet(c, 'name') ?? safeGet(c, 'tool') ?? '')
+        if (name === toolName || name.endsWith(toolName)) return true
+        const fn = safeGet(c, 'function')
+        if (fn && typeof fn === 'object' && String(safeGet(/** @type {Record<string, unknown>} */ (fn), 'name') ?? '') === toolName) {
+          return true
+        }
+      }
+    }
+  }
+  return false
+}
+
+/**
+ * Empty-state copy that separates the two very different "nothing here"
+ * situations: the tool was never pulled from disk (call to action) vs. it was
+ * pulled and the disk really has no data.
+ *
+ * @param {boolean} pulled whether the backing tool was called this session
+ * @param {string} topic what is missing (e.g. "质量门禁证书")
+ * @returns {string}
+ */
+export function diskEmptyStateText(pulled, topic) {
+  const subject = topic || '数据'
+  return pulled
+    ? `已从磁盘拉取：${subject}暂无记录（磁盘无数据）。`
+    : `尚未从磁盘拉取${subject}：数据存放在项目 .iterate/ 下，点「拉取磁盘快照」复制指令发回会话即可回填。`
+}
+
 // ─── Finding filtering ──────────────────────────────────────────────────────
 
 /**
@@ -1543,6 +2068,9 @@ export function buildFilterOptions(findings) {
   /** @type {Record<string, number>} */
   const dimCounts = {}
   for (const f of list) {
+    // TriagePanel feeds report findings in unconditionally — ONE null / junk
+    // element must not kill the whole filter bar with a TypeError.
+    if (!f || typeof f !== 'object') continue
     const sev = String(f.severity ?? 'low')
     const sv = severities.find((s) => s.value === sev)
     if (sv) sv.count++
@@ -1581,7 +2109,9 @@ export function countVerdicts(triageState) {
  * @returns {Record<string, 'keep' | 'skip' | 'ignore'>}
  */
 export function batchSetVerdict(triageState, indices, verdict) {
-  if (verdict !== 'keep' && verdict !== 'skip' && verdict !== 'ignore') return triageState
+  // TRIAGE_VERDICTS is the source of truth for valid verdict keys — anything
+  // outside it (unknown key, junk type) is rejected unchanged.
+  if (!TRIAGE_VERDICTS.includes(verdict)) return triageState
   if (!Array.isArray(indices) || indices.length === 0) return triageState
   const next = { ...triageState }
   for (const idx of indices) {
@@ -1601,6 +2131,8 @@ export function batchSetVerdict(triageState, indices, verdict) {
  * @returns {Record<string, 'keep' | 'skip' | 'ignore'>}
  */
 export function setAllVerdicts(triageState, verdict, indices) {
+  // Delegates to batchSetVerdict, whose TRIAGE_VERDICTS validation rejects an
+  // unknown verdict key here as well (unchanged state is returned).
   const targets = Array.isArray(indices)
     ? indices
     : Object.keys(triageState ?? {}).map(Number)
@@ -1745,6 +2277,21 @@ export const CONFIG_EDIT_FIELDS = [
   { key: 'max_rounds', label: '最大轮数', hint: '正整数' },
   { key: 'review.scope', label: '审查范围', hint: '"full" 或 "changed-only"' },
   { key: 'reasoning_effort', label: '审查推理强度', hint: '"low" / "medium" / "high"，缺省跟随模型默认' },
+  {
+    key: 'validation.commands',
+    label: '验证命令',
+    hint: '数组，每项是一条白名单命令字符串，如 ["npm test","npm run lint"]；每轮验证逐条执行。留空数组 = 不验证（本轮迭代不受任何测试保护）',
+  },
+  {
+    key: 'language',
+    label: '界面语言',
+    hint: '"zh" 或 "en"（默认 "en"）：控制审批理由、防御事件标签等面向人文案的语言',
+  },
+  {
+    key: 'personalization.known_intentional',
+    label: '已知有意问题',
+    hint: '数组，每项 {file, line?, dimension, reason}；命中条目在评审中被跳过。可用分诊面板的「回读已写入条目」核对',
+  },
   { key: 'atomic.max_lines', label: '原子修复上限行数', hint: '正整数' },
   { key: 'git.push_per_round', label: '每轮推送', hint: 'true / false' },
 ]
@@ -1760,13 +2307,19 @@ export function buildConfigEditGuide() {
     '---------------------',
     '配置文件：项目根目录 iterate.config.yaml。',
     '',
+    '⚠ 未配置 validation.commands 时迭代不被保护：每轮 validate 拿到空结果会被当作',
+    '  “验证通过”，等于在没有任何测试保护的情况下继续收敛。第一次启动迭代前，',
+    '  请先给 validation.commands 配上至少一条真实命令（如 npm test）。',
+    '',
     '可编辑字段：',
     ...CONFIG_EDIT_FIELDS.map((f) => `- ${f.key}（${f.label}）：${f.hint}`),
     '',
     '让模型帮你改：',
     '1. 调用 iterate_config({ operation: "read" }) 查看当前配置；',
-    '2. 说明想改的字段，例如「把 max_rounds 改成 5，dimensions 只保留 correctness 和 security」；',
+    '2. 说明想改的字段，例如「把 max_rounds 改成 5，validation.commands 加上 npm test」；',
     '3. 模型会调用 iterate_config({ operation: "write", updates: {...} }) 写入，写入前自动备份，失败自动回滚。',
+    '',
+    '也可以用设置页的“选字段 → 生成写入指令”直接复制第 3 步的指令粘贴给模型。',
   ]
   return lines.join('\n')
 }
@@ -1784,6 +2337,48 @@ export function buildConfigEditInstruction(desiredChanges) {
   return `请调用 \`iterate_config\` 写入以下配置更新：\n\n\`\`\`json\n${payload}\n\`\`\``
 }
 
+/** Placeholder for a config value the user still has to supply. */
+export const CONFIG_VALUE_PLACEHOLDER = '<由模型填写：该字段的新值>'
+
+/**
+ * Look up an editable config field by its dotted key (gap #8).
+ *
+ * @param {string} key
+ * @returns {{ key: string, label: string, hint: string } | null}
+ */
+export function configFieldByKey(key) {
+  if (typeof key !== 'string' || !key) return null
+  return CONFIG_EDIT_FIELDS.find((f) => f.key === key) ?? null
+}
+
+/**
+ * Gap #8: turn a single selected config field into a paste-able write
+ * instruction. `value` may be omitted, in which case an explicit
+ * "filled in by the model" placeholder is emitted so the user knows what to
+ * complete (same convention as the other instruction builders).
+ *
+ * @param {string} key
+ * @param {unknown} [value]
+ * @returns {string}
+ */
+export function buildConfigFieldInstruction(key, value) {
+  const field = configFieldByKey(key)
+  const label = field ? field.label : key
+  const hint = field ? field.hint : '见 iterate.config.yaml'
+  const updates = { [key]: value === undefined ? CONFIG_VALUE_PLACEHOLDER : value }
+  // Delegate the payload to `buildConfigEditInstruction` so the multi-field
+  // builder stays a live code path (it used to be test-only dead code).
+  const payload = buildConfigEditInstruction(updates)
+  return [
+    `配置字段 · ${label}（${key}）`,
+    `字段说明：${hint}`,
+    '',
+    payload,
+    '',
+    '写入前请先 \`operation: "read"\` 展示当前值；写入由工具自动备份，失败自动回滚。',
+  ].join('\n')
+}
+
 /**
  * Keyboard shortcut → triage verdict mapping (used by the triage panel).
  * @type {Record<string, 'keep' | 'skip' | 'ignore'>}
@@ -1805,7 +2400,10 @@ export const VERDICT_SHORTCUTS = {
  * @returns {'keep' | 'skip' | 'ignore' | null}
  */
 export function keyToVerdict(key) {
-  return VERDICT_SHORTCUTS[key] ?? null
+  const verdict = VERDICT_SHORTCUTS[key]
+  // TRIAGE_VERDICTS is the verdict source of truth: a shortcut entry whose
+  // value falls outside the verdict set is not a triage shortcut.
+  return verdict !== undefined && TRIAGE_VERDICTS.includes(verdict) ? verdict : null
 }
 
 // ─── Select-all keys ────────────────────────────────────────────────────────
@@ -1940,20 +2538,26 @@ export function filterTimelineEntries(entries, opts) {
 }
 
 /**
- * Serialize the full observatory state (manifest + live feed) into a JSON
- * string the client can copy/export. Always includes an `exportedAt` stamp and
- * guards against non-serializable / oversized payloads by falling back to the
- * manifest only.
+ * Serialize the full observatory state (manifest + live feed + pulled disk
+ * snapshots) into a JSON string the client can copy/export. Always includes an
+ * `exportedAt` stamp and guards against non-serializable / oversized payloads
+ * by falling back to the manifest only.
+ *
+ * Gap #11: `extra` lets the caller attach the disk-side artifacts
+ * (qualityGate / experienceBank / defenseEvents / report) that the export
+ * previously dropped, so the copy actually captures the on-disk state.
  *
  * @param {unknown} manifest
  * @param {unknown} live
+ * @param {Record<string, unknown>} [extra]
  * @returns {string}
  */
-export function serializeObservatoryExport(manifest, live) {
+export function serializeObservatoryExport(manifest, live, extra) {
   const payload = {
     exportedAt: new Date().toISOString(),
     manifest: manifest && typeof manifest === 'object' ? manifest : null,
     live: Array.isArray(live) ? live : [],
+    ...pickExportExtras(extra),
   }
   try {
     return JSON.stringify(payload, null, 2)
@@ -1963,6 +2567,105 @@ export function serializeObservatoryExport(manifest, live) {
   }
 }
 
+/** Disk-side keys the export recognizes (gap #11). */
+export const EXPORT_EXTRA_KEYS = ['qualityGate', 'experienceBank', 'defenseEvents', 'report']
+
+/**
+ * Copy only the known extra keys, dropping `undefined` so the export shape
+ * stays stable when a snapshot has not been pulled yet.
+ *
+ * @param {unknown} extra
+ * @returns {Record<string, unknown>}
+ */
+function pickExportExtras(extra) {
+  const out = {}
+  if (!extra || typeof extra !== 'object') return out
+  for (const key of EXPORT_EXTRA_KEYS) {
+    if (!Object.prototype.hasOwnProperty.call(extra, key)) continue
+    const value = extra[key]
+    if (value === undefined) continue
+    out[key] = value
+  }
+  return out
+}
+
+/**
+ * Gap #13: build the cross-round comparison table for a single session.
+ * One row per round: findings raised, findings fixed, severity mix and the
+ * validation command outcomes recorded on the manifest.
+ *
+ * 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
+ * @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) {
+  const rounds = new Map()
+  const rowsFor = (round) => {
+    const n = Number(round)
+    const key = Number.isFinite(n) && n > 0 ? Math.floor(n) : 0
+    if (!rounds.has(key)) {
+      rounds.set(key, { round: key, findings: 0, fixed: 0, severities: Object.create(null), validations: [] })
+    }
+    return rounds.get(key)
+  }
+
+  const list = report && Array.isArray(report.findings) ? report.findings : []
+  for (const f of list) {
+    if (!f || typeof f !== 'object') continue
+    const row = rowsFor(f.round)
+    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
+  }
+
+  const vals = Array.isArray(validations) ? validations : []
+  for (const v of vals) {
+    if (!v || typeof v !== 'object') continue
+    const row = rowsFor(v.round)
+    row.validations.push({
+      command: typeof v.command === 'string' ? v.command : '',
+      exitCode: typeof v.exitCode === 'number' ? v.exitCode : null,
+      allowed: v.allowed === true,
+    })
+  }
+
+  return [...rounds.values()]
+    .filter((r) => r.round > 0)
+    .sort((a, b) => a.round - b.round)
+    .map((r) => ({ ...r, severities: { ...r.severities } }))
+}
+
+/**
+ * Gap #5: decide what the convergence dashboard should say.
+ *
+ * - `running` — a manifest exists and the run has not stopped: show the live
+ *   round/phase instead of the onboarding copy (gap #5's actual bug: the old
+ *   check was `!transcript`, so a run in progress still rendered "how to start").
+ * - `done`    — a manifest exists but the run is no longer active: show the
+ *   outcome (with `stoppedReason` when the workflow recorded one).
+ * - `empty`   — nothing has run yet: show the start-instruction prompt.
+ *
+ * @param {unknown} transcript normalized transcript (or a raw manifest)
+ * @returns {{state: 'running'|'done'|'empty', round: number, phase: string, stoppedReason: string}}
+ */
+export function dashboardRunState(transcript) {
+  const t = transcript && typeof transcript === 'object' ? transcript : null
+  if (!t) return { state: 'empty', round: 0, phase: '', stoppedReason: '' }
+  const rawRound = Number(t.round)
+  const round = Number.isFinite(rawRound) && rawRound > 0 ? Math.floor(rawRound) : 1
+  const stoppedReason = typeof t.stoppedReason === 'string' ? t.stoppedReason.trim() : ''
+  return {
+    state: t.active === true ? 'running' : 'done',
+    round,
+    phase: latestPhase(t.phases),
+    stoppedReason,
+  }
+}
+
 /**
  * Latest non-empty workflow phase name (plan / review / fix / validate /
  * report …) from the transcript manifest's phase list. The last recorded