iterate-plugin 3.8.0 → 3.9.1

package/src/session-record.ts

@@ -0,0 +1,355 @@
+/**
+ * src/session-record.ts — dsh session-linked run records (dsh ≥ 0.2.1-rc.1).
+ *
+ * Upstream capability (dsh `0.2.1-rc.1`, released 2026-10-17): the *Session
+ * state-record API*. An experimental plugin may append its own record onto a
+ * session's append-only log with `appendPluginRecord(session, type, data)` and
+ * read it back with `pluginRecordOf(event)` (`@deepseek-ai/dsh-session`). The
+ * record is marked `ignorable`, never enters the model-visible surface, and is
+ * carried along by fork / resume / format migration.
+ *
+ * Why the plugin adopts it:
+ *   The iterate run state has, until now, lived ONLY under `<projectRoot>/.iterate/`.
+ *   That is correct for normal operation but has two blind spots the session
+ *   log closes:
+ *     1. **Loss recovery** — if `.iterate/` is deleted, moved, or the working
+ *        directory changes, the observatory goes blank even though the session
+ *        that produced the run is still open. A compact run record on the
+ *        session log lets `iterate_transcript read` rehydrate the run summary
+ *        instead of returning an empty view.
+ *     2. **Session anchoring** — run provenance is tied to the *session* that
+ *        produced it, not only to whatever directory the process happens to be
+ *        in when someone looks afterwards.
+ *
+ * Design (fail-safe, never a hard dependency):
+ *   - The API is loaded lazily via a dynamic `import()` and used structurally
+ *     (no compile-time coupling to `PluginRecordMap`), so a host whose copy of
+ *     `@deepseek-ai/dsh-session` predates the API simply reports
+ *     `supported: false` instead of failing to load the plugin.
+ *   - Every entry point returns a structured result; nothing throws. Writing a
+ *     record is best-effort — a run must never fail because the session log
+ *     could not accept a bookkeeping record.
+ *   - `normalizeRunRecord` re-validates a restored payload, because a record
+ *     read from a resumed session carries whatever JSON an earlier build wrote.
+ */
+
+/** The `plugin:` record type this plugin owns (grammar-checked by dsh). */
+export const ITERATE_RUN_RECORD_TYPE = 'plugin:iterate/run'
+/** Bump when the record payload shape changes incompatibly. */
+export const ITERATE_RUN_RECORD_VERSION = 1
+
+/** Compact, lossless-JSON summary of one iterate run at a point in time. */
+export interface IterateRunRecord {
+  version: number
+  /** Project root the run belongs to (absolute at write time). */
+  project: string
+  goal: string
+  mode: 'dry-run' | 'normal' | null
+  taskMode: 'code' | 'iterate' | null
+  /** Highest round reached. */
+  round: number
+  maxRounds: number
+  /** False once the run recorded a terminal `stoppedReason`. */
+  active: boolean
+  stoppedReason: string | null
+  /** Per-round NEW-finding counts, newest last (drives the F2 trend on recovery). */
+  convergence: number[]
+  findings: {
+    total: number
+    critical: number
+    high: number
+    medium: number
+    low: number
+  }
+  /** Applied (successful) fixes recorded so far. */
+  fixedCount: number
+  /** Quality-gate verdict snapshotted at write time (`pending` when undecided). */
+  qualityStatus: 'pass' | 'fail' | 'pending' | null
+  /** ISO timestamp the record was written. */
+  updatedAt: string
+}
+
+/** A run record read back from a session log, with its log position. */
+export interface StoredRunRecord extends IterateRunRecord {
+  /** Session-log sequence number the record occupies. */
+  seq: number
+  /** Unix epoch milliseconds at append (from the host). */
+  time: number
+}
+
+/** Minimal structural view of the session-log API we consume. */
+export interface SessionRecordApi {
+  appendPluginRecord(session: unknown, type: string, data: unknown): number
+  pluginRecordOf(event: unknown): { type: string; seq: number; time: number; data: unknown } | undefined
+}
+
+/** Minimal structural view of a dsh Session (only what this module reads). */
+export interface SessionLike {
+  ownEvents?(): readonly unknown[]
+  snapshotEvents?(): readonly unknown[]
+}
+
+/** Result of a best-effort record append. */
+export type AppendRecordResult =
+  | { ok: true; supported: true; seq: number }
+  | { ok: false; supported: boolean; error: string }
+
+/** Result of reading the session's iterate run records. */
+export interface ReadRecordsResult {
+  supported: boolean
+  /** Oldest → newest. */
+  records: StoredRunRecord[]
+  /** Present only when the read itself failed unexpectedly. */
+  error?: string
+}
+
+// ─── Pure payload construction / validation ─────────────────────────────────
+
+/** Coerce an unknown to a finite non-negative integer, else `fallback`. */
+function nonNegInt(value: unknown, fallback = 0): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback
+  const n = Math.floor(value)
+  return n >= 0 ? n : fallback
+}
+
+/** Extract a string, else `''`. */
+function str(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+/** Extract one of the allowed literal values, else `null`. */
+function oneOf<T extends string>(value: unknown, allowed: readonly T[]): T | null {
+  return typeof value === 'string' && (allowed as readonly string[]).includes(value) ? (value as T) : null
+}
+
+/** Severity counts recovered from an on-disk manifest summary. */
+export interface RunRecordCounts {
+  total: number
+  critical: number
+  high: number
+  medium: number
+  low: number
+}
+
+/**
+ * Build a run record from the fields a persisted transcript manifest exposes.
+ * Pure: the caller passes already-normalized values, so this is unit-testable
+ * without touching disk or a session.
+ */
+export function buildRunRecord(input: {
+  project?: unknown
+  goal?: unknown
+  mode?: unknown
+  taskMode?: unknown
+  round?: unknown
+  maxRounds?: unknown
+  active?: unknown
+  stoppedReason?: unknown
+  convergence?: unknown
+  counts?: Partial<RunRecordCounts>
+  fixedCount?: unknown
+  qualityStatus?: unknown
+  now?: string
+}): IterateRunRecord {
+  const convergence = Array.isArray(input.convergence)
+    ? input.convergence
+        .filter((n): n is number => typeof n === 'number' && Number.isFinite(n) && n >= 0)
+        .slice(-1000)
+    : []
+  const c = input.counts ?? {}
+  const stopped = str(input.stoppedReason)
+  return {
+    version: ITERATE_RUN_RECORD_VERSION,
+    project: str(input.project),
+    goal: str(input.goal),
+    mode: oneOf(input.mode, ['dry-run', 'normal'] as const),
+    taskMode: oneOf(input.taskMode, ['code', 'iterate'] as const),
+    round: nonNegInt(input.round),
+    maxRounds: nonNegInt(input.maxRounds),
+    active: input.active !== false,
+    stoppedReason: stopped ? stopped : null,
+    convergence,
+    findings: {
+      total: nonNegInt(c.total),
+      critical: nonNegInt(c.critical),
+      high: nonNegInt(c.high),
+      medium: nonNegInt(c.medium),
+      low: nonNegInt(c.low),
+    },
+    fixedCount: nonNegInt(input.fixedCount),
+    qualityStatus: oneOf(input.qualityStatus, ['pass', 'fail', 'pending'] as const),
+    updatedAt: str(input.now) || new Date().toISOString(),
+  }
+}
+
+/**
+ * Owner-side validation of a payload read back from a session log.
+ * A restored record carries whatever JSON an earlier build of this plugin
+ * wrote, so every field is re-checked; anything unrecognizable returns `null`
+ * (the caller skips it) rather than surfacing junk to a renderer.
+ */
+export function normalizeRunRecord(data: unknown): IterateRunRecord | null {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return null
+  const d = data as Record<string, unknown>
+  // A record written by a future/incompatible build is skipped rather than
+  // coerced: the version gate is the contract that lets the payload evolve.
+  // The check is exact (an integer compare, not a floor) so a payload stamped
+  // `1.9` by a future build is rejected instead of rounded down to `1`.
+  if (!Number.isInteger(d.version) || d.version !== ITERATE_RUN_RECORD_VERSION) return null
+  const findings = (d.findings && typeof d.findings === 'object' && !Array.isArray(d.findings)
+    ? (d.findings as Record<string, unknown>)
+    : {}) as Record<string, unknown>
+  return buildRunRecord({
+    project: d.project,
+    goal: d.goal,
+    mode: d.mode,
+    taskMode: d.taskMode,
+    round: d.round,
+    maxRounds: d.maxRounds,
+    active: d.active,
+    stoppedReason: d.stoppedReason,
+    convergence: d.convergence,
+    counts: {
+      total: findings.total as number,
+      critical: findings.critical as number,
+      high: findings.high as number,
+      medium: findings.medium as number,
+      low: findings.low as number,
+    },
+    fixedCount: d.fixedCount,
+    qualityStatus: d.qualityStatus,
+    now: typeof d.updatedAt === 'string' ? d.updatedAt : undefined,
+  })
+}
+
+// ─── Session access (lazy, fail-safe) ────────────────────────────────────────
+
+/** Lazily-resolved production API; `undefined` = not yet attempted. */
+let cachedApi: Promise<SessionRecordApi | null> | undefined
+/** Test override; when set (including `null`) the dynamic import is bypassed. */
+let testApiOverride: SessionRecordApi | null | undefined
+/** Module loader; replaceable for tests to exercise import failure/late availability. */
+let moduleImporter: () => Promise<unknown> = () => import('@deepseek-ai/dsh-session')
+
+/** Resolve the `@deepseek-ai/dsh-session` record API, or `null` when absent. */
+export function loadSessionRecordApi(): Promise<SessionRecordApi | null> {
+  if (testApiOverride !== undefined) return Promise.resolve(testApiOverride)
+  if (cachedApi === undefined) {
+    // `Promise.resolve().then(...)` (not a bare call) so a loader that throws
+    // SYNCHRONOUSLY still lands in the `.catch` instead of escaping.
+    cachedApi = Promise.resolve()
+      .then(() => moduleImporter())
+      .then((mod) => {
+        const m = mod as unknown as Partial<SessionRecordApi>
+        if (typeof m.appendPluginRecord !== 'function' || typeof m.pluginRecordOf !== 'function') {
+          return null
+        }
+        return {
+          appendPluginRecord: m.appendPluginRecord.bind(mod),
+          pluginRecordOf: m.pluginRecordOf.bind(mod),
+        }
+      })
+      .catch(() => null)
+    // A `null` resolution (module/API absent, or a transient import failure) is
+    // NOT memoized: it is cleared so the next call retries. Otherwise one
+    // unlucky first import would disable session linking for the whole process.
+    void cachedApi.then((api) => {
+      if (!api) cachedApi = undefined
+    })
+  }
+  return cachedApi
+}
+
+/**
+ * Replace the module loader for tests (to exercise the import-failure and
+ * late-availability paths). Pass `undefined` to restore the real dynamic import.
+ */
+export function setSessionRecordImporterForTests(loader: (() => Promise<unknown>) | undefined): void {
+  moduleImporter = loader ?? (() => import('@deepseek-ai/dsh-session'))
+  cachedApi = undefined
+}
+
+/**
+ * Override the session-record API for tests. Pass `undefined` to restore the
+ * real dynamic import, or an object / `null` to force a deterministic result.
+ */
+export function setSessionRecordApiForTests(api: SessionRecordApi | null | undefined): void {
+  testApiOverride = api
+}
+
+/** Extract the session from a tool execution (`exec.agent.session`), defensively. */
+export function sessionOf(exec: unknown): SessionLike | undefined {
+  try {
+    const agent = (exec as { agent?: { session?: unknown } } | null | undefined)?.agent
+    const session = agent?.session
+    if (!session || typeof session !== 'object') return undefined
+    const s = session as SessionLike
+    if (typeof s.ownEvents === 'function' || typeof s.snapshotEvents === 'function') return s
+    return undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Read every event a session exposes (own events preferred, snapshot fallback). */
+function eventsOf(session: SessionLike): readonly unknown[] {
+  try {
+    if (typeof session.ownEvents === 'function') return session.ownEvents() ?? []
+  } catch {
+    // fall through to snapshot
+  }
+  try {
+    if (typeof session.snapshotEvents === 'function') return session.snapshotEvents() ?? []
+  } catch {
+    // no readable log
+  }
+  return []
+}
+
+/**
+ * Best-effort append of one run record to the session log.
+ * Never throws: an absent API, a degraded session, or a rejected payload all
+ * surface as `{ ok: false }` so the surrounding tool call can continue.
+ */
+export async function appendRunRecord(
+  session: SessionLike | undefined,
+  record: IterateRunRecord,
+): Promise<AppendRecordResult> {
+  const api = await loadSessionRecordApi()
+  if (!api) return { ok: false, supported: false, error: 'session record API unavailable' }
+  if (!session) return { ok: false, supported: true, error: 'no session in scope' }
+  try {
+    const seq = api.appendPluginRecord(session, ITERATE_RUN_RECORD_TYPE, record)
+    return { ok: true, supported: true, seq }
+  } catch (err) {
+    return {
+      ok: false,
+      supported: true,
+      error: `session rejected the run record: ${err instanceof Error ? err.message : String(err)}`,
+    }
+  }
+}
+
+/** Read every iterate run record from the session log (oldest → newest). */
+export async function readRunRecords(session: SessionLike | undefined): Promise<ReadRecordsResult> {
+  const api = await loadSessionRecordApi()
+  if (!api) return { supported: false, records: [] }
+  if (!session) return { supported: true, records: [] }
+  try {
+    const records: StoredRunRecord[] = []
+    for (const event of eventsOf(session)) {
+      const rec = api.pluginRecordOf(event)
+      if (!rec || rec.type !== ITERATE_RUN_RECORD_TYPE) continue
+      const normalized = normalizeRunRecord(rec.data)
+      if (!normalized) continue
+      records.push({ ...normalized, seq: nonNegInt(rec.seq), time: nonNegInt(rec.time) })
+    }
+    return { supported: true, records }
+  } catch (err) {
+    return {
+      supported: true,
+      records: [],
+      error: `failed to read session records: ${err instanceof Error ? err.message : String(err)}`,
+    }
+  }
+}

package/src/skill-prompt.ts

@@ -23,7 +23,8 @@ You have the iterate plugin installed, which registers these tools:
 - \`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 on disk with no newer decision-log activity 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.
-- \`iterate_transcript\` — runtime observatory file (\`.iterate/transcript.json\`). \`read\` fetches the persisted manifest including any steering \`nudge\` for this run's reviewers; \`capture\` (call once after the final report) persists the per-reviewer threads, convergence trend, findings, fixes, checkpoint, per-round validation results (\`validations\`: command + exitCode + allowed + rejectReason), and timeline so the client observatory panel reflects the run; \`nudge\` sets/clears steering text the next round's reviewers read. Purely local, never touches source files.
+- \`iterate_transcript\` — runtime observatory file (\`.iterate/transcript.json\`). \`read\` fetches the persisted manifest including any steering \`nudge\` for this run's reviewers — and, when the file is missing or malformed, recovers a summary manifest from the session log's run record (returns \`recovered:true\`); \`capture\` (call once after the final report) persists the per-reviewer threads, convergence trend, findings, fixes, checkpoint, per-round validation results (\`validations\`: command + exitCode + allowed + rejectReason), and timeline so the client observatory panel reflects the run, and links the run to the dsh session (\`sessionRecord\`); \`recall\` lists the run records linked to this session (newest first) so a run stays traceable after \`.iterate/\` is wiped; \`nudge\` sets/clears steering text the next round's reviewers read. Purely local, never touches source files.
+- \`iterate_report\` — export the current run as a portable report. \`format:"markdown"\` (default) renders a PR-pasteable report (run header, quality gate, findings, fixes, validations, defense events, experience bank); \`format:"sarif"\` renders a SARIF 2.1.0 log for CI / GitHub Code Scanning (one rule per review dimension, severity → error/warning/note, file+line locations, suggested fix attached). Set \`write:true\` to persist it under \`.iterate/report.md\` / \`.iterate/report.sarif\`; \`lang\` (zh | en) selects the report language. Read-only apart from the optional report file.
 - \`iterate_experience\` — experience bank (\`.iterate/experience.json\`): \`list\`/\`search\`/\`get\` recall verified fixes and patterns from past sessions (read the bank before fixing so proven fixes are applied first); \`add\` records a new verified fix — re-adding the same pattern+dimension bumps its hit count instead of duplicating it; \`remove\` deletes a stale or incorrect entry by \`id\` so bad experiences never resurface.
 - \`iterate_quality_gate\` — quality certificate: \`read\` loads the persisted dimension convergence rates / verification pass rate / PASS-FAIL status; \`compute\` recomputes a fresh snapshot from this round's findings + validation results (supply \`findingsByRound\` for real convergence) and persists it to \`.iterate/quality-gate.json\`; \`clear\` removes the persisted certificate to reset a stale gate before a fresh iteration.
 - \`iterate_defense_events\` — defense event stream (\`.iterate/defense-events.json\`): \`list\`/\`counts\` review precondition failures, rollbacks, invariant violations, and falsified assumptions; \`record\` logs a new event when a defense fires. Human-readable labels follow the project \`language\` (en/zh).

package/src/tools/report.ts

@@ -0,0 +1,244 @@
+/**
+ * src/tools/report.ts — `iterate_report` tool.
+ *
+ *   iterate_report — render the current iterate run into a portable report.
+ *
+ * Two formats, one normalized data model (shared with the client export
+ * buttons via `src/report-render.ts`, so the on-screen export and this tool
+ * can never drift):
+ *
+ *   - `markdown` — a PR-pasteable run report: header (mode/round/status), the
+ *                  quality-gate table, the findings table, the fixes table,
+ *                  validations, defense events, and the experience bank.
+ *   - `sarif`    — a SARIF 2.1.0 log so CI / GitHub Code Scanning can consume
+ *                  iterate findings as code-scanning results (ruleId =
+ *                  dimension, severity → error/warning/note, file+line
+ *                  locations, suggested fix attached).
+ *
+ * Reads only local state (`.iterate/transcript.json` + the quality / experience
+ * / defense stores) and writes only `.iterate/report.<ext>` when `write:true`.
+ * Malformed or missing state is rendered as-is (empty tables) — an export must
+ * never fail because a run was partial.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+import { resolveProjectRootForExec } from '../config-loader.ts'
+import { iterateDir, transcriptPath } from '../paths.ts'
+import { readQualityGate } from './quality-store.ts'
+import { readExperienceBank } from './experience-store.ts'
+import { readDefenseEvents } from './defense-store.ts'
+import { resultHeadline } from './present.ts'
+import { renderRunReportMarkdown, renderRunReportSarif, REPORT_FORMATS } from '../report-render.ts'
+
+/** Formats accepted by the tool (kept in sync with the shared renderer). */
+const FORMATS: ReadonlySet<string> = new Set(REPORT_FORMATS)
+
+/** Read the persisted transcript manifest, tolerating a missing/garbled file. */
+function readManifest(projectRoot: string): { manifest: unknown; source: 'disk' | 'empty' } {
+  const file = transcriptPath(projectRoot)
+  if (!existsSync(file)) return { manifest: {}, source: 'empty' }
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf-8')) as unknown
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return { manifest: parsed, source: 'disk' }
+    }
+    return { manifest: {}, source: 'empty' }
+  } catch {
+    return { manifest: {}, source: 'empty' }
+  }
+}
+
+/**
+ * Register the `iterate_report` tool.
+ * Renders the current run into a Markdown or SARIF report.
+ */
+export function registerReportTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_report',
+      // Result card: surface the report headline ("report: markdown · N findings")
+      // as the card title. Pure: reads only the rendered result (replay-safe).
+      presentResult: (_args, result) => {
+        const title = resultHeadline(result)
+        return title ? { card: 'generic', title } : undefined
+      },
+      // `write:true` persists a file; a pure render joins a parallel group.
+      isConcurrencySafe: (args) => (args as { write?: unknown }).write !== true,
+      description:
+        'Export the current iterate run as a portable report. ' +
+        '`format:"markdown"` (default) renders a PR-pasteable report: run header (mode / round / status), ' +
+        'quality-gate table, findings table, fixes table, per-round validations, defense events, and the ' +
+        'experience bank. `format:"sarif"` renders a SARIF 2.1.0 log for CI / GitHub Code Scanning ' +
+        '(one rule per review dimension; finding severity maps to error/warning/note; findings carry ' +
+        'file + line locations and the suggested fix). ' +
+        'Set `write:true` to also persist the report under `.iterate/report.md` / `.iterate/report.sarif` ' +
+        'and get the path back. `lang` selects the report language (zh | en). ' +
+        'Read-only apart from the optional report file; never touches source files.',
+      parameters: {
+        format: {
+          type: 'string',
+          description: 'Report format: "markdown" (default) or "sarif".',
+          enum: ['markdown', 'sarif'],
+        },
+        write: {
+          type: 'boolean',
+          description: 'When true, persist the report to `.iterate/report.md` / `.iterate/report.sarif` and return its path. Default: false.',
+        },
+        lang: {
+          type: 'string',
+          description: 'Report language: "zh" (default) or "en". Affects labels/headings only.',
+          enum: ['zh', 'en'],
+        },
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean', required: true },
+            kind: { type: 'string' },
+            format: { type: 'string' },
+            /** The rendered report text (Markdown, or pretty-printed SARIF JSON). */
+            content: { type: 'string' },
+            /** The SARIF log object, when format is "sarif". */
+            sarif: { type: 'json' },
+            /** Whether a source transcript manifest was found on disk. */
+            source: { type: 'string' },
+            written: { type: 'boolean' },
+            reportPath: { type: 'string' },
+            findings: { type: 'number' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (!value.ok) return [{ type: 'text', text: `report export failed: ${value.error}` }]
+          const content = typeof value.content === 'string' ? value.content : ''
+          const header = [
+            `report: ${String(value.format ?? 'markdown')} · ${String(value.findings ?? 0)} findings · source=${String(value.source ?? 'empty')}`,
+            value.written ? `written to ${String(value.reportPath ?? '')}` : '',
+          ].filter(Boolean).join(' · ')
+          return [{ type: 'text', text: `${header}\n\n${content}` }]
+        },
+      },
+
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
+        if (!resolved.ok) return { ok: false, kind: 'report', error: resolved.reason }
+        const projectRoot = resolved.root
+
+        const rawFormat = typeof args.format === 'string' ? args.format : 'markdown'
+        const format = FORMATS.has(rawFormat) ? rawFormat : 'markdown'
+        const lang = args.lang === 'en' ? 'en' : 'zh'
+
+        const { manifest, source } = readManifest(projectRoot)
+        let qualityGate: unknown = null
+        let experienceBank: unknown = null
+        let defenseEvents: unknown = null
+        try {
+          qualityGate = readQualityGate(projectRoot)
+        } catch {
+          qualityGate = null
+        }
+        try {
+          experienceBank = readExperienceBank(projectRoot)
+        } catch {
+          experienceBank = null
+        }
+        try {
+          defenseEvents = readDefenseEvents(projectRoot)
+        } catch {
+          defenseEvents = null
+        }
+
+        const extra = { qualityGate, experienceBank, defenseEvents }
+        let content: string
+        let sarif: JsonValue | undefined
+        let findings = 0
+        try {
+          if (format === 'sarif') {
+            const doc = renderRunReportSarif(manifest, extra, {
+              toolVersion: pluginVersion(),
+            }) as unknown as { runs?: Array<{ results?: unknown[] }> }
+            sarif = doc as unknown as JsonValue
+            content = JSON.stringify(doc, null, 2)
+            findings = Array.isArray(doc?.runs?.[0]?.results) ? (doc.runs[0].results as unknown[]).length : 0
+          } else {
+            content = renderRunReportMarkdown(manifest, extra, { lang }) as unknown as string
+            findings = countMarkdownFindings(content)
+          }
+        } catch (err) {
+          return {
+            ok: false,
+            kind: 'report',
+            format,
+            error: `failed to render report: ${err instanceof Error ? err.message : String(err)}`,
+          }
+        }
+
+        let written = false
+        let reportPath: string | undefined
+        if (args.write === true) {
+          try {
+            const dir = iterateDir(projectRoot)
+            mkdirSync(dir, { recursive: true })
+            reportPath = `${dir}/report.${format === 'sarif' ? 'sarif' : 'md'}`
+            writeFileSync(reportPath, content, 'utf-8')
+            written = true
+          } catch (err) {
+            return {
+              ok: false,
+              kind: 'report',
+              format,
+              error: `failed to write report: ${err instanceof Error ? err.message : String(err)}`,
+            }
+          }
+        }
+
+        return {
+          ok: true,
+          kind: 'report',
+          format,
+          content,
+          ...(sarif !== undefined ? { sarif } : {}),
+          source,
+          written,
+          ...(reportPath ? { reportPath } : {}),
+          findings,
+        }
+      },
+    }),
+  )
+}
+
+/**
+ * Best-effort plugin version for the SARIF driver. Resolved from the package
+ * manifest next to this module (`src/tools` and `dist/tools` are both two
+ * levels below the root); an unreadable/unparsable manifest yields ''.
+ */
+function pluginVersion(): string {
+  try {
+    const raw = readFileSync(new URL('../../package.json', import.meta.url), 'utf-8')
+    const pkg = JSON.parse(raw) as { version?: unknown }
+    return typeof pkg.version === 'string' ? pkg.version : ''
+  } catch {
+    return ''
+  }
+}
+
+/** Count the findings table rows in a rendered Markdown report (for the card). */
+function countMarkdownFindings(markdown: string): number {
+  const m = /##\s+.*?\((\d+)\)/.exec(markdown)
+  if (m && m[1]) {
+    const n = Number(m[1])
+    if (Number.isFinite(n)) return n
+  }
+  return 0
+}