iterate-plugin 3.11.0 → 3.12.0

package/lib/client.js

@@ -1,4 +1,4 @@
-/* iterate-plugin client source-digest: e3baa31a1f6965343996a15a146b539f5c1d02547014ae0cf0b2f90809967b7e */
+/* iterate-plugin client source-digest: 408ff45e22a5041e34cdeb7ccd786225658f6c1fe52a7bb5233fc35450546683 */
 window.__ModuleLoader__.load({ id: "iterate-plugin", factory: (require) => {
 var module = { exports: {} };
 var exports = module.exports;
@@ -854,6 +854,62 @@ function scanSessionForDefenseEvents(session) {
   const loose = findFirstInObject(session, isDefenseEventsResult);
   return loose ? normalizeDefenseEventsResult(loose) : null;
 }
+function isPreflightReport(obj) {
+  if (!obj || typeof obj !== "object") return false;
+  const o = (
+    /** @type {Record<string, unknown>} */
+    obj
+  );
+  const ready = safeGet(o, "ready");
+  const checks = safeGet(o, "checks");
+  const blocking = safeGet(o, "blocking");
+  const warnings = safeGet(o, "warnings");
+  return typeof ready === "boolean" && Array.isArray(checks) && (typeof blocking === "number" || typeof warnings === "number");
+}
+function findPreflightReportInObject(obj) {
+  return findFirstInObject(obj, (o) => isPreflightReport(o));
+}
+function normalizePreflightReport(raw) {
+  const src = raw && typeof raw === "object" ? (
+    /** @type {Record<string, unknown>} */
+    raw
+  ) : {};
+  const asNum = (v) => typeof v === "number" && Number.isFinite(v) ? v : 0;
+  const asStr = (v) => typeof v === "string" ? v : "";
+  const checks = Array.isArray(safeGet(src, "checks")) ? safeGet(src, "checks") : [];
+  return {
+    ok: safeGet(src, "ok") !== false,
+    ready: safeGet(src, "ready") === true,
+    blocking: asNum(safeGet(src, "blocking")),
+    warnings: asNum(safeGet(src, "warnings")),
+    error: asStr(safeGet(src, "error")) || null,
+    checks: (
+      /** @type {unknown[]} */
+      checks.map((c) => {
+        const rec = (
+          /** @type {Record<string, unknown>} */
+          c && typeof c === "object" ? c : {}
+        );
+        const status = safeGet(rec, "status");
+        const detail = safeGet(rec, "detail");
+        return {
+          id: asStr(safeGet(rec, "id")),
+          status: status === "pass" || status === "warn" || status === "fail" ? status : "warn",
+          detail: detail && typeof detail === "object" ? detail : {}
+        };
+      })
+    )
+  };
+}
+function scanSessionForPreflight(session) {
+  const node = latestToolResultNode(session, "iterate_preflight", findPreflightReportInObject);
+  if (node !== null) {
+    const found = findPreflightReportInObject(node);
+    if (found) return normalizePreflightReport(found);
+  }
+  const loose = findFirstInObject(session, isPreflightReport);
+  return loose ? normalizePreflightReport(loose) : null;
+}
 function isRunSummary(obj) {
   if (!obj || typeof obj !== "object") return false;
   const o = (
@@ -1280,6 +1336,13 @@ function buildQualityGateClearInstruction() {
 ${JSON.stringify({ operation: "clear" }, null, 2)}
 \`\`\``;
 }
+function buildPreflightInstruction() {
+  return `\u8BF7\u8C03\u7528 \`iterate_preflight\` \u8FD0\u884C\u5F00\u8DD1\u524D\u9884\u68C0\uFF08\u53EA\u8BFB\uFF1A\u6821\u9A8C validation.commands\u3001git\u3001\u810F\u5DE5\u4F5C\u533A\u3001\u9648\u65E7\u8D28\u91CF\u95E8\u7981\u4E0E\u4E2D\u65AD\u65AD\u70B9\uFF09\uFF1A
+
+\`\`\`json
+${JSON.stringify({}, null, 2)}
+\`\`\``;
+}
 function buildRollbackInstruction(id) {
   return `\u8BF7\u8C03\u7528 \`iterate_rollback\` \u56DE\u6EDA\u4EE5\u4E0B\u4FEE\u590D\uFF1A
 
@@ -1555,13 +1618,35 @@ function buildCompletionSummary(report, lang = "zh") {
   const stats = severityStats(report);
   const converged = conv.converged === true;
   const totalFindings = stats.critical + stats.high + stats.medium + stats.low;
+  const stopped = typeof conv.stoppedReason === "string" ? conv.stoppedReason : typeof report.stoppedReason === "string" ? report.stoppedReason : "";
+  const reason = stopped ? completionReason(stopped, lang, total) : converged ? lang === "en" ? "converged" : "\u5DF2\u6536\u655B" : lang === "en" ? `reached the round limit ${total}` : `\u5DF2\u8FBE\u6700\u5927\u8F6E\u6570 ${total}`;
   if (lang === "en") {
-    const reason2 = converged ? "converged" : `reached the round limit ${total}`;
-    return `iterate review complete \xB7 ${rounds}/${total} rounds \xB7 ${totalFindings} findings \xB7 ${reason2}`;
+    return `iterate review complete \xB7 ${rounds}/${total} rounds \xB7 ${totalFindings} findings \xB7 ${reason}`;
   }
-  const reason = converged ? "\u5DF2\u6536\u655B" : `\u5DF2\u8FBE\u6700\u5927\u8F6E\u6570 ${total}`;
   return `iterate \u8BC4\u5BA1\u5B8C\u6210 \xB7 ${rounds}/${total} \u8F6E \xB7 ${totalFindings} \u9879\u53D1\u73B0 \xB7 ${reason}`;
 }
+function completionReason(reason, lang, total) {
+  const zh = {
+    converged: "\u5DF2\u6536\u655B",
+    max_rounds_reached: `\u5DF2\u8FBE\u6700\u5927\u8F6E\u6570 ${total}`,
+    aborted_by_validation: "\u9A8C\u8BC1\u5931\u8D25\u540E\u56DE\u6EDA",
+    aborted_by_config: "\u9A8C\u8BC1\u547D\u4EE4\u672A\u5728\u767D\u540D\u5355",
+    inconclusive: "\u8F6E\u6B21\u7ED3\u8BBA\u4E0D\u660E",
+    schema_invalid: "\u5BA1\u67E5\u8F93\u51FA schema \u6821\u9A8C\u5931\u8D25",
+    no_usable_reviewer_output: "\u65E0\u53EF\u7528\u5BA1\u67E5\u8F93\u51FA"
+  };
+  const en = {
+    converged: "converged",
+    max_rounds_reached: `reached the round limit ${total}`,
+    aborted_by_validation: "rolled back after a validation failure",
+    aborted_by_config: "validation command not allow-listed",
+    inconclusive: "inconclusive rounds",
+    schema_invalid: "review output failed schema validation",
+    no_usable_reviewer_output: "no usable review output"
+  };
+  const table = lang === "en" ? en : zh;
+  return Object.hasOwn(table, reason) ? table[reason] : reason;
+}
 var CONFIG_EDIT_FIELDS = [
   {
     key: "goal",
@@ -2658,6 +2743,38 @@ var EN = {
   \u6E05\u9664\u7C7B\u578B\u7B5B\u9009: "Clear type filter",
   "\u9632\u7EBF\uFF1A{a0}": "Defense: {a0}",
   \u6CA1\u6709\u5339\u914D\u8BE5\u7C7B\u578B\u7684\u9632\u5FA1\u4E8B\u4EF6: "No defense events of this type",
+  // ── F11 preflight ────────────────────────────────────────────────────────
+  \u5F00\u8DD1\u9884\u68C0: "Preflight",
+  \u5F85\u9884\u68C0: "Not run yet",
+  \u672A\u5C31\u7EEA: "Not ready",
+  "\u590D\u5236 iterate_preflight \u9884\u68C0\u6307\u4EE4\uFF08\u542B JSON \u53C2\u6570\uFF09": "Copy the iterate_preflight readiness instruction (JSON arguments included)",
+  \u8FD0\u884C\u9884\u68C0: "Run preflight",
+  \u5F00\u8DD1\u9884\u68C0\u6E05\u5355: "Preflight checklist",
+  \u9884\u68C0\u7ED3\u679C: "Preflight result",
+  "\u5F00\u8DD1\u524D\u5148\u9884\u68C0\uFF1A\u786E\u8BA4\u9A8C\u8BC1\u547D\u4EE4\u3001Git\u3001\u5DE5\u4F5C\u533A\u3001\u9648\u65E7\u95E8\u7981\u4E0E\u4E2D\u65AD\u65AD\u70B9\u90FD\u5DF2\u5C31\u7EEA\uFF0C\u907F\u514D\u5F00\u8DD1\u540E\u624D\u53D1\u73B0\u73AF\u5883\u95EE\u9898\u3002": "Run preflight first: confirm validation commands, git, the working tree, a stale gate and an interrupted checkpoint are ready, so you do not discover an environment problem mid-run.",
+  \u590D\u5236\u9884\u68C0\u6307\u4EE4: "Copy preflight instruction",
+  \u9A8C\u8BC1\u547D\u4EE4: "Validation commands",
+  "\u5DF2\u914D\u7F6E {a0} \u6761\u9A8C\u8BC1\u547D\u4EE4": "{a0} validation command(s) configured",
+  "\u672A\u914D\u7F6E validation.commands \u2014\u2014 \u672C\u8F6E\u65E0\u6CD5\u8BC1\u660E\u4FEE\u590D\uFF0C\u5C5E\u963B\u65AD\u9879": "validation.commands is not configured \u2014 the run cannot prove fixes (blocking)",
+  "Git \u4ED3\u5E93": "Git repository",
+  "\u5DF2\u68C0\u6D4B\u5230 Git \u4ED3\u5E93": "Git repository detected",
+  "\u4E0D\u662F Git \u4ED3\u5E93 \u2014\u2014 changed-only \u8303\u56F4\u4E0E iterate_diff \u9700\u8981\u5B83": "Not a git repository \u2014 changed-only scope and iterate_diff need one",
+  \u5DE5\u4F5C\u533A: "Working tree",
+  "\u672A\u63D0\u4EA4\u6539\u52A8\uFF1A\u672A\u77E5": "Uncommitted changes: unknown",
+  "{a0} \u4E2A\u672A\u63D0\u4EA4/\u672A\u8DDF\u8E2A\u6587\u4EF6 \u2014\u2014 \u5EFA\u8BAE\u5148 commit \u6216 stash": "{a0} uncommitted/untracked file(s) \u2014 commit or stash first",
+  \u5DE5\u4F5C\u533A\u5E72\u51C0: "Working tree clean",
+  \u9648\u65E7\u95E8\u7981: "Stale gate",
+  "\u78C1\u76D8\u4E0A\u6B8B\u7559 FAIL \u8D28\u91CF\u95E8\u7981 \u2014\u2014 \u5F00\u65B0\u8F6E\u524D\u5148\u6E05\u9664": "A stale FAIL quality gate is persisted \u2014 clear it before a fresh run",
+  "\u8D28\u91CF\u95E8\u7981\uFF1A{a0}": "Quality gate: {a0}",
+  \u65E0\u6301\u4E45\u5316\u8D28\u91CF\u95E8\u7981: "No persisted quality gate",
+  \u4E2D\u65AD\u65AD\u70B9: "Interrupted checkpoint",
+  "\u5B58\u5728\u4E2D\u65AD\u65AD\u70B9\uFF08\u5DF2\u6062\u590D {a0} \u6B21\uFF09\u2014\u2014 \u6062\u590D\u6216\u6E05\u9664\u540E\u518D\u5F00\u8DD1": "An interrupted checkpoint is waiting (resumed {a0}x) \u2014 resume or clear it first",
+  \u65E0\u4E2D\u65AD\u65AD\u70B9: "No interrupted checkpoint",
+  \u914D\u7F6E\u9A8C\u8BC1\u547D\u4EE4: "Configure validation",
+  \u6062\u590D\u65AD\u70B9: "Resume checkpoint",
+  "\u963B\u65AD {a0} \xB7 \u8B66\u544A {a1}": "Blocking {a0} \xB7 warnings {a1}",
+  "\u9884\u68C0\u5931\u8D25\uFF1A{a0}": "Preflight failed: {a0}",
+  "\u9884\u68C0\u53EA\u8BFB\uFF0C\u4E0D\u4F1A\u4FEE\u6539\u914D\u7F6E\u6216\u6587\u4EF6\u3002": "Preflight is read-only; it never modifies config or files.",
   // ── copy feedback ────────────────────────────────────────────────────────
   \u5DF2\u590D\u5236: "Copied",
   \u590D\u5236\u5931\u8D25: "Copy failed"
@@ -2907,6 +3024,7 @@ var ITERATE_CSS = `
 .iterate-gate[data-status="pass"] { color: var(--dsw-alias-state-success-primary); background: color-mix(in srgb, var(--dsw-alias-state-success-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-state-success-primary) 28%, transparent); }
 .iterate-gate[data-status="fail"] { color: var(--dsw-alias-state-error-primary); background: color-mix(in srgb, var(--dsw-alias-state-error-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-state-error-primary) 28%, transparent); }
 .iterate-gate[data-status="pending"] { color: var(--dsw-alias-label-secondary); background: color-mix(in srgb, var(--dsw-alias-label-secondary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-label-secondary) 28%, transparent); }
+.iterate-gate[data-status="warn"] { color: var(--dsw-alias-state-warn-primary); background: color-mix(in srgb, var(--dsw-alias-state-warn-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-state-warn-primary) 28%, transparent); }
 
 /* v3.0: Experience bank hit highlight */
 .iterate-exp-hit { display: inline-flex; align-items: center; gap: 6px; padding: 2px 8px; border-radius: 6px; background: color-mix(in srgb, var(--dsw-alias-state-success-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-state-success-primary) 28%, transparent); font-size: 11px; color: var(--dsw-alias-state-success-primary); }
@@ -4343,7 +4461,9 @@ var OBS_TABS = [
   // v3.0: Quality Command Center tabs
   { key: "f8", label: { zh: "\u8D28\u91CF\u95E8\u7981", en: "Quality gate" }, hotkey: "8" },
   { key: "f9", label: { zh: "\u7ECF\u9A8C\u94F6\u884C", en: "Experience bank" }, hotkey: "9" },
-  { key: "f10", label: { zh: "\u9632\u5FA1\u4E8B\u4EF6", en: "Defense events" }, hotkey: "0" }
+  { key: "f10", label: { zh: "\u9632\u5FA1\u4E8B\u4EF6", en: "Defense events" }, hotkey: "0" },
+  // v3.12: pre-run readiness checklist (validation/git/dirty-tree/stale-gate/checkpoint)
+  { key: "f11", label: { zh: "\u5F00\u8DD1\u9884\u68C0", en: "Preflight" }, hotkey: "" }
 ];
 var OBS_HOTKEY_TABS = {
   1: "f1",
@@ -4414,6 +4534,10 @@ function latestDefenseEvents(session) {
   if (!session) return null;
   return scanSessionForDefenseEvents(session);
 }
+function latestPreflight(session) {
+  if (!session) return null;
+  return scanSessionForPreflight(session);
+}
 function buildObsFixInstruction(f) {
   return buildFixInstruction(f);
 }
@@ -4426,6 +4550,7 @@ function ObservatoryPanel(props) {
   const qualityGate = latestQualityGate(session);
   const experienceBank = latestExperienceBank(session);
   const defenseEvents = latestDefenseEvents(session);
+  const preflight = latestPreflight(session);
   const [open, setOpen] = React.useState(false);
   const [tab, setTab] = React.useState("live");
   const [expandedThreads, setExpandedThreads] = React.useState(/* @__PURE__ */ new Set());
@@ -5577,6 +5702,195 @@ function ObservatoryPanel(props) {
       eventRows.length > 0 ? React.createElement("div", {}, ...eventRows) : React.createElement("div", { className: "iterate-obs-empty" }, t("\u6CA1\u6709\u5339\u914D\u8BE5\u7C7B\u578B\u7684\u9632\u5FA1\u4E8B\u4EF6"))
     );
   };
+  const renderPreflight = () => {
+    const preflightInstruction = buildPreflightInstruction();
+    const report = preflight;
+    const hasReport = report !== null && Array.isArray(report.checks);
+    const ready = report !== null && report.ready === true;
+    const blocking = Number(report && report.blocking != null ? report.blocking : 0);
+    const warnings = Number(report && report.warnings != null ? report.warnings : 0);
+    const statusLabel = !hasReport ? t("\u5F85\u9884\u68C0") : ready ? t("\u5C31\u7EEA") : t("\u672A\u5C31\u7EEA");
+    const statusTone = !hasReport ? "pending" : ready ? "pass" : "fail";
+    const headerBar = React.createElement(
+      "div",
+      { className: "iterate-obs-bar", style: { marginBottom: 8 } },
+      React.createElement("b", {}, t("\u5F00\u8DD1\u9884\u68C0")),
+      React.createElement("span", { className: "iterate-gate", "data-status": statusTone }, statusLabel),
+      React.createElement("button", {
+        className: "iterate-btn",
+        "data-primary": "",
+        "data-copied": copiedKey === "preflight" ? "" : void 0,
+        onClick: () => copyInstruction("preflight", preflightInstruction),
+        title: t("\u590D\u5236 iterate_preflight \u9884\u68C0\u6307\u4EE4\uFF08\u542B JSON \u53C2\u6570\uFF09")
+      }, copiedKey === "preflight" ? t("\u5DF2\u590D\u5236") : t("\u8FD0\u884C\u9884\u68C0"))
+    );
+    if (!hasReport) {
+      return React.createElement(
+        "div",
+        {},
+        headerBar,
+        React.createElement(
+          "div",
+          { className: "iterate-obs-block" },
+          React.createElement(
+            "div",
+            { className: "iterate-obs-block-head" },
+            React.createElement("span", {}, t("\u5F00\u8DD1\u9884\u68C0\u6E05\u5355")),
+            React.createElement("span", { className: "iterate-obs-badge" }, "v3.12")
+          ),
+          React.createElement(
+            "div",
+            { className: "iterate-obs-block-body" },
+            React.createElement(
+              "div",
+              { className: "iterate-obs-msg" },
+              // Gap #4: separate "pulled and empty" from "never pulled".
+              diskEmptyStateText(toolCalledInSession(session, "iterate_preflight"), t("\u9884\u68C0\u7ED3\u679C"), getLang())
+            ),
+            React.createElement(
+              "div",
+              { className: "iterate-obs-msg", style: { marginTop: 6 } },
+              t("\u5F00\u8DD1\u524D\u5148\u9884\u68C0\uFF1A\u786E\u8BA4\u9A8C\u8BC1\u547D\u4EE4\u3001Git\u3001\u5DE5\u4F5C\u533A\u3001\u9648\u65E7\u95E8\u7981\u4E0E\u4E2D\u65AD\u65AD\u70B9\u90FD\u5DF2\u5C31\u7EEA\uFF0C\u907F\u514D\u5F00\u8DD1\u540E\u624D\u53D1\u73B0\u73AF\u5883\u95EE\u9898\u3002")
+            ),
+            React.createElement(
+              "div",
+              { className: "iterate-obs-bar", style: { marginTop: 8 } },
+              React.createElement("button", {
+                className: "iterate-btn",
+                "data-copied": copiedKey === "preflight-instr" ? "" : void 0,
+                onClick: () => copyInstruction("preflight-instr", preflightInstruction),
+                title: t("\u590D\u5236\u9884\u68C0\u6307\u4EE4")
+              }, copiedKey === "preflight-instr" ? t("\u5DF2\u590D\u5236") : t("\u590D\u5236\u9884\u68C0\u6307\u4EE4"))
+            )
+          )
+        )
+      );
+    }
+    if (report && report.ok === false) {
+      return React.createElement(
+        "div",
+        {},
+        headerBar,
+        React.createElement(
+          "div",
+          { className: "iterate-obs-block" },
+          React.createElement(
+            "div",
+            { className: "iterate-obs-block-head" },
+            React.createElement("span", {}, t("\u5F00\u8DD1\u9884\u68C0\u6E05\u5355")),
+            React.createElement("span", { className: "iterate-obs-badge" }, "v3.12")
+          ),
+          React.createElement(
+            "div",
+            { className: "iterate-obs-block-body" },
+            React.createElement(
+              "div",
+              { className: "iterate-obs-msg" },
+              tf("\u9884\u68C0\u5931\u8D25\uFF1A{a0}", { a0: String(report.error || "") })
+            )
+          )
+        )
+      );
+    }
+    const CHECK_META = {
+      validation: {
+        label: t("\u9A8C\u8BC1\u547D\u4EE4"),
+        detail: (d) => {
+          const n = Number(d.commandCount ?? 0);
+          return n > 0 ? tf("\u5DF2\u914D\u7F6E {a0} \u6761\u9A8C\u8BC1\u547D\u4EE4", { a0: n }) : t("\u672A\u914D\u7F6E validation.commands \u2014\u2014 \u672C\u8F6E\u65E0\u6CD5\u8BC1\u660E\u4FEE\u590D\uFF0C\u5C5E\u963B\u65AD\u9879");
+        }
+      },
+      git: {
+        label: t("Git \u4ED3\u5E93"),
+        detail: (d) => d.isRepo === true ? t("\u5DF2\u68C0\u6D4B\u5230 Git \u4ED3\u5E93") : t("\u4E0D\u662F Git \u4ED3\u5E93 \u2014\u2014 changed-only \u8303\u56F4\u4E0E iterate_diff \u9700\u8981\u5B83")
+      },
+      "dirty-tree": {
+        label: t("\u5DE5\u4F5C\u533A"),
+        detail: (d) => {
+          const n = d.changedFiles;
+          if (n === null || n === void 0) return t("\u672A\u63D0\u4EA4\u6539\u52A8\uFF1A\u672A\u77E5");
+          const num = Number(n);
+          return num > 0 ? tf("{a0} \u4E2A\u672A\u63D0\u4EA4/\u672A\u8DDF\u8E2A\u6587\u4EF6 \u2014\u2014 \u5EFA\u8BAE\u5148 commit \u6216 stash", { a0: num }) : t("\u5DE5\u4F5C\u533A\u5E72\u51C0");
+        }
+      },
+      "stale-gate": {
+        label: t("\u9648\u65E7\u95E8\u7981"),
+        detail: (d) => {
+          const s = d.overallStatus;
+          if (s === "fail") return t("\u78C1\u76D8\u4E0A\u6B8B\u7559 FAIL \u8D28\u91CF\u95E8\u7981 \u2014\u2014 \u5F00\u65B0\u8F6E\u524D\u5148\u6E05\u9664");
+          return s ? tf("\u8D28\u91CF\u95E8\u7981\uFF1A{a0}", { a0: String(s) }) : t("\u65E0\u6301\u4E45\u5316\u8D28\u91CF\u95E8\u7981");
+        }
+      },
+      "interrupted-checkpoint": {
+        label: t("\u4E2D\u65AD\u65AD\u70B9"),
+        detail: (d) => {
+          if (d.interrupted === true) {
+            const rc = Number(d.resumeCount ?? 0);
+            return tf("\u5B58\u5728\u4E2D\u65AD\u65AD\u70B9\uFF08\u5DF2\u6062\u590D {a0} \u6B21\uFF09\u2014\u2014 \u6062\u590D\u6216\u6E05\u9664\u540E\u518D\u5F00\u8DD1", { a0: rc });
+          }
+          return t("\u65E0\u4E2D\u65AD\u65AD\u70B9");
+        }
+      }
+    };
+    const fixFor = (id) => {
+      switch (id) {
+        case "validation":
+          return { key: "preflight-fix-validation", label: t("\u914D\u7F6E\u9A8C\u8BC1\u547D\u4EE4"), instruction: buildConfigFieldInstruction("validation.commands") };
+        case "stale-gate":
+          return { key: "preflight-fix-gate", label: t("\u6E05\u9664\u95E8\u7981"), instruction: buildQualityGateClearInstruction() };
+        case "interrupted-checkpoint":
+          return { key: "preflight-fix-checkpoint", label: t("\u6062\u590D\u65AD\u70B9"), instruction: buildCheckpointResumeInstruction() };
+        default:
+          return null;
+      }
+    };
+    const rows = (report.checks || []).map((c, i) => {
+      const id = String(c.id || "");
+      const status = String(c.status || "warn");
+      const meta = CHECK_META[id];
+      const label = meta ? meta.label : id || "?";
+      const detail = meta ? meta.detail(c.detail || {}) : "";
+      const fix = status !== "pass" ? fixFor(id) : null;
+      return React.createElement(
+        "div",
+        { key: `pf-${i}`, className: "iterate-obs-row" },
+        React.createElement("span", { className: "iterate-gate", "data-status": status }, status.toUpperCase()),
+        React.createElement("b", {}, label),
+        React.createElement("span", { className: "iterate-obs-msg" }, detail),
+        fix ? React.createElement("button", {
+          className: "iterate-btn",
+          "data-copied": copiedKey === fix.key ? "" : void 0,
+          onClick: () => copyInstruction(fix.key, fix.instruction),
+          title: fix.instruction
+        }, copiedKey === fix.key ? t("\u5DF2\u590D\u5236") : fix.label) : null
+      );
+    });
+    return React.createElement(
+      "div",
+      {},
+      headerBar,
+      React.createElement(
+        "div",
+        { className: "iterate-obs-block" },
+        React.createElement(
+          "div",
+          { className: "iterate-obs-block-head" },
+          React.createElement("span", {}, t("\u5F00\u8DD1\u9884\u68C0\u6E05\u5355")),
+          React.createElement(
+            "span",
+            { className: "iterate-obs-head-meta" },
+            tf("\u963B\u65AD {a0} \xB7 \u8B66\u544A {a1}", { a0: blocking, a1: warnings })
+          )
+        ),
+        React.createElement(
+          "div",
+          { className: "iterate-obs-block-body" },
+          React.createElement("div", { className: "iterate-obs-msg" }, t("\u9884\u68C0\u53EA\u8BFB\uFF0C\u4E0D\u4F1A\u4FEE\u6539\u914D\u7F6E\u6216\u6587\u4EF6\u3002")),
+          ...rows
+        )
+      )
+    );
+  };
   const renderLive = () => {
     const liveEntries = manifest.live || [];
     if (liveEntries.length === 0) {
@@ -5673,6 +5987,8 @@ function ObservatoryPanel(props) {
         return renderExperienceBank();
       case "f10":
         return renderDefenseEvents();
+      case "f11":
+        return renderPreflight();
       default:
         return null;
     }

package/lib/parse.js

@@ -1124,6 +1124,88 @@ export function scanSessionForDefenseEvents(session) {
   return loose ? normalizeDefenseEventsResult(loose) : null
 }
 
+// ─── Preflight readiness report detection ────────────────────────────────────
+
+/**
+ * Check whether `obj` is an `iterate_preflight` report.
+ *
+ * Discriminator: a boolean `ready`, an array `checks`, and a numeric
+ * `blocking`/`warnings` counter. The `ok:false` error shape (empty checks)
+ * still matches so the panel can render the failure instead of claiming
+ * "not pulled yet".
+ *
+ * @param {unknown} obj
+ * @returns {boolean}
+ */
+export function isPreflightReport(obj) {
+  if (!obj || typeof obj !== 'object') return false
+  const o = /** @type {Record<string, unknown>} */ (obj)
+  const ready = safeGet(o, 'ready')
+  const checks = safeGet(o, 'checks')
+  const blocking = safeGet(o, 'blocking')
+  const warnings = safeGet(o, 'warnings')
+  return (
+    typeof ready === 'boolean' &&
+    Array.isArray(checks) &&
+    (typeof blocking === 'number' || typeof warnings === 'number')
+  )
+}
+
+/** Deep-find the first `iterate_preflight` report node inside `obj`. */
+function findPreflightReportInObject(obj) {
+  return findFirstInObject(obj, (o) => isPreflightReport(o))
+}
+
+/**
+ * Normalize an `iterate_preflight` report into a JSON-safe object.
+ *
+ * @param {Record<string, unknown> | null | undefined} raw
+ * @returns {Record<string, unknown>}
+ */
+export function normalizePreflightReport(raw) {
+  const src = raw && typeof raw === 'object'
+    ? /** @type {Record<string, unknown>} */ (raw)
+    : {}
+  const asNum = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
+  const asStr = (v) => (typeof v === 'string' ? v : '')
+  const checks = Array.isArray(safeGet(src, 'checks')) ? safeGet(src, 'checks') : []
+  return {
+    ok: safeGet(src, 'ok') !== false,
+    ready: safeGet(src, 'ready') === true,
+    blocking: asNum(safeGet(src, 'blocking')),
+    warnings: asNum(safeGet(src, 'warnings')),
+    error: asStr(safeGet(src, 'error')) || null,
+    checks: (/** @type {unknown[]} */ (checks)).map((c) => {
+      const rec = /** @type {Record<string, unknown>} */ (c && typeof c === 'object' ? c : {})
+      const status = safeGet(rec, 'status')
+      const detail = safeGet(rec, 'detail')
+      return {
+        id: asStr(safeGet(rec, 'id')),
+        status: status === 'pass' || status === 'warn' || status === 'fail' ? status : 'warn',
+        detail: detail && typeof detail === 'object' ? detail : {},
+      }
+    }),
+  }
+}
+
+/**
+ * Scan a session snapshot for the latest `iterate_preflight` result and return
+ * its normalized report (or null).
+ *
+ * @param {unknown} session
+ * @returns {Record<string, unknown> | null}
+ */
+export function scanSessionForPreflight(session) {
+  const node = latestToolResultNode(session, 'iterate_preflight', findPreflightReportInObject)
+  if (node !== null) {
+    const found = findPreflightReportInObject(node)
+    if (found) return normalizePreflightReport(found)
+  }
+  // Same deep-scan fallback as the quality-gate scanner (see above).
+  const loose = findFirstInObject(session, isPreflightReport)
+  return loose ? normalizePreflightReport(loose) : null
+}
+
 // ─── Run-summary / meta-review verdict detection ─────────────────────────────
 
 /**
@@ -1857,6 +1939,21 @@ export function buildQualityGateClearInstruction() {
   )
 }
 
+/**
+ * `iterate_preflight` readiness-check payload (runs the pre-run checklist).
+ *
+ * @returns {string}
+ */
+export function buildPreflightInstruction() {
+  return (
+    '请调用 `iterate_preflight` 运行开跑前预检（只读：校验 validation.commands、git、脏工作区、' +
+    '陈旧质量门禁与中断断点）：\n\n' +
+    '```json\n' +
+    `${JSON.stringify({}, null, 2)}\n` +
+    '```'
+  )
+}
+
 /**
  * `iterate_rollback` payload for one applied fix id.
  *
@@ -2310,14 +2407,63 @@ export function buildCompletionSummary(report, lang = 'zh') {
   const stats = severityStats(report)
   const converged = conv.converged === true
   const totalFindings = stats.critical + stats.high + stats.medium + stats.low
+  // The persisted `stoppedReason` is the authoritative "why" — a validation
+  // abort or a schema failure must NOT be reported as "reached the round
+  // limit". A normalized report nests it under `convergence.stoppedReason`
+  // (normalizeReport); a raw harness report may carry it at the top level.
+  // Fall back to the convergence flag only when no reason was stored (older
+  // transcripts predate the field).
+  const stopped = typeof conv.stoppedReason === 'string'
+    ? conv.stoppedReason
+    : typeof report.stoppedReason === 'string'
+      ? report.stoppedReason
+      : ''
+  const reason = stopped
+    ? completionReason(stopped, lang, total)
+    : converged
+      ? (lang === 'en' ? 'converged' : '已收敛')
+      : (lang === 'en' ? `reached the round limit ${total}` : `已达最大轮数 ${total}`)
   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}`
 }
 
+/**
+ * Compact "why the run ended" phrase for the completion summary.
+ * Mirrors `stoppedReasonLabel` but drops the "已结束 · " prefix so it reads
+ * inside the one-line summary. Unknown reasons degrade to the raw value.
+ *
+ * @param {string} reason
+ * @param {string} lang
+ * @param {number} total
+ * @returns {string}
+ */
+function completionReason(reason, lang, total) {
+  const zh = {
+    converged: '已收敛',
+    max_rounds_reached: `已达最大轮数 ${total}`,
+    aborted_by_validation: '验证失败后回滚',
+    aborted_by_config: '验证命令未在白名单',
+    inconclusive: '轮次结论不明',
+    schema_invalid: '审查输出 schema 校验失败',
+    no_usable_reviewer_output: '无可用审查输出',
+  }
+  const en = {
+    converged: 'converged',
+    max_rounds_reached: `reached the round limit ${total}`,
+    aborted_by_validation: 'rolled back after a validation failure',
+    aborted_by_config: 'validation command not allow-listed',
+    inconclusive: 'inconclusive rounds',
+    schema_invalid: 'review output failed schema validation',
+    no_usable_reviewer_output: 'no usable review output',
+  }
+  const table = lang === 'en' ? en : zh
+  // Object.hasOwn, NOT `table[reason]`: a hand-edited `__proto__` reason must
+  // not resolve through the prototype chain to a non-string.
+  return Object.hasOwn(table, reason) ? table[reason] : reason
+}
+
 // ─── Config edit guidance ───────────────────────────────────────────────────
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "3.11.0",
+  "version": "3.12.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",

package/src/client/i18n.ts

@@ -446,11 +446,50 @@ export const EN: Record<string, string> = {
   '防线：{a0}': 'Defense: {a0}',
   没有匹配该类型的防御事件: 'No defense events of this type',
 
+  // ── F11 preflight ────────────────────────────────────────────────────────
+  开跑预检: 'Preflight',
+  待预检: 'Not run yet',
+  未就绪: 'Not ready',
+  '复制 iterate_preflight 预检指令（含 JSON 参数）':
+    'Copy the iterate_preflight readiness instruction (JSON arguments included)',
+  运行预检: 'Run preflight',
+  开跑预检清单: 'Preflight checklist',
+  预检结果: 'Preflight result',
+  '开跑前先预检：确认验证命令、Git、工作区、陈旧门禁与中断断点都已就绪，避免开跑后才发现环境问题。':
+    'Run preflight first: confirm validation commands, git, the working tree, a stale gate and an interrupted checkpoint are ready, so you do not discover an environment problem mid-run.',
+  复制预检指令: 'Copy preflight instruction',
+  验证命令: 'Validation commands',
+  '已配置 {a0} 条验证命令': '{a0} validation command(s) configured',
+  '未配置 validation.commands —— 本轮无法证明修复，属阻断项':
+    'validation.commands is not configured — the run cannot prove fixes (blocking)',
+  'Git 仓库': 'Git repository',
+  '已检测到 Git 仓库': 'Git repository detected',
+  '不是 Git 仓库 —— changed-only 范围与 iterate_diff 需要它':
+    'Not a git repository — changed-only scope and iterate_diff need one',
+  工作区: 'Working tree',
+  '未提交改动：未知': 'Uncommitted changes: unknown',
+  '{a0} 个未提交/未跟踪文件 —— 建议先 commit 或 stash':
+    '{a0} uncommitted/untracked file(s) — commit or stash first',
+  工作区干净: 'Working tree clean',
+  陈旧门禁: 'Stale gate',
+  '磁盘上残留 FAIL 质量门禁 —— 开新轮前先清除':
+    'A stale FAIL quality gate is persisted — clear it before a fresh run',
+  '质量门禁：{a0}': 'Quality gate: {a0}',
+  无持久化质量门禁: 'No persisted quality gate',
+  中断断点: 'Interrupted checkpoint',
+  '存在中断断点（已恢复 {a0} 次）—— 恢复或清除后再开跑':
+    'An interrupted checkpoint is waiting (resumed {a0}x) — resume or clear it first',
+  无中断断点: 'No interrupted checkpoint',
+  配置验证命令: 'Configure validation',
+  恢复断点: 'Resume checkpoint',
+  '阻断 {a0} · 警告 {a1}': 'Blocking {a0} · warnings {a1}',
+  '预检失败：{a0}': 'Preflight failed: {a0}',
+  '预检只读，不会修改配置或文件。': 'Preflight is read-only; it never modifies config or files.',
+
   // ── copy feedback ────────────────────────────────────────────────────────
   已复制: 'Copied',
   复制失败: 'Copy failed',
 }
-
 let current: Lang = 'zh'
 let storage: LangStorage | null = null
 const listeners = new Set<(lang: Lang) => void>()