iterate-plugin 2.8.4 → 2.9.0

package/lib/parse.js

@@ -28,6 +28,124 @@ export const SEVERITY_COLOR = {
   low: '#6b7280',
 }
 
+// ─── Interruption / resume + image attachment detection ──────────────────────
+
+/**
+ * Deep-scan an object tree for a decision-log `resume` marker.
+ * The normal-mode workflow appends a `resume` decision-log entry when it
+ * continues a previous interrupted run:
+ *   { type: "resume", data: { resumedFromRound, resumeCount } }
+ * This is the durable client-side signal that a run was interrupted and
+ * recovered. Returns the highest `resumeCount` observed, or 0 when none.
+ *
+ * @param {unknown} obj
+ * @param {Set<unknown>} [seen]
+ * @param {number} [maxDepth=20]
+ * @returns {number}
+ */
+export function scanSessionForResume(obj, seen, maxDepth = 20) {
+  if (maxDepth <= 0) return 0
+  if (!obj || typeof obj !== 'object') return 0
+
+  const s = seen || new Set()
+  if (s.has(obj)) return 0
+  s.add(obj)
+
+  let best = 0
+
+  // Direct marker: { type: "resume", data: { resumeCount } }.
+  const direct = /** @type {Record<string, unknown>} */ (obj)
+  if (direct.type === 'resume') {
+    const data = /** @type {Record<string, unknown>} */ (direct.data || {})
+    if (typeof data.resumeCount === 'number' && data.resumeCount > best) {
+      best = data.resumeCount
+    }
+  }
+  // Nested entry: { entry: { type: "resume", data: { resumeCount } } }.
+  if (direct.entry && typeof direct.entry === 'object') {
+    const entry = /** @type {Record<string, unknown>} */ (direct.entry)
+    if (entry.type === 'resume') {
+      const data = /** @type {Record<string, unknown>} */ (entry.data || {})
+      if (typeof data.resumeCount === 'number' && data.resumeCount > best) {
+        best = data.resumeCount
+      }
+    }
+  }
+
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      const found = scanSessionForResume(item, s, maxDepth - 1)
+      if (found > best) best = found
+    }
+    return best
+  }
+
+  for (const key of Object.keys(direct)) {
+    const val = direct[key]
+    if (val && typeof val === 'object') {
+      const found = scanSessionForResume(val, s, maxDepth - 1)
+      if (found > best) best = found
+    }
+  }
+
+  return best
+}
+
+/**
+ * Count distinct user-attached images inside a session snapshot.
+ * Matches dsh image blocks ({ type: "image", attachment: {...} }) and
+ * raw attachment references ({ mediaType, width, height, bytes }). Dedupes by
+ * `attachmentId` when present so the same image never counts twice.
+ *
+ * @param {unknown} session
+ * @returns {number}
+ */
+export function countSessionImages(session) {
+  if (!session || typeof session !== 'object') return 0
+
+  const ids = new Set()
+  let count = 0
+
+  /** @param {unknown} obj */
+  const walk = (obj, depth) => {
+    if (depth <= 0 || !obj || typeof obj !== 'object') return
+    if (seen.has(obj)) return
+    seen.add(obj)
+    const o = /** @type {Record<string, unknown>} */ (obj)
+
+    // Image block: { type: "image", attachment: { ...ref } }.
+    let ref = null
+    if (o.type === 'image' && o.attachment && typeof o.attachment === 'object') {
+      ref = /** @type {Record<string, unknown>} */ (o.attachment)
+    }
+    // Raw attachment reference shape.
+    if (!ref && typeof o.mediaType === 'string' && String(o.mediaType).startsWith('image/')) {
+      ref = o
+    }
+    if (ref) {
+      const id = typeof ref.attachmentId === 'string' ? ref.attachmentId : null
+      if (id) {
+        if (!ids.has(id)) { ids.add(id); count += 1 }
+      } else {
+        count += 1
+      }
+    }
+
+    if (Array.isArray(obj)) {
+      for (const item of obj) walk(item, depth - 1)
+      return
+    }
+    for (const key of Object.keys(o)) {
+      const val = o[key]
+      if (val && typeof val === 'object') walk(val, depth - 1)
+    }
+  }
+
+  const seen = new Set()
+  walk(session, 12)
+  return count
+}
+
 // ─── ReviewReport detection ──────────────────────────────────────────────────
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "2.8.4",
+  "version": "2.9.0",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus a dry-run pure-review mode with multi-round convergence and a meta-review that audits the report and emits a final review report.",
   "type": "module",
   "license": "MIT",

package/src/client/index.ts

@@ -68,6 +68,8 @@ import {
   keyToVerdict,
   allVerdictKeys,
   buildRuntimeStatusGuide,
+  scanSessionForResume,
+  countSessionImages,
   SEVERITY_LABEL,
   SEVERITY_COLOR,
 } from '../../lib/parse.js'
@@ -320,6 +322,10 @@ const ITERATE_CSS = `
 .iterate-pill { display: inline-flex; align-items: center; gap: 7px; padding: 3px 11px; border-radius: 999px; font-size: 11px; font-weight: 600; white-space: nowrap; 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-pill-dot { width: 6px; height: 6px; border-radius: 50%; background: currentColor; }
 
+/* Interruption / resume + attachment chips (dashboard) */
+.iterate-chip-resume { display: inline-flex; align-items: center; gap: 6px; padding: 3px 10px; border-radius: 999px; font-size: 11px; font-weight: 600; white-space: nowrap; 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); }
+.iterate-chip-images { display: inline-flex; align-items: center; gap: 6px; padding: 3px 10px; border-radius: 999px; font-size: 11px; font-weight: 600; white-space: nowrap; color: var(--dsw-alias-brand-primary); background: color-mix(in srgb, var(--dsw-alias-brand-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-brand-primary) 28%, transparent); }
+
 /* Accessibility-switch toggle */
 .iterate-switch { position: relative; width: 42px; height: 24px; border-radius: 999px; padding: 0; cursor: pointer; background: var(--dsw-alias-bg-layer-2); border: 1px solid var(--dsw-alias-border-l1); transition: background-color 160ms ease, border-color 160ms ease; }
 .iterate-switch:focus-visible { outline: 2px solid var(--dsw-alias-brand-primary); outline-offset: 2px; }
@@ -552,6 +558,25 @@ function ConvergenceDashboard(props: SlotProps) {
   const dims = groupByDimension(report)
   const trend = computeTrendMetrics(report)
 
+  // Interruption / resume awareness: a decision-log `resume` entry in the
+  // session means this run continued from an interrupted checkpoint.
+  const resumeCount = scanSessionForResume(session)
+  const imageCount = countSessionImages(session)
+  const resumeChip = resumeCount > 0
+    ? React.createElement('span', {
+        className: 'iterate-chip-resume',
+        key: 'resume',
+        title: '本次迭代从上一次中断的断点继续执行',
+      }, `已中断恢复 ×${String(resumeCount)}`)
+    : null
+  const imageChip = imageCount > 0
+    ? React.createElement('span', {
+        className: 'iterate-chip-images',
+        key: 'images',
+        title: '会话中检测到用户附带的图片，评审将作为视觉证据参考',
+      }, `附件图片 ${String(imageCount)}`)
+    : null
+
   const dimBadges = Object.keys(dims).slice(0, 6).map((dim) =>
     React.createElement(
       'span',
@@ -598,6 +623,8 @@ function ConvergenceDashboard(props: SlotProps) {
       stats.medium,
     ),
     fixBadge,
+    resumeChip,
+    imageChip,
     React.createElement(TrendChart, { points: trend.points }),
     ...dimBadges,
   )

package/src/skill-prompt.ts

@@ -13,14 +13,14 @@ You have the iterate plugin installed, which registers these tools:
 - \`iterate_config\` — read iterate.config.yaml (dimensions, validation commands, personalization) or write a validated partial update (operation:"write", with automatic backup + rollback)
 - \`iterate_validate\` — run a whitelisted validation command
 - \`iterate_decision_log\` — append to the decision log, or read entries back for review
-- \`iterate_context\` — read SKILL.md / ITERATE.md project context
+- \`iterate_context\` — read SKILL.md / ITERATE.md project context; also relays user-attached image metadata (e.g. UI screenshots, error dialogs) so reviewers can treat them as visual evidence
 - \`iterate_review\` — deterministic review engine: \`plan\` builds the review plan (for \`review.scope: changed-only\`, it resolves the git-diff file set against \`git.target_branch\` and auto-falls back to \`full\` when nothing changed); \`aggregate\` dedupes/merges findings, validates every finding against the findings schema when \`reviewer.output_schema_validation\` is on (dropping invalid entries and reporting them via \`schemaValidation\`), and computes convergence; \`meta-review\` audits a built report for internal consistency (counts, buckets, sorting, convergence math) and returns a final report with an \`approved\` / \`needs_revision\` verdict. Purely computational.
 - \`iterate_triage\` — manage "known_intentional" entries in the config (list / apply, with dedupe + backup + rollback)
 - \`iterate_fix\` — apply ONE atomic fix: backs up the file, enforces the atomic max_lines threshold, writes the new content, and records the fix (id + diff summary) in \`.iterate/fixes/registry.json\`
 - \`iterate_diff\` — show the accumulated diff for a fixed file (vs its original backup) or a per-file summary of all fixes
 - \`iterate_rollback\` — revert a fix by id: restore the file from its backup, remove the fix from the registry, log a \`revert\` entry. Use when a round's validation fails
 - \`iterate_checkpoint\` — save / load / clear an iteration checkpoint (\`.iterate/checkpoint.json\`) so a long run can resume where it left off
-- \`iterate_status\` — summarize the current run: mode, round, fixes applied, architectural remaining, decision-log size, checkpoint presence
+- \`iterate_status\` — summarize the current run: mode, round, fixes applied, architectural remaining, decision-log size, checkpoint presence, and whether the run was interrupted (a checkpoint left on disk means the previous run was interrupted and can be resumed)
 - \`iterate_history\` — inspect the runtime state in detail: decision-log entries and applied fixes (optionally scoped to a round or a fixed file)
 - \`iterate_prune\` — remove stale runtime artifacts (\`.iterate/\` entries). Defaults to a read-only dry-run that reports what WOULD be removed; pass \`dryRun:false\` to actually prune.
 
@@ -31,13 +31,26 @@ When the user asks to review or iterate on the project (e.g. "review this projec
 
 ### Workflow script contract
 Write a plain-JS script (top-level await, ends with \`return <json>\`). Available globals:
-- \`agent(prompt, opts?): Promise<value>\` — spawn a subagent. \`opts.schema\` gives structured output (object-rooted JSON Schema: type/properties/required/additionalProperties/items/enum/const/oneOf only). Resolves \`null\` on child failure. Other opts: \`label\`, \`phase\`.
+- \`agent(prompt, opts?): Promise<value>\` — spawn a subagent. \`opts.schema\` gives structured output (object-rooted JSON Schema: type/properties/required/additionalProperties/items/enum/const/oneOf only). Resolves \`null\` on child failure. Other opts: \`label\`, \`phase\`. Backend selection (optional): pass \`provider\` (e.g. \`"codex"\`, \`"claude"\`, \`"default"\`) to route the sub-agent to a specific provider backend, and/or \`model\` to pin a model id. When omitted, the sub-agent uses the same provider/model as the parent session.
 - \`parallel(thunks): Promise<value[]>\` — run zero-arg async functions concurrently, await all.
 - \`phase(title)\`, \`log(message)\` — progress narration.
 - \`args\` — the args object passed to the workflow tool.
 
 The script CANNOT call tools directly. Subagents are the ones who call tools.
 
+### Sub-agent backend selection
+Every \`agent()\` call may carry a backend hint via \`opts.provider\` / \`opts.model\`. Use it deliberately to balance cost, speed, and reliability:
+- **Reviewers** (many, run in parallel, read-only, benefit from strict JSON): prefer a fast/cheap model when one is configured; otherwise omit the hint and inherit the session backend.
+- **Fixers / aggregators** (few, must be reliable and follow tool results exactly): keep them on the parent's default backend unless a specific provider is known-good.
+- **Never invent a provider/model name.** Pass a hint ONLY when the deployment actually registers that adapter (see \`ih config\` / the configured provider list). When in doubt, omit \`provider\`/\`model\` entirely — the sub-agent then runs on the same backend as the parent session, which is always a safe default.
+- The optional \`args.subagentProvider\` / \`args.subagentModel\` allow the caller to override the whole run's sub-agent backend from the invocation; the canonical scripts below read them and spread the hint onto every spawned sub-agent (reviewers, fixers, validators, aggregators).
+
+### User-attached image evidence
+The user may attach images to the conversation (UI screenshots, error dialogs, design references, logs-as-pictures). When they do:
+- You see those images natively in the session. Capture their metadata and pass it into the workflow via \`args.attachments\` — an array of objects, each with optional \`name\`, \`mediaType\`, \`width\`, \`height\`, and a \`note\` describing what the image shows and why it matters for this review.
+- The canonical scripts below read \`args.attachments\` and relay them into every reviewer prompt so reviewers treat the attached visuals as evidence (e.g. "the screenshot in this message shows the broken layout the review should reproduce").
+- If a reviewer needs the images relayed explicitly, it can call \`iterate_context\` with \`attachments\` to get the normalized image descriptions in its context. Never fabricate an attachment — only relay images the user actually attached.
+
 ### Dry-run mode workflow (pure review — the ONLY mode that never touches files)
 This is iterate's read-only health-check: repeated review rounds until findings converge,
 then produce an auditable report, then audit the report itself (meta-review) and give a
@@ -47,9 +60,15 @@ Canonical script — reproduce this structure exactly (adjust dims via the plan)
 
 \`\`\`js
 phase('plan')
+// Optional per-run backend override for sub-agents (omit to inherit the session backend).
+const subAgentProvider = (args && args.subagentProvider) || undefined
+const subAgentModel = (args && args.subagentModel) || undefined
+const backend = Object.assign({}, subAgentProvider ? { provider: subAgentProvider } : {}, subAgentModel ? { model: subAgentModel } : {})
+// User-attached image evidence relayed into reviewer prompts (metadata only).
+const attachments = (args && Array.isArray(args.attachments)) ? args.attachments : []
 const planRes = await agent(
   'Call iterate_review({operation:"plan", mode:"dry-run"}) and return the plan JSON.',
-  { label: 'review:plan' }
+  Object.assign({ label: 'review:plan' }, backend)
 )
 const plan = (planRes && planRes.plan) ? planRes.plan : null
 if (!plan || !Array.isArray(plan.dimensions)) throw new Error('plan failed: iterate_review did not return a valid plan')
@@ -71,16 +90,18 @@ for (let r = 1; r <= maxRounds; r++) {
       ? '\\nSTRICT JSON REQUIRED: your previous output failed schema validation. Return ONLY a JSON object {"findings":[...]} where EVERY finding has dimension, file, line (non-negative integer; 0 = whole-file), severity (critical|high|medium|low), summary, failure_scenario, suggested_fix, is_atomic (boolean).'
       : ''
     const raw = await parallel(dims.map(dim => () => agent(
-      'Review dimension "' + dim + '". Already-known findings (do NOT re-report): ' +
+      'Review dimension "' + dim + '".' +
+      (attachments.length > 0 ? ' User-attached images are part of the evidence (reproduce/verify against them): ' + JSON.stringify(attachments) + '.' : '') +
+      ' Already-known findings (do NOT re-report): ' +
       JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.',
-      { label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }
+      Object.assign({ label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }, backend)
     )))
     const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
     if (rounds.length >= r) rounds[r - 1] = thisRound; else rounds.push(thisRound)
     // Deterministic aggregate: cross-round dedupe + known_intentional filter + severity sort.
     agg = await agent(
       'Call iterate_review({operation:"aggregate", mode:"dry-run", rounds:' + JSON.stringify(rounds) + ', maxReviewRounds:' + maxRounds + ', knownIntentional:' + JSON.stringify(knownIntentional) + '}) and return the report JSON.',
-      { label: 'review:aggregate:r' + r }
+      Object.assign({ label: 'review:aggregate:r' + r }, backend)
     )
     // reviewer.output_schema_validation (default on): aggregate returns per-round
     // schemaValidation; retry the just-finished round (≤2 times) when invalid.
@@ -104,20 +125,20 @@ for (let r = 1; r <= maxRounds; r++) {
 phase('report')
 const finalAgg = await agent(
   'Call iterate_review({operation:"aggregate", mode:"dry-run", rounds:' + JSON.stringify(rounds) + ', maxReviewRounds:' + maxRounds + ', knownIntentional:' + JSON.stringify(knownIntentional) + '}) and return the report JSON.',
-  { label: 'review:aggregate:final' }
+  Object.assign({ label: 'review:aggregate:final' }, backend)
 )
 const report = (finalAgg && finalAgg.report) ? finalAgg.report : null
 if (!report || !report.convergence) throw new Error('aggregate failed: no valid report was produced')
 await agent(
   'Call iterate_decision_log({operation:"append", type:"report", round:' + report.convergence.totalRounds + ', data:{mode:"dry-run", totalFindings:' + report.summary.totalFindings + '}})',
-  { label: 'review:log' }
+  Object.assign({ label: 'review:log' }, backend)
 )
 
 phase('meta-review')
 // Audit the report itself for internal consistency, then produce the final report.
 const metaRes = await agent(
   'Call iterate_review({operation:"meta-review", report:' + JSON.stringify(report) + '}) and return the finalReport JSON.',
-  { label: 'review:meta' }
+  Object.assign({ label: 'review:meta' }, backend)
 )
 const finalReport = metaRes && metaRes.finalReport ? metaRes.finalReport : null
 const metaAudit = finalReport && finalReport.metaReview ? finalReport.metaReview : null
@@ -153,26 +174,42 @@ Set \`args.mode = "normal"\`. Loop: resume → plan → parallel review ×N →
 Canonical script — reproduce this structure exactly (adjust dims via the plan):
 
 \`\`\`js
-// args = { mode: "normal", maxRounds? }
+// args = { mode: "normal", maxRounds?, subagentProvider?, subagentModel?, attachments? }
+// Optional per-run backend override for sub-agents (omit to inherit the session backend).
+const subAgentProvider = (args && args.subagentProvider) || undefined
+const subAgentModel = (args && args.subagentModel) || undefined
+const backend = Object.assign({}, subAgentProvider ? { provider: subAgentProvider } : {}, subAgentModel ? { model: subAgentModel } : {})
+// User-attached image evidence relayed into reviewer prompts (metadata only).
+const attachments = (args && Array.isArray(args.attachments)) ? args.attachments : []
 phase('resume')
 // If a previous run was interrupted, resume from its checkpoint instead of restarting.
 const ckRes = await agent(
   'Call iterate_checkpoint({ operation: "load" }) and return the checkpoint JSON.',
-  { label: 'checkpoint:load' }
+  Object.assign({ label: 'checkpoint:load' }, backend)
 )
 const checkpoint = (ckRes && ckRes.checkpoint) ? ckRes.checkpoint : null
 const startRound = (checkpoint && typeof checkpoint.round === 'number') ? checkpoint.round + 1 : 1
+// Track how many times this checkpoint has already been resumed (interruption recovery).
+const resumeCount = (checkpoint && typeof checkpoint.resumeCount === 'number') ? checkpoint.resumeCount : 0
+if (checkpoint) {
+  // A previous run left a checkpoint — record the recovery so the decision log
+  // shows the resume, then continue where it left off.
+  await agent(
+    'Call iterate_decision_log({operation:"append", type:"resume", round:' + startRound + ', data:{resumedFromRound:' + checkpoint.round + ', resumeCount:' + (resumeCount + 1) + '}})',
+    Object.assign({ label: 'log:resume' }, backend)
+  )
+}
 
 phase('plan')
 const configRes = await agent(
   'Call iterate_config({ validate: true }) and return the config JSON.',
-  { label: 'config:read' }
+  Object.assign({ label: 'config:read' }, backend)
 )
 const cfg = (configRes && configRes.config) ? configRes.config : null
 const atomicMaxLines = (cfg && cfg.atomic && cfg.atomic.max_lines) ? cfg.atomic.max_lines : 20
 const planRes = await agent(
   'Call iterate_review({operation:"plan", mode:"normal", maxReviewRounds:' + (args.maxRounds || 3) + '}) and return the plan JSON.',
-  { label: 'review:plan' }
+  Object.assign({ label: 'review:plan' }, backend)
 )
 const plan = (planRes && planRes.plan) ? planRes.plan : null
 if (!plan || !Array.isArray(plan.dimensions)) throw new Error('plan failed: iterate_review did not return a valid plan')
@@ -199,8 +236,9 @@ for (let r = startRound; r <= maxRounds; r++) {
       : ''
     const raw = await parallel(dims.map(dim => () => agent(
       'Review dimension "' + dim + '" on the CURRENT code state (previous atomic findings are fixed). ' +
+      (attachments.length > 0 ? ' User-attached images are part of the evidence (reproduce/verify against them): ' + JSON.stringify(attachments) + '.' : '') +
       'Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.',
-      { label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }
+      Object.assign({ label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }, backend)
     )))
     const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
     if (rounds.length >= r) rounds[r - 1] = thisRound; else rounds.push(thisRound)
@@ -210,7 +248,7 @@ for (let r = startRound; r <= maxRounds; r++) {
     // show a running "fixes applied" metric for normal mode.
     agg = await agent(
       'Call iterate_review({operation:"aggregate", mode:"normal", rounds:' + JSON.stringify([thisRound]) + ', knownIntentional:' + JSON.stringify(knownIntentional) + ', fixedCount:' + fixedCount + '}) and return the report JSON.',
-      { label: 'review:aggregate:r' + r }
+      Object.assign({ label: 'review:aggregate:r' + r }, backend)
     )
     // reviewer.output_schema_validation (default on): aggregate returns per-round
     // schemaValidation; retry the just-finished round (≤2 times) when invalid.
@@ -240,12 +278,12 @@ for (let r = startRound; r <= maxRounds; r++) {
       'iterate_fix({ file: "' + file + '", content: <full new file content>, finding: <that finding>, round: ' + r + ' }). ' +
       'Apply the findings IN ORDER. After all fixes, call iterate_diff({ file: "' + file + '" }) to verify the accumulated diff. ' +
       'Findings: ' + JSON.stringify(byFile[file]) + '. Return the array of {id, ok, error} per iterate_fix call.',
-      { label: 'fix:' + file, phase: 'fix', schema: {
+      Object.assign({ label: 'fix:' + file, phase: 'fix', schema: {
         type: 'object', additionalProperties: false,
         properties: {
           fixes: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { id: { type: 'string' }, ok: { type: 'boolean' }, error: { type: 'string' } }, required: ['id', 'ok'] } }
         },
-        required: ['fixes'] } }
+        required: ['fixes'] } }, backend)
     )))
     for (const res of fixRes) {
       if (res && Array.isArray(res.fixes)) {
@@ -267,12 +305,12 @@ for (let r = startRound; r <= maxRounds; r++) {
   const valRes = await agent(
     'Read iterate.config.yaml validation.commands, then call iterate_validate({ command: <cmd> }) for EACH configured command ' +
     '(one tool call per command). Return all results as {command, exitCode} entries.',
-    { label: 'validate:r' + r, phase: 'validate', schema: {
+    Object.assign({ label: 'validate:r' + r, phase: 'validate', schema: {
       type: 'object', additionalProperties: false,
       properties: {
         results: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { command: { type: 'string' }, exitCode: { type: 'integer' } }, required: ['command', 'exitCode'] } }
       },
-      required: ['results'] } }
+      required: ['results'] } }, backend)
   )
   failedCommands = (valRes && Array.isArray(valRes.results)) ? valRes.results.filter(v => v.exitCode !== 0).map(v => v.command) : []
   if (failedCommands.length > 0) {
@@ -281,17 +319,17 @@ for (let r = startRound; r <= maxRounds; r++) {
     if (roundFixIds.length > 0) {
       await agent(
         'Call iterate_rollback({ id: <id> }) for EACH of these fix ids (one call per id): ' + JSON.stringify(roundFixIds) + '. Return the array of {id, ok, error}.',
-        { label: 'rollback:r' + r, phase: 'rollback', schema: {
+        Object.assign({ label: 'rollback:r' + r, phase: 'rollback', schema: {
           type: 'object', additionalProperties: false,
           properties: {
             results: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { id: { type: 'string' }, ok: { type: 'boolean' }, error: { type: 'string' } }, required: ['id', 'ok'] } }
           },
-          required: ['results'] } }
+          required: ['results'] } }, backend)
       )
     }
     await agent(
       'Call iterate_decision_log({operation:"append", type:"round_failed", round:' + r + ', data:{failedCommands:' + JSON.stringify(failedCommands) + ', rolledBack:' + roundFixIds.length + '}})',
-      { label: 'log:failed:r' + r }
+      Object.assign({ label: 'log:failed:r' + r }, backend)
     )
     break
   }
@@ -299,13 +337,13 @@ for (let r = startRound; r <= maxRounds; r++) {
   await agent(
     'Call iterate_decision_log({operation:"append", type:"review_result", round:' + r +
     ', data:{atomic:' + atomic.length + ', architectural:' + remaining.length + ', fixedSoFar:' + fixedCount + '}})',
-    { label: 'log:r' + r }
+    Object.assign({ label: 'log:r' + r }, backend)
   )
 
   // Persist progress so an interrupted run can resume from the next round.
   await agent(
-    'Call iterate_checkpoint({ operation: "save", mode: "normal", round:' + r + ', maxRounds:' + maxRounds + ', fixedCount:' + fixedCount + ', architecturalCount:' + architectural.length + ', findings:' + JSON.stringify(architectural) + ' }) and return the checkpoint JSON.',
-    { label: 'checkpoint:save:r' + r }
+    'Call iterate_checkpoint({ operation: "save", mode: "normal", round:' + r + ', maxRounds:' + maxRounds + ', fixedCount:' + fixedCount + ', architecturalCount:' + architectural.length + ', resumeCount:' + resumeCount + ', findings:' + JSON.stringify(architectural) + ' }) and return the checkpoint JSON.',
+    Object.assign({ label: 'checkpoint:save:r' + r }, backend)
   )
 
   if (atomic.length === 0 && remaining.length === 0) {

package/src/tools/checkpoint.ts

@@ -42,6 +42,7 @@ export function validateCheckpoint(input: {
   maxRounds: unknown
   fixedCount: unknown
   architecturalCount: unknown
+  resumeCount?: unknown
 }): string | null {
   if (input.mode !== 'dry-run' && input.mode !== 'normal') {
     return 'mode must be "dry-run" or "normal"'
@@ -58,6 +59,12 @@ export function validateCheckpoint(input: {
   if (typeof input.architecturalCount !== 'number' || !Number.isInteger(input.architecturalCount) || input.architecturalCount < 0) {
     return 'architecturalCount must be a non-negative integer'
   }
+  if (
+    input.resumeCount !== undefined &&
+    (typeof input.resumeCount !== 'number' || !Number.isInteger(input.resumeCount) || input.resumeCount < 0)
+  ) {
+    return 'resumeCount must be a non-negative integer'
+  }
   return null
 }
 
@@ -103,6 +110,10 @@ export function computeStatus(input: {
     findingsCount: checkpoint?.findings.length ?? 0,
     totalDecisionLogEntries: entries.length,
     hasCheckpoint: checkpoint !== null,
+    // A checkpoint left on disk means the previous run was interrupted before
+    // it could clear it — this is the durable "interruption" signal.
+    interrupted: checkpoint !== null,
+    resumeCount: checkpoint?.resumeCount ?? 0,
     checkpoint,
     lastUpdated,
   }
@@ -133,6 +144,7 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
         maxRounds: { type: 'integer', description: 'Required for save: total round cap.' },
         fixedCount: { type: 'integer', description: 'Required for save: number of fixes applied so far.' },
         architecturalCount: { type: 'integer', description: 'Required for save: architectural findings left unfixed.' },
+        resumeCount: { type: 'integer', description: 'Optional for save: how many times this checkpoint has already been resumed after an interruption (default 0).' },
         findings: { type: 'json', description: 'Optional for save: the current deduped findings to resume from.' },
         path: { type: 'string', description: 'Project root directory (default: current working directory).' },
       },
@@ -181,6 +193,7 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
             maxRounds: args.maxRounds,
             fixedCount: args.fixedCount,
             architecturalCount: args.architecturalCount,
+            resumeCount: args.resumeCount,
           })
           if (invalid) return { operation: 'save', ok: false, error: invalid }
           const checkpoint: IterationCheckpoint = {
@@ -189,6 +202,7 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
             maxRounds: args.maxRounds as number,
             fixedCount: args.fixedCount as number,
             architecturalCount: args.architecturalCount as number,
+            resumeCount: (typeof args.resumeCount === 'number' ? args.resumeCount : 0),
             findings: (Array.isArray(args.findings) ? args.findings : []) as unknown as IterationCheckpoint['findings'],
             startedAt: readCheckpoint(projectRoot)?.startedAt ?? new Date().toISOString(),
             updatedAt: new Date().toISOString(),
@@ -239,6 +253,8 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
             findingsCount: { type: 'integer' },
             totalDecisionLogEntries: { type: 'integer' },
             hasCheckpoint: { type: 'boolean' },
+            interrupted: { type: 'boolean', description: 'True when a checkpoint exists, meaning the previous run was interrupted before finishing.' },
+            resumeCount: { type: 'integer', description: 'How many times the current checkpoint has already been resumed.' },
             lastUpdated: { type: 'string' },
             error: { type: 'string' },
           },
@@ -251,7 +267,7 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
             `Fixed: ${value.fixedCount} · Architectural remaining: ${value.architecturalCount}`,
             `Findings in checkpoint: ${value.findingsCount}`,
             `Decision-log entries: ${value.totalDecisionLogEntries}`,
-            `Checkpoint: ${value.hasCheckpoint ? 'yes' : 'no'}`,
+            `Checkpoint: ${value.hasCheckpoint ? 'yes' : 'no'}${value.interrupted ? ' (interrupted — resumable)' : ''}${value.resumeCount ? ` · resumed ${value.resumeCount}x` : ''}`,
             value.lastUpdated ? `Last updated: ${value.lastUpdated}` : '',
           ]
           return [{ type: 'text', text: lines.filter(Boolean).join('\n') }]
@@ -277,6 +293,8 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
           findingsCount: status.findingsCount,
           totalDecisionLogEntries: status.totalDecisionLogEntries,
           hasCheckpoint: status.hasCheckpoint,
+          interrupted: status.interrupted,
+          resumeCount: status.resumeCount,
           lastUpdated: status.lastUpdated ?? undefined,
         }
       },