iterate-plugin 3.11.0 → 3.12.0

package/src/client/index.ts

@@ -75,6 +75,8 @@ import {
   scanSessionForQualityGate,
   scanSessionForExperienceBank,
   scanSessionForDefenseEvents,
+  scanSessionForPreflight,
+  buildPreflightInstruction,
   filterLiveEntries,
   filterTimelineEntries,
   serializeObservatoryExport,
@@ -336,6 +338,24 @@ interface ObsQualityGate {
   dimensions?: ObsQualityGateDimension[]
 }
 
+/** One readiness check from `iterate_preflight` (F11). `detail` is structured
+ *  facts the panel localizes into a sentence. */
+interface ObsPreflightCheck {
+  id?: string
+  status?: string
+  detail?: Record<string, unknown>
+}
+
+/** Latest `iterate_preflight` report scanned out of the session stream. */
+interface ObsPreflight {
+  ok?: boolean
+  ready?: boolean
+  blocking?: number
+  warnings?: number
+  error?: string | null
+  checks?: ObsPreflightCheck[]
+}
+
 interface ObsExperienceEntry {
   id?: string
   timestamp?: string
@@ -583,6 +603,7 @@ const 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); }
@@ -2179,6 +2200,8 @@ const OBS_TABS = [
   { key: 'f8', label: { zh: '质量门禁', en: 'Quality gate' }, hotkey: '8' },
   { key: 'f9', label: { zh: '经验银行', en: 'Experience bank' }, hotkey: '9' },
   { key: 'f10', label: { zh: '防御事件', en: 'Defense events' }, hotkey: '0' },
+  // v3.12: pre-run readiness checklist (validation/git/dirty-tree/stale-gate/checkpoint)
+  { key: 'f11', label: { zh: '开跑预检', en: 'Preflight' }, hotkey: '' },
 ] as const
 
 /** Digit → tab id. `1-9` map to F1–F9, `0` to F10, `-` back to the live feed
@@ -2267,6 +2290,12 @@ function latestDefenseEvents(session: unknown): ObsDefenseResult | null {
   return scanSessionForDefenseEvents(session) as ObsDefenseResult | null
 }
 
+/** Find the latest preflight report inside a session snapshot. */
+function latestPreflight(session: unknown): ObsPreflight | null {
+  if (!session) return null
+  return scanSessionForPreflight(session) as ObsPreflight | null
+}
+
 /** Build a human-pasteable `iterate_fix` instruction for one finding.
  *  Gap #10: delegates to the shared builder so the payload always names the
  *  four required `iterate_fix` params (file / content / finding / round) and
@@ -2295,6 +2324,7 @@ function ObservatoryPanel(props: SlotProps) {
   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')
@@ -3356,6 +3386,176 @@ function ObservatoryPanel(props: SlotProps) {
     )
   }
 
+  // ── F11: Preflight readiness ──────────────────────────────────────────────
+  // v3.12: renders the latest iterate_preflight checklist scanned from the
+  // session stream. Each warn/fail row offers the exact fix instruction
+  // (configure validation, clear a stale gate, resume an interrupted
+  // checkpoint) so the environment is repaired BEFORE a round is spent on it.
+  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('待预检') : ready ? t('就绪') : t('未就绪')
+    const statusTone = !hasReport ? 'pending' : ready ? 'pass' : 'fail'
+    const headerBar = React.createElement('div', { className: 'iterate-obs-bar', style: { marginBottom: 8 } },
+      React.createElement('b', {}, t('开跑预检')),
+      React.createElement('span', { className: 'iterate-gate', 'data-status': statusTone }, statusLabel),
+      React.createElement('button', {
+        className: 'iterate-btn', 'data-primary': '', 'data-copied': copiedKey === 'preflight' ? '' : undefined,
+        onClick: () => copyInstruction('preflight', preflightInstruction),
+        title: t('复制 iterate_preflight 预检指令（含 JSON 参数）'),
+      }, copiedKey === 'preflight' ? t('已复制') : t('运行预检')),
+    )
+
+    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('开跑预检清单')),
+            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('预检结果'), getLang()),
+            ),
+            React.createElement('div', { className: 'iterate-obs-msg', style: { marginTop: 6 } },
+              t('开跑前先预检：确认验证命令、Git、工作区、陈旧门禁与中断断点都已就绪，避免开跑后才发现环境问题。'),
+            ),
+            React.createElement('div', { className: 'iterate-obs-bar', style: { marginTop: 8 } },
+              React.createElement('button', {
+                className: 'iterate-btn', 'data-copied': copiedKey === 'preflight-instr' ? '' : undefined,
+                onClick: () => copyInstruction('preflight-instr', preflightInstruction),
+                title: t('复制预检指令'),
+              }, copiedKey === 'preflight-instr' ? t('已复制') : t('复制预检指令')),
+            ),
+          ),
+        ),
+      )
+    }
+
+    // A tool-level failure (bad path, root refused) carries no usable checks —
+    // surface the error instead of a misleading "ready, 0 blocking" summary.
+    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('开跑预检清单')),
+            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('预检失败：{a0}', { a0: String(report.error || '') }),
+            ),
+          ),
+        ),
+      )
+    }
+
+    // Localized label + detail per check id. Detail is structured facts from
+    // the tool, so the panel — not the tool — owns the wording/language.
+    const CHECK_META: Record<string, { label: string; detail: (d: Record<string, unknown>) => string }> = {
+      validation: {
+        label: t('验证命令'),
+        detail: (d) => {
+          const n = Number(d.commandCount ?? 0)
+          return n > 0
+            ? tf('已配置 {a0} 条验证命令', { a0: n })
+            : t('未配置 validation.commands —— 本轮无法证明修复，属阻断项')
+        },
+      },
+      git: {
+        label: t('Git 仓库'),
+        detail: (d) => (d.isRepo === true ? t('已检测到 Git 仓库') : t('不是 Git 仓库 —— changed-only 范围与 iterate_diff 需要它')),
+      },
+      'dirty-tree': {
+        label: t('工作区'),
+        detail: (d) => {
+          const n = d.changedFiles
+          if (n === null || n === undefined) return t('未提交改动：未知')
+          const num = Number(n)
+          return num > 0
+            ? tf('{a0} 个未提交/未跟踪文件 —— 建议先 commit 或 stash', { a0: num })
+            : t('工作区干净')
+        },
+      },
+      'stale-gate': {
+        label: t('陈旧门禁'),
+        detail: (d) => {
+          const s = d.overallStatus
+          if (s === 'fail') return t('磁盘上残留 FAIL 质量门禁 —— 开新轮前先清除')
+          return s ? tf('质量门禁：{a0}', { a0: String(s) }) : t('无持久化质量门禁')
+        },
+      },
+      'interrupted-checkpoint': {
+        label: t('中断断点'),
+        detail: (d) => {
+          if (d.interrupted === true) {
+            const rc = Number(d.resumeCount ?? 0)
+            return tf('存在中断断点（已恢复 {a0} 次）—— 恢复或清除后再开跑', { a0: rc })
+          }
+          return t('无中断断点')
+        },
+      },
+    }
+
+    // Repair action per check id; null = guidance only (no tool can fix it).
+    const fixFor = (id: string): { key: string; label: string; instruction: string } | null => {
+      switch (id) {
+        case 'validation':
+          return { key: 'preflight-fix-validation', label: t('配置验证命令'), instruction: buildConfigFieldInstruction('validation.commands') }
+        case 'stale-gate':
+          return { key: 'preflight-fix-gate', label: t('清除门禁'), instruction: buildQualityGateClearInstruction() }
+        case 'interrupted-checkpoint':
+          return { key: 'preflight-fix-checkpoint', label: t('恢复断点'), 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 ? '' : undefined,
+              onClick: () => copyInstruction(fix.key, fix.instruction),
+              title: fix.instruction,
+            }, copiedKey === fix.key ? t('已复制') : 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('开跑预检清单')),
+          React.createElement('span', { className: 'iterate-obs-head-meta' },
+            tf('阻断 {a0} · 警告 {a1}', { a0: blocking, a1: warnings }),
+          ),
+        ),
+        React.createElement('div', { className: 'iterate-obs-block-body' },
+          React.createElement('div', { className: 'iterate-obs-msg' }, t('预检只读，不会修改配置或文件。')),
+          ...rows,
+        ),
+      ),
+    )
+  }
+
   // ── Live: real-time secondary-subagent activity stream (newest first) ─────
   const renderLive = () => {
     const liveEntries = manifest.live || []
@@ -3440,6 +3640,7 @@ function ObservatoryPanel(props: SlotProps) {
       case 'f8': return renderQualityGate()
       case 'f9': return renderExperienceBank()
       case 'f10': return renderDefenseEvents()
+      case 'f11': return renderPreflight()
       default: return null
     }
   }

package/src/index.ts

@@ -46,6 +46,7 @@ import { registerExperienceBankTool } from './tools/experience-bank.ts'
 import { registerQualityGateTool } from './tools/quality-gate.ts'
 import { registerDefenseEventsTool } from './tools/defense-events.ts'
 import { registerReportTool } from './tools/report.ts'
+import { registerPreflightTool } from './tools/preflight.ts'
 import { registerSessionHooks } from './session-hooks.ts'
 import { registerLiveCapture } from './live.ts'
 import { installWorkingDirectoryContext } from './working-directory.ts'
@@ -71,11 +72,11 @@ export function apply(ctx: Context): void {
   registerSessionHooks(ctx)
   registerLiveCapture(ctx)
 
-  // 1. Register the 17 tools (14 original + 3 v3.0). Each registration is
-  //    isolated: one failing tool must not take down the other 16, the gate
-  //    above, or the prompt below (a partial plugin that still gates and
-  //    teaches the workflow beats an aborted `apply`). Failures are logged,
-  //    never swallowed silently.
+  // 1. Register the 19 tools (14 original + 3 v3.0 + report + preflight). Each
+  //    registration is isolated: one failing tool must not take down the other
+  //    18, the gate above, or the prompt below (a partial plugin that still
+  //    gates and teaches the workflow beats an aborted `apply`). Failures are
+  //    logged, never swallowed silently.
   const toolRegistrations: Array<[string, () => void]> = [
     ['iterate_config', () => registerConfigTool(ctx)],
     ['iterate_validate', () => registerValidateTool(ctx)],
@@ -97,6 +98,8 @@ export function apply(ctx: Context): void {
     ['iterate_defense_events', () => registerDefenseEventsTool(ctx)],
     // v3.9: PR-ready / CI-ready report export
     ['iterate_report', () => registerReportTool(ctx)],
+    // v3.12: pre-run readiness check (validation/git/stale-gate/interrupted)
+    ['iterate_preflight', () => registerPreflightTool(ctx)],
   ]
   for (const [toolName, register] of toolRegistrations) {
     try {

package/src/tools/preflight.ts

@@ -0,0 +1,289 @@
+/**
+ * src/tools/preflight.ts — `iterate_preflight` tool.
+ *
+ * Answers one question BEFORE a run starts: "is this project ready to iterate
+ * safely, and what must be fixed first?" It reads only local state (config,
+ * git, persisted artifacts, checkpoint) and returns a structured checklist the
+ * observatory renders as a preflight panel (F11).
+ *
+ * Why it exists: the most expensive failure mode is starting a run that cannot
+ * prove anything — an empty `validation.commands` means the loop has no way to
+ * tell a fix from a regression, and a stale FAIL certificate or a leftover
+ * interrupted checkpoint makes the first round lie about its starting state.
+ * Preflight surfaces those conditions before the model spends a round
+ * discovering them mid-flight.
+ *
+ * Read-only: never mutates config, files, or artifacts.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+import { resolveProjectRootForExec, loadEffectiveConfig, flattenCommands } from '../config-loader.ts'
+import { runGit } from '../git-scope.ts'
+import { readQualityGate } from './quality-store.ts'
+import { readCheckpoint, computeStatus } from './checkpoint.ts'
+import { readDecisionEntries } from './decision-log.ts'
+import { readRegistry } from './fix.ts'
+import { resultHeadline } from './present.ts'
+
+/** A single check's outcome. `fail` blocks a clean run; `warn` is advisory. */
+export type PreflightStatus = 'pass' | 'warn' | 'fail'
+
+/** One readiness check. `detail` is structured facts (no prose) so the client
+ *  can localize the message and offer the right fix action. */
+export interface PreflightCheck {
+  /** Stable id the client maps to a localized label + fix action. */
+  id: string
+  status: PreflightStatus
+  detail: Record<string, unknown>
+}
+
+/** The full preflight report. */
+export interface PreflightReport {
+  ok: boolean
+  /** True when no check is `fail` (warnings do not block). */
+  ready: boolean
+  /** Count of `fail` checks. */
+  blocking: number
+  /** Count of `warn` checks. */
+  warnings: number
+  checks: PreflightCheck[]
+  error?: string
+}
+
+/** Facts gathered from disk/git before the pure decision runs. */
+export interface PreflightInput {
+  /** Number of configured validation commands (flattened across modules). */
+  validationCommandCount: number
+  /** Whether the project root is inside a git work tree. */
+  isGitRepo: boolean
+  /** Uncommitted/untracked file count, or null when git could not answer. */
+  changedFiles: number | null
+  /** Persisted quality-gate overall status, or null when none is stored. */
+  gateOverallStatus: 'pass' | 'fail' | 'pending' | null
+  /** True when a leftover checkpoint is genuinely interrupted (nothing newer). */
+  interrupted: boolean
+  /** How many times the leftover checkpoint has already been resumed. */
+  resumeCount: number
+}
+
+/**
+ * Build the readiness checklist from already-gathered facts (pure).
+ *
+ * The five checks and why each exists:
+ *   1. `validation`            — empty command set ⇒ the loop cannot prove a
+ *                                fix; the product is fail-closed here, so this
+ *                                is a BLOCKING `fail`, not a warning.
+ *   2. `git`                   — changed-only scope + `iterate_diff` need a
+ *                                repository; full-scope review still works, so
+ *                                absent is a `warn`.
+ *   3. `dirty-tree`            — a run over uncommitted work mixes the user's
+ *                                WIP with the plugin's fixes; advisory `warn`.
+ *                                Unknown (null) is treated as pass so a git
+ *                                hiccup never fabricates a warning.
+ *   4. `stale-gate`            — a persisted FAIL certificate makes the first
+ *                                round read stale; `warn` + clear before a
+ *                                fresh run.
+ *   5. `interrupted-checkpoint`— a leftover checkpoint from a run that never
+ *                                progressed; `warn` + resume or clear.
+ */
+export function buildPreflightReport(input: PreflightInput): PreflightReport {
+  const checks: PreflightCheck[] = [
+    {
+      id: 'validation',
+      status: input.validationCommandCount > 0 ? 'pass' : 'fail',
+      detail: { commandCount: input.validationCommandCount },
+    },
+    {
+      id: 'git',
+      status: input.isGitRepo ? 'pass' : 'warn',
+      detail: { isRepo: input.isGitRepo },
+    },
+    {
+      id: 'dirty-tree',
+      status: input.changedFiles !== null && input.changedFiles > 0 ? 'warn' : 'pass',
+      detail: { changedFiles: input.changedFiles },
+    },
+    {
+      id: 'stale-gate',
+      status: input.gateOverallStatus === 'fail' ? 'warn' : 'pass',
+      detail: { overallStatus: input.gateOverallStatus },
+    },
+    {
+      id: 'interrupted-checkpoint',
+      status: input.interrupted ? 'warn' : 'pass',
+      detail: { interrupted: input.interrupted, resumeCount: input.resumeCount },
+    },
+  ]
+
+  const blocking = checks.filter((c) => c.status === 'fail').length
+  const warnings = checks.filter((c) => c.status === 'warn').length
+  return { ok: true, ready: blocking === 0, blocking, warnings, checks }
+}
+
+/** Human-readable (English, for the model-facing render) description per check. */
+function describeCheck(id: string, detail: Record<string, unknown>): string {
+  switch (id) {
+    case 'validation': {
+      const n = Number(detail.commandCount ?? 0)
+      return n > 0
+        ? `${n} validation command(s) configured`
+        : 'no validation.commands configured — the run cannot prove fixes (blocking)'
+    }
+    case 'git':
+      return detail.isRepo === true
+        ? 'git repository detected'
+        : 'not a git repository — changed-only scope and iterate_diff need one'
+    case 'dirty-tree': {
+      const n = detail.changedFiles
+      if (n === null || n === undefined) return 'uncommitted changes: unknown'
+      const num = Number(n)
+      return num > 0
+        ? `${num} uncommitted/untracked file(s) — commit or stash before a run`
+        : 'working tree clean'
+    }
+    case 'stale-gate': {
+      const s = detail.overallStatus
+      if (s === 'fail') return 'a stale FAIL quality gate is persisted — clear it before a fresh run'
+      return s ? `quality gate: ${String(s)}` : 'no persisted quality gate'
+    }
+    case 'interrupted-checkpoint': {
+      if (detail.interrupted === true) {
+        const rc = Number(detail.resumeCount ?? 0)
+        return `an interrupted checkpoint is waiting (resumed ${rc}x) — resume or clear it`
+      }
+      return 'no interrupted checkpoint'
+    }
+    default:
+      return ''
+  }
+}
+
+/**
+ * Register the `iterate_preflight` tool.
+ */
+export function registerPreflightTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_preflight',
+      // Pure read of on-disk state + git → safe to join a parallel group.
+      isConcurrencySafe: () => true,
+      presentResult: (_args, result) => {
+        const title = resultHeadline(result)
+        return title ? { card: 'generic', title } : undefined
+      },
+      description:
+        'Read-only readiness check to run BEFORE starting an iterate run. Returns a checklist: whether ' +
+        'validation.commands is configured (an empty set means the loop cannot prove fixes — blocking), ' +
+        'whether the project is a git repository, how many files are uncommitted, whether a stale FAIL ' +
+        'quality gate is persisted, and whether an interrupted checkpoint is waiting. Use it before a fresh ' +
+        'run so you fix the environment first instead of discovering it mid-round.',
+      parameters: {
+        path: { type: 'string', description: 'Project root directory (default: current working directory).' },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean', required: true },
+            ready: { type: 'boolean' },
+            blocking: { type: 'integer' },
+            warnings: { type: 'integer' },
+            checks: { type: 'json', description: 'Per-check outcomes: { id, status: pass|warn|fail, detail }.' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (!value.ok) return [{ type: 'text', text: `preflight failed: ${value.error}` }]
+          const checks = Array.isArray(value.checks) ? value.checks : []
+          const warnings = Number(value.warnings ?? 0)
+          const noun = warnings === 1 ? 'warning' : 'warnings'
+          const head = value.ready
+            ? `Preflight: READY (${Number(value.blocking ?? 0)} blocking, ${warnings} ${noun})`
+            : `Preflight: NOT READY (${Number(value.blocking ?? 0)} blocking, ${warnings} ${noun})`
+          const lines = checks.map((c) => {
+            const check = c as { id?: unknown; status?: unknown; detail?: Record<string, unknown> }
+            const id = String(check.id ?? '?')
+            const status = String(check.status ?? '?').toUpperCase()
+            return `  ${status} ${id} — ${describeCheck(id, check.detail ?? {})}`
+          })
+          return [{ type: 'text', text: [head, ...lines].join('\n') }]
+        },
+      },
+
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
+        if (!resolved.ok) {
+          return { ok: false, ready: false, blocking: 0, warnings: 0, checks: [] as unknown as JsonValue, error: resolved.reason }
+        }
+        const projectRoot = resolved.root
+
+        // 1. validation.commands — the load-bearing check.
+        let validationCommandCount = 0
+        try {
+          const effective = loadEffectiveConfig(projectRoot)
+          validationCommandCount = flattenCommands(effective.config.validation?.commands).length
+        } catch {
+          validationCommandCount = 0
+        }
+
+        // 2/3. git repo + dirty tree (best-effort; any failure degrades to unknown).
+        let isGitRepo = false
+        let changedFiles: number | null = null
+        try {
+          const inside = await runGit(['rev-parse', '--is-inside-work-tree'], projectRoot, { signal: exec.signal })
+          isGitRepo = inside.ok && inside.stdout.trim() === 'true'
+          if (isGitRepo) {
+            const status = await runGit(['status', '--porcelain', '-z'], projectRoot, { signal: exec.signal })
+            if (status.ok) {
+              // `-z` NUL-terminates each entry; a rename emits two NUL-separated
+              // paths for one entry, but counting non-empty tokens is still a
+              // faithful "there is uncommitted work" signal (>=1 when dirty).
+              changedFiles = status.stdout.split('\u0000').filter((s) => s.length > 0).length
+            }
+          }
+        } catch {
+          isGitRepo = false
+          changedFiles = null
+        }
+
+        // 4. stale quality gate.
+        let gateOverallStatus: 'pass' | 'fail' | 'pending' | null = null
+        try {
+          gateOverallStatus = readQualityGate(projectRoot).overallStatus ?? null
+        } catch {
+          gateOverallStatus = null
+        }
+
+        // 5. interrupted checkpoint (reuse the exact status logic so preflight
+        //    and iterate_status can never disagree about "interrupted").
+        let interrupted = false
+        let resumeCount = 0
+        try {
+          const status = computeStatus({
+            checkpoint: readCheckpoint(projectRoot),
+            decisionEntries: readDecisionEntries(projectRoot),
+            fixRegistry: readRegistry(projectRoot),
+          })
+          interrupted = status.interrupted
+          resumeCount = status.resumeCount
+        } catch {
+          interrupted = false
+          resumeCount = 0
+        }
+
+        const report = buildPreflightReport({
+          validationCommandCount,
+          isGitRepo,
+          changedFiles,
+          gateOverallStatus,
+          interrupted,
+          resumeCount,
+        })
+        return { ...report, checks: report.checks as unknown as JsonValue }
+      },
+    }),
+  )
+}