iterate-plugin 3.6.0 → 3.7.0

package/lib/parse.js

@@ -207,9 +207,15 @@ export function countSessionImages(session) {
 
 /**
  * Check whether `obj` is a valid ReviewReport-like object.
- * The minimum requirement: an object with `convergence` (object),
+ * The minimum requirement: an object with `convergence` (a RECORD),
  * `findings` (array), and `rounds` (array).
  *
+ * The convergence guard is also the TranscriptManifest discriminator: a
+ * manifest carries `convergence` / `rounds` / `findings` too, but its
+ * convergence is the per-round count SERIES (an array). Since
+ * `typeof [] === 'object'` in JS, only an explicit array rejection keeps the
+ * two shapes apart — see `isTranscriptManifest`.
+ *
  * @param {unknown} obj
  * @returns {obj is Record<string, unknown>}
  */
@@ -217,12 +223,8 @@ export function isReviewReport(obj) {
   if (!obj || typeof obj !== 'object') return false
   const o = /** @type {Record<string, unknown>} */ (obj)
   const convergence = safeGet(o, 'convergence')
-  return (
-    typeof convergence === 'object' &&
-    convergence !== null &&
-    Array.isArray(safeGet(o, 'findings')) &&
-    Array.isArray(safeGet(o, 'rounds'))
-  )
+  if (!convergence || typeof convergence !== 'object' || Array.isArray(convergence)) return false
+  return Array.isArray(safeGet(o, 'findings')) && Array.isArray(safeGet(o, 'rounds'))
 }
 
 /**
@@ -585,7 +587,13 @@ export function scanSessionForTranscript(session) {
     }
   }
 
-  return null
+  // Fallback: a host snapshot without the tool-call envelope (a restored
+  // transcript, a rehydrated turn, a shell that surfaces artifacts directly)
+  // may still carry a manifest somewhere in the tree. Deep-scan for it so the
+  // dashboard and the observatory keep filling instead of degrading to the
+  // first-run empty state. The manifest is returned RAW — callers normalize.
+  const loose = findFirstInObject(session, isTranscriptManifest)
+  return loose ? /** @type {Record<string, unknown>} */ (loose) : null
 }
 
 /**
@@ -975,10 +983,16 @@ export function normalizeQualityGateSnapshot(raw) {
  */
 export function scanSessionForQualityGate(session) {
   const node = latestToolResultNode(session, 'iterate_quality_gate', findQualityGateInObject)
-  if (node === null) return null
-  const found = findQualityGateInObject(node)
-  if (!found) return null
-  return normalizeQualityGateSnapshot(found)
+  if (node !== null) {
+    const found = findQualityGateInObject(node)
+    if (found) return normalizeQualityGateSnapshot(found)
+  }
+  // Fallback: a host snapshot without the tool-call envelope (a restored
+  // transcript, a rehydrated turn, a shell that surfaces artifacts directly)
+  // still carries the snapshot somewhere in the tree — deep-scan for it so
+  // the panel fills instead of claiming "not pulled yet".
+  const loose = findFirstInObject(session, isQualityGateSnapshot)
+  return loose ? normalizeQualityGateSnapshot(loose) : null
 }
 
 /**
@@ -1034,10 +1048,13 @@ export function normalizeExperienceBankResult(raw) {
  */
 export function scanSessionForExperienceBank(session) {
   const node = latestToolResultNode(session, 'iterate_experience', findExperienceResultInObject)
-  if (node === null) return null
-  const found = findExperienceResultInObject(node)
-  if (!found) return null
-  return normalizeExperienceBankResult(found)
+  if (node !== null) {
+    const found = findExperienceResultInObject(node)
+    if (found) return normalizeExperienceBankResult(found)
+  }
+  // Same deep-scan fallback as the quality-gate scanner (see above).
+  const loose = findFirstInObject(session, isExperienceBankResult)
+  return loose ? normalizeExperienceBankResult(loose) : null
 }
 
 /**
@@ -1098,10 +1115,13 @@ export function normalizeDefenseEventsResult(raw) {
  */
 export function scanSessionForDefenseEvents(session) {
   const node = latestToolResultNode(session, 'iterate_defense_events', findDefenseResultInObject)
-  if (node === null) return null
-  const found = findDefenseResultInObject(node)
-  if (!found) return null
-  return normalizeDefenseEventsResult(found)
+  if (node !== null) {
+    const found = findDefenseResultInObject(node)
+    if (found) return normalizeDefenseEventsResult(found)
+  }
+  // Same deep-scan fallback as the quality-gate scanner (see above).
+  const loose = findFirstInObject(session, isDefenseEventsResult)
+  return loose ? normalizeDefenseEventsResult(loose) : null
 }
 
 // ─── Run-summary / meta-review verdict detection ─────────────────────────────
@@ -1963,10 +1983,16 @@ export function toolCalledInSession(session, toolName) {
  *
  * @param {boolean} pulled whether the backing tool was called this session
  * @param {string} topic what is missing (e.g. "质量门禁证书")
+ * @param {'zh'|'en'} [lang] UI language (the caller localizes `topic` itself)
  * @returns {string}
  */
-export function diskEmptyStateText(pulled, topic) {
-  const subject = topic || '数据'
+export function diskEmptyStateText(pulled, topic, lang = 'zh') {
+  const subject = topic || (lang === 'en' ? 'data' : '数据')
+  if (lang === 'en') {
+    return pulled
+      ? `Pulled from disk: ${subject} has no records yet (the disk is empty).`
+      : `Not pulled from disk yet: ${subject} lives under the project's .iterate/ — copy the "Pull disk snapshot" instruction back into the session and it will fill in.`
+  }
   return pulled
     ? `已从磁盘拉取：${subject}暂无记录（磁盘无数据）。`
     : `尚未从磁盘拉取${subject}：数据存放在项目 .iterate/ 下，点「拉取磁盘快照」复制指令发回会话即可回填。`
@@ -2223,27 +2249,40 @@ export function trendMax(points) {
 //
 // Every value the iterate loop can report as `stoppedReason` — including the
 // schema-retry batch (schema_invalid / no_usable_reviewer_output / inconclusive)
-// — maps to a concrete Chinese label. Unknown values still get a readable
-// default instead of a bare "已结束". Kept in parse.js so both the client
-// observatory badge and Node unit tests share one source of truth.
+// — maps to a concrete label in zh and en. Unknown values still get a readable
+// default instead of a bare "已结束" / "Done". Kept in parse.js so both the
+// client observatory badge and Node unit tests share one source of truth.
 
 /**
- * Chinese badge label for a run's `stoppedReason`, or null/undefined-safe.
+ * Badge label for a run's `stoppedReason`, or null/undefined-safe.
+ *
+ * @param {unknown} reason
+ * @param {'zh'|'en'} [lang] UI language (default zh, the model-facing default)
  *
  * @param {string | null | undefined} reason
  * @returns {string}
  */
-export function stoppedReasonLabel(reason) {
-  switch (reason) {
-    case 'converged': return '已结束 · 已收敛（无新发现）'
-    case 'max_rounds_reached': return '已结束 · 达到轮数上限'
-    case 'aborted_by_validation': return '已结束 · 验证失败后回滚停止'
-    case 'aborted_by_config': return '已结束 · 验证命令不在白名单（配置需修复）'
-    case 'inconclusive': return '已结束 · 轮次结论不明（审查输出无效）'
-    case 'schema_invalid': return '已结束 · 审查输出连续 schema 校验失败'
-    case 'no_usable_reviewer_output': return '已结束 · 无可用审查输出'
-    default: return reason ? `已结束 · ${reason}` : '已结束'
-  }
+export function stoppedReasonLabel(reason, lang = 'zh') {
+  const zh = {
+    converged: '已结束 · 已收敛（无新发现）',
+    max_rounds_reached: '已结束 · 达到轮数上限',
+    aborted_by_validation: '已结束 · 验证失败后回滚停止',
+    aborted_by_config: '已结束 · 验证命令不在白名单（配置需修复）',
+    inconclusive: '已结束 · 轮次结论不明（审查输出无效）',
+    schema_invalid: '已结束 · 审查输出连续 schema 校验失败',
+    no_usable_reviewer_output: '已结束 · 无可用审查输出',
+  }
+  const en = {
+    converged: 'Done \u00b7 converged (no new findings)',
+    max_rounds_reached: 'Done \u00b7 reached the round limit',
+    aborted_by_validation: 'Done \u00b7 rolled back after a validation failure',
+    aborted_by_config: 'Done \u00b7 validation command not allow-listed (config needs fixing)',
+    inconclusive: 'Done \u00b7 inconclusive rounds (invalid review output)',
+    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}` : '已结束')
 }
 
 // ─── Completion notification ────────────────────────────────────────────────
@@ -2252,48 +2291,93 @@ export function stoppedReasonLabel(reason) {
  * One-line completion summary for notifications ("已收敛 / 已达最大轮数").
  *
  * @param {Record<string, unknown>} report
+ * @param {'zh'|'en'} [lang] UI language
  * @returns {string}
  */
-export function buildCompletionSummary(report) {
+export function buildCompletionSummary(report, lang = 'zh') {
   const conv = /** @type {Record<string, unknown>} */ (report.convergence ?? {})
   const rounds = getCurrentRound(report)
   const total = getTotalRounds(report)
   const stats = severityStats(report)
   const converged = conv.converged === true
-  const reason = converged ? '已收敛' : `已达最大轮数 ${total}`
   const totalFindings = stats.critical + stats.high + stats.medium + stats.low
+  if (lang === 'en') {
+    const reason = converged ? 'converged' : `reached the round limit ${total}`
+    return `iterate review complete \u00b7 ${rounds}/${total} rounds \u00b7 ${totalFindings} findings \u00b7 ${reason}`
+  }
+  const reason = converged ? '已收敛' : `已达最大轮数 ${total}`
   return `iterate 评审完成 · ${rounds}/${total} 轮 · ${totalFindings} 项发现 · ${reason}`
 }
 
 // ─── Config edit guidance ───────────────────────────────────────────────────
 
 /**
- * Editable config fields (key + label + hint), used by the settings guide.
- * @type {Array<{ key: string, label: string, hint: string }>}
+ * Editable config fields, used by the settings picker (rendered in the UI) and
+ * by the copy-paste guide / instruction builders (model-facing, always zh).
+ * `label`/`hint` are `{ zh, en }` pairs — the UI localizes them with
+ * `field.label[getLang()]`, while the guide builders below read `.zh`.
+ * @type {Array<{ key: string, label: { zh: string, en: string }, hint: { zh: string, en: string } }>}
  */
 export const CONFIG_EDIT_FIELDS = [
-  { key: 'goal', label: '目标', hint: '一句话描述本次迭代目标（字符串）' },
-  { key: 'dimensions', label: '审查维度', hint: '数组，如 ["correctness","security"]' },
-  { key: 'max_rounds', label: '最大轮数', hint: '正整数' },
-  { key: 'review.scope', label: '审查范围', hint: '"full" 或 "changed-only"' },
-  { key: 'reasoning_effort', label: '审查推理强度', hint: '"low" / "medium" / "high"，缺省跟随模型默认' },
+  {
+    key: 'goal',
+    label: { zh: '目标', en: 'Goal' },
+    hint: { zh: '一句话描述本次迭代目标（字符串）', en: "One-sentence description of this iteration's goal (a string)" },
+  },
+  {
+    key: 'dimensions',
+    label: { zh: '审查维度', en: 'Review dimensions' },
+    hint: { zh: '数组，如 ["correctness","security"]', en: 'Array, e.g. ["correctness","security"]' },
+  },
+  {
+    key: 'max_rounds',
+    label: { zh: '最大轮数', en: 'Max rounds' },
+    hint: { zh: '正整数', en: 'Positive integer' },
+  },
+  {
+    key: 'review.scope',
+    label: { zh: '审查范围', en: 'Review scope' },
+    hint: { zh: '"full" 或 "changed-only"', en: '"full" or "changed-only"' },
+  },
+  {
+    key: 'reasoning_effort',
+    label: { zh: '审查推理强度', en: 'Review reasoning effort' },
+    hint: { zh: '"low" / "medium" / "high"，缺省跟随模型默认', en: '"low" / "medium" / "high"; omitted = follow the model default' },
+  },
   {
     key: 'validation.commands',
-    label: '验证命令',
-    hint: '数组，每项是一条白名单命令字符串，如 ["npm test","npm run lint"]；每轮验证逐条执行。留空数组 = 不验证（本轮迭代不受任何测试保护）',
+    label: { zh: '验证命令', en: 'Validation commands' },
+    hint: {
+      zh: '数组，每项是一条白名单命令字符串，如 ["npm test","npm run lint"]；每轮验证逐条执行。留空数组 = 不验证（本轮迭代不受任何测试保护）',
+      en: 'Array of allow-listed command strings, e.g. ["npm test","npm run lint"]; run one by one every round. An empty array = no verification (this iteration runs with no test protection)',
+    },
   },
   {
     key: 'language',
-    label: '界面语言',
-    hint: '"zh" 或 "en"（默认 "en"）：控制审批理由、防御事件标签等面向人文案的语言',
+    label: { zh: '界面语言', en: 'Interface language' },
+    hint: {
+      zh: '"zh" 或 "en"（默认 "en"）：控制审批理由、防御事件标签等面向人文案的语言',
+      en: '"zh" or "en" (default "en"): language of human-facing copy such as approval rationales and defense-event labels',
+    },
   },
   {
     key: 'personalization.known_intentional',
-    label: '已知有意问题',
-    hint: '数组，每项 {file, line?, dimension, reason}；命中条目在评审中被跳过。可用分诊面板的「回读已写入条目」核对',
+    label: { zh: '已知有意问题', en: 'Known intentional issues' },
+    hint: {
+      zh: '数组，每项 {file, line?, dimension, reason}；命中条目在评审中被跳过。可用分诊面板的「回读已写入条目」核对',
+      en: 'Array of {file, line?, dimension, reason}; findings hitting an entry are skipped in review. Verify via the triage panel\'s "read back written entries"',
+    },
+  },
+  {
+    key: 'atomic.max_lines',
+    label: { zh: '原子修复上限行数', en: 'Atomic fix line cap' },
+    hint: { zh: '正整数', en: 'Positive integer' },
+  },
+  {
+    key: 'git.push_per_round',
+    label: { zh: '每轮推送', en: 'Push per round' },
+    hint: { zh: 'true / false', en: 'true / false' },
   },
-  { key: 'atomic.max_lines', label: '原子修复上限行数', hint: '正整数' },
-  { key: 'git.push_per_round', label: '每轮推送', hint: 'true / false' },
 ]
 
 /**
@@ -2312,7 +2396,7 @@ export function buildConfigEditGuide() {
     '  请先给 validation.commands 配上至少一条真实命令（如 npm test）。',
     '',
     '可编辑字段：',
-    ...CONFIG_EDIT_FIELDS.map((f) => `- ${f.key}（${f.label}）：${f.hint}`),
+    ...CONFIG_EDIT_FIELDS.map((f) => `- ${f.key}（${f.label.zh}）：${f.hint.zh}`),
     '',
     '让模型帮你改：',
     '1. 调用 iterate_config({ operation: "read" }) 查看当前配置；',
@@ -2344,7 +2428,7 @@ 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}
+ * @returns {{ key: string, label: { zh: string, en: string }, hint: { zh: string, en: string } } | null}
  */
 export function configFieldByKey(key) {
   if (typeof key !== 'string' || !key) return null
@@ -2363,8 +2447,9 @@ export function configFieldByKey(key) {
  */
 export function buildConfigFieldInstruction(key, value) {
   const field = configFieldByKey(key)
-  const label = field ? field.label : key
-  const hint = field ? field.hint : '见 iterate.config.yaml'
+  // Model-facing instruction text: always zh, like every other builder here.
+  const label = field ? field.label.zh : key
+  const hint = field ? field.hint.zh : '见 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).
@@ -2379,6 +2464,116 @@ export function buildConfigFieldInstruction(key, value) {
   ].join('\n')
 }
 
+// ─── Config read-back (write → read-back loop) ──────────────────────────────
+//
+// The triage panel got a read-back instruction (#7); the config editor only
+// generated writes, so there was no way to SEE what the file actually says
+// after pasting an instruction. These three pieces close that loop: an
+// instruction the settings card copies, a session scanner that picks the
+// echoed result back up, and a dotted-path resolver that surfaces the value
+// of the field the user currently has selected.
+
+/**
+ * Copy-paste instruction that makes the model call `iterate_config` read and
+ * echo the full result (including `config`) into the session, where the
+ * settings card can display it.
+ *
+ * @returns {string}
+ */
+export function buildConfigReadInstruction() {
+  return (
+    '请调用 `iterate_config` 回读当前生效配置，并把完整结果（含 config 字段）原样回显，' +
+    '供我核对界面上展示的当前值：\n\n' +
+    '```json\n' +
+    `${JSON.stringify({ operation: 'read' }, null, 2)}\n` +
+    '```'
+  )
+}
+
+/**
+ * Top-level keys of an iterate config, derived from the editable field list
+ * so a newly editable section is covered by the predicate automatically.
+ * @type {string[]}
+ */
+const CONFIG_TOP_LEVEL_KEYS = [...new Set(CONFIG_EDIT_FIELDS.map((f) => f.key.split('.')[0]))]
+
+/**
+ * Is `v` an effective iterate config? Requires several known top-level keys:
+ * `loadEffectiveConfig` always merges the built-in defaults, so a real config
+ * is complete — while a stray `{ goal: ... }` record elsewhere in the
+ * transcript cannot impersonate one.
+ *
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+export function isEffectiveConfig(v) {
+  if (!v || typeof v !== 'object' || Array.isArray(v)) return false
+  const rec = /** @type {Record<string, unknown>} */ (v)
+  let hits = 0
+  for (const key of CONFIG_TOP_LEVEL_KEYS) {
+    if (Object.hasOwn(rec, key)) hits += 1
+    if (hits >= 3) return true
+  }
+  return false
+}
+
+/**
+ * Locate the config inside one `iterate_config` tool result. Reads and writes
+ * both report it under `config`; a section read (`data`) is deliberately not
+ * accepted because it is only a slice.
+ *
+ * @param {unknown} v
+ * @returns {Record<string, unknown> | null}
+ */
+export function findConfigInResult(v) {
+  if (!v || typeof v !== 'object' || Array.isArray(v)) return null
+  const rec = /** @type {Record<string, unknown>} */ (v)
+  const cfg = safeGet(rec, 'config')
+  if (isEffectiveConfig(cfg)) return /** @type {Record<string, unknown>} */ (cfg)
+  return isEffectiveConfig(v) ? rec : null
+}
+
+/**
+ * Latest effective config echoed into the session: the newest full
+ * `iterate_config` result (read or post-write), falling back to a deep scan
+ * for a config that reached the stream without the tool envelope (restored
+ * transcript, host that surfaces artifacts directly).
+ *
+ * @param {unknown} session
+ * @returns {Record<string, unknown> | null}
+ */
+export function scanSessionForConfigRead(session) {
+  const node = latestToolResultNode(session, 'iterate_config', findConfigInResult)
+  if (node !== null) {
+    const cfg = findConfigInResult(node)
+    if (cfg) return cfg
+  }
+  const loose = findFirstInObject(session, isEffectiveConfig)
+  return loose ? /** @type {Record<string, unknown>} */ (loose) : null
+}
+
+/**
+ * Resolve a dotted editable-field key (`validation.commands`, `review.scope`)
+ * against a read-back config.
+ *
+ * @param {Record<string, unknown> | null | undefined} config
+ * @param {string} key dotted field key from CONFIG_EDIT_FIELDS
+ * @returns {{ resolved: boolean, value: unknown }} `value` is undefined when unresolved
+ */
+export function configValueByPath(config, key) {
+  if (!config || typeof config !== 'object' || typeof key !== 'string' || !key) {
+    return { resolved: false, value: undefined }
+  }
+  let node = /** @type {unknown} */ (config)
+  for (const part of key.split('.')) {
+    if (!node || typeof node !== 'object' || Array.isArray(node)) return { resolved: false, value: undefined }
+    const rec = /** @type {Record<string, unknown>} */ (node)
+    if (!Object.hasOwn(rec, part)) return { resolved: false, value: undefined }
+    node = rec[part]
+  }
+  return { resolved: true, value: node }
+}
+
 /**
  * Keyboard shortcut → triage verdict mapping (used by the triage panel).
  * @type {Record<string, 'keep' | 'skip' | 'ignore'>}

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "iterate-plugin",
-  "version": "3.6.0",
+  "version": "3.7.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-plugin.git"
+    "url": "https://github.com/jingzhao-l/iterate-skill.git",
+    "directory": "harness/iterate-plugin"
   },
-  "homepage": "https://github.com/jingzhao-l/iterate-plugin",
+  "homepage": "https://github.com/jingzhao-l/iterate-skill/tree/main/harness/iterate-plugin",
   "bugs": {
-    "url": "https://github.com/jingzhao-l/iterate-plugin/issues"
+    "url": "https://github.com/jingzhao-l/iterate-skill/issues"
   },
   "keywords": [
     "dsh-plugin",
@@ -45,7 +46,8 @@
         "0.1.7-rc.2": "compatible",
         "0.2.0-rc.1": "compatible",
         "0.2.0-rc.2": "compatible",
-        "0.2.1-alpha.1": "compatible"
+        "0.2.1-alpha.1": "compatible",
+        "0.2.1-alpha.2": "compatible"
       }
     },
     "client": {
@@ -76,25 +78,28 @@
     "build": "tsc -p tsconfig.build.json",
     "build:client": "node scripts/build-client.mjs",
     "prepublishOnly": "npm run build && npm run build:client",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json && tsc --noEmit -p tsconfig.client.json",
     "typecheck:client": "tsc --noEmit -p tsconfig.client.json",
     "test": "tsx --test test/*.test.ts",
     "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.1",
-    "@deepseek-ai/dsh-util-values": "0.2.1-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"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-jobs": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-session": "0.2.1-alpha.1",
+    "@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",
     "@types/js-yaml": "4.0.9",
     "@types/node": "22.15.0",
     "@types/react": "19.2.2",
     "esbuild": "0.25.12",
+    "jsdom": "26.1.0",
+    "react": "19.2.2",
+    "react-dom": "19.2.2",
     "tsx": "4.20.3",
     "typescript": "5.9.3"
   },