iterate-plugin 3.7.0 → 3.9.0

package/dist/skill-prompt.js

@@ -22,7 +22,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).
@@ -134,7 +135,7 @@ for (let r = 1; r <= maxRounds; r++) {
         (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
         '\\n Already-known findings (do NOT re-report): ' +
         JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.'
-      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
+      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta?.findingsSchema }, backend))
     }))
     // A per-dimension reviewer subagent resolves \`null\` on child failure; the
     // aggregate below would report an all-failed round as an empty round, and
@@ -463,7 +464,7 @@ for (let r = startRound; r <= maxRounds; r++) {
         (steering ? '\\n STEERING — read this first: ' + steering : '') +
         (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
         '\\n Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.'
-      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
+      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta?.findingsSchema }, backend))
     }))
     // ALL reviewers returning null (child failures) means this round produced
     // no usable output — an empty aggregate must not read like a clean

package/dist/tools/checkpoint.js

@@ -12,6 +12,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
 import { writeJsonAtomic } from "../atomic-fs.js";
+import { withProjectLock } from "../file-lock.js";
 import { checkpointPath, iterateDir, transcriptPath } from "../paths.js";
 import { readRegistry } from "./fix.js";
 import { readDecisionEntries } from "./decision-log.js";
@@ -289,23 +290,29 @@ export function registerCheckpointTool(ctx) {
                 return { operation: 'load', ok: true, checkpoint: checkpoint };
             }
             if (args.operation === 'resume') {
-                const current = readCheckpoint(projectRoot);
-                if (!current) {
-                    return { operation: 'resume', ok: false, error: 'no checkpoint to resume — run `save` first' };
-                }
-                const resumed = {
-                    ...current,
-                    resumeCount: (current.resumeCount ?? 0) + 1,
-                    updatedAt: new Date().toISOString(),
-                };
-                try {
-                    mkdirSync(iterateDir(projectRoot), { recursive: true });
-                    writeJsonAtomic(checkpointPath(projectRoot), resumed);
-                }
-                catch (err) {
-                    return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` };
-                }
-                return { operation: 'resume', ok: true, checkpoint: resumed };
+                // Read-modify-write across processes: a concurrent resume in a
+                // sibling process would read the same resumeCount and write it back,
+                // losing one increment. Serialize on a checkpoint lock (the same
+                // advisory pattern the config/triage/transcript writers use).
+                return withProjectLock(projectRoot, 'checkpoint', () => {
+                    const current = readCheckpoint(projectRoot);
+                    if (!current) {
+                        return { operation: 'resume', ok: false, error: 'no checkpoint to resume — run `save` first' };
+                    }
+                    const resumed = {
+                        ...current,
+                        resumeCount: (current.resumeCount ?? 0) + 1,
+                        updatedAt: new Date().toISOString(),
+                    };
+                    try {
+                        mkdirSync(iterateDir(projectRoot), { recursive: true });
+                        writeJsonAtomic(checkpointPath(projectRoot), resumed);
+                    }
+                    catch (err) {
+                        return { operation: 'resume', ok: false, error: `failed to persist resumed checkpoint: ${String(err)}` };
+                    }
+                    return { operation: 'resume', ok: true, checkpoint: resumed };
+                });
             }
             if (args.operation === 'clear') {
                 const existed = existsSync(checkpointPath(projectRoot));

package/dist/tools/config.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { defaultConfig, loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from "../config-loader.js";
 import { applyConfigUpdates, readRawConfig, validateConfigUpdates, writeConfigFile, } from "../config-write.js";
+import { withProjectLock } from "../file-lock.js";
 /**
  * Register the `iterate_config` tool.
  * Reads and returns the iterate.config.yaml configuration, or writes a
@@ -105,42 +106,50 @@ export function registerConfigTool(ctx) {
                 if (updateErrors.length > 0) {
                     return { operation: 'write', ok: false, found: false, errors: updateErrors };
                 }
-                let base;
-                try {
-                    // Partial updates must be mergeable on a FRESH project (no config
-                    // file yet): otherwise `{max_rounds: 5}` alone fails schema
-                    // validation with a misleading "missing goal". Merge against the
-                    // built-in defaults when there is no file to read, so the written
-                    // config captures the effective config (defaults + update) and the
-                    // documented "write a partial update" contract works out of the box.
-                    base = existsSync(join(projectRoot, 'iterate.config.yaml'))
-                        ? readRawConfig(join(projectRoot, 'iterate.config.yaml'))
-                        : defaultConfig();
-                }
-                catch (err) {
-                    return { operation: 'write', ok: false, found: false, error: `failed to read config: ${String(err)}` };
-                }
-                const merged = applyConfigUpdates(base, updates ?? {});
-                const schemaErrors = validateConfig(merged);
-                if (schemaErrors.length > 0) {
+                // Serialize the read→merge→validate→write cycle against any other
+                // config/triage writer in a sibling process: without the lock, two
+                // sessions on the same project each read a stale base and the second
+                // merge silently discards the first's update (lost update). The same
+                // lock name is shared with `iterate_triage apply` so the two writers
+                // are mutually exclusive.
+                return withProjectLock(projectRoot, 'config-write', () => {
+                    let base;
+                    try {
+                        // Partial updates must be mergeable on a FRESH project (no config
+                        // file yet): otherwise `{max_rounds: 5}` alone fails schema
+                        // validation with a misleading "missing goal". Merge against the
+                        // built-in defaults when there is no file to read, so the written
+                        // config captures the effective config (defaults + update) and the
+                        // documented "write a partial update" contract works out of the box.
+                        base = existsSync(join(projectRoot, 'iterate.config.yaml'))
+                            ? readRawConfig(join(projectRoot, 'iterate.config.yaml'))
+                            : defaultConfig();
+                    }
+                    catch (err) {
+                        return { operation: 'write', ok: false, found: false, error: `failed to read config: ${String(err)}` };
+                    }
+                    const merged = applyConfigUpdates(base, updates ?? {});
+                    const schemaErrors = validateConfig(merged);
+                    if (schemaErrors.length > 0) {
+                        return {
+                            operation: 'write',
+                            ok: false,
+                            found: false,
+                            errors: schemaErrors.map((e) => `missing/required field: ${e}`),
+                        };
+                    }
+                    const result = writeConfigFile(projectRoot, merged);
+                    if (!result.ok)
+                        return { operation: 'write', ok: false, found: false, error: result.error };
+                    const { config } = loadEffectiveConfig(projectRoot);
                     return {
                         operation: 'write',
-                        ok: false,
-                        found: false,
-                        errors: schemaErrors.map((e) => `missing/required field: ${e}`),
+                        ok: true,
+                        found: true,
+                        backupPath: result.backupPath ?? null,
+                        config: config,
                     };
-                }
-                const result = writeConfigFile(projectRoot, merged);
-                if (!result.ok)
-                    return { operation: 'write', ok: false, found: false, error: result.error };
-                const { config } = loadEffectiveConfig(projectRoot);
-                return {
-                    operation: 'write',
-                    ok: true,
-                    found: true,
-                    backupPath: result.backupPath ?? null,
-                    config: config,
-                };
+                });
             }
             // ── Read operations (original behavior) ────────────────────────────
             const { config, source } = loadEffectiveConfig(projectRoot);

package/dist/tools/decision-log.js

@@ -1,8 +1,8 @@
-import { appendFileSync, readFileSync, mkdirSync, existsSync, openSync, writeSync, closeSync, unlinkSync, statSync, } from 'node:fs';
+import { appendFileSync, readFileSync, mkdirSync, existsSync, statSync, } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
-import { makeLockRelease } from "../file-lock.js";
+import { acquireProjectLockChecked } from "../file-lock.js";
 const LOG_DIR = '.iterate';
 const LOG_FILE = 'decision-log.jsonl';
 // ─── Cross-process log mutex ────────────────────────────────────────────────
@@ -19,34 +19,15 @@ const LOG_FILE = 'decision-log.jsonl';
 // be lost to a wedged append), never to a crash. The prune REWRITE is the
 // opposite — it renames the log and therefore refuses to run when the lock
 // cannot be taken (see `rewriteDecisionLogKeepingRecent` in prune.ts).
-const LOCK_FILE = '.decision-log.lock';
-const LOCK_WAIT_MS = 5000;
-const LOCK_STALE_MS = 10000;
-const LOCK_POLL_MS = 25;
-/** True when a pid refers to a live process (or we lack permission to tell). */
-function processAlive(pid) {
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return err.code === 'EPERM';
-    }
-}
-/** Synchronous busy-wait sleep (Atomics.wait is a reliable sleep in Node). */
-function sleepSync(ms) {
-    const sab = new Int32Array(new SharedArrayBuffer(4));
-    Atomics.wait(sab, 0, 0, ms);
-}
+/** Lock name shared with the prune rewrite (→ `.iterate/.decision-log.lock`). */
+const LOG_LOCK_NAME = 'decision-log';
 /**
  * Acquire the decision-log lock for `projectRoot`.
  * Returns a release function (always callable; a no-op when the lock could
  * not be taken — never wedge an append behind a vanished holder).
  *
- * `options.waitMs` / `options.staleMs` override the defaults (tests use short
- * waits so a live-holder timeout is exercised in milliseconds, not 5s).
+ * `options.waitMs` / `options.staleMs` override the shared defaults (tests use
+ * short waits so a live-holder timeout is exercised in milliseconds, not 5s).
  */
 export function acquireLogLock(projectRoot, options = {}) {
     return acquireLogLockChecked(projectRoot, options).release;
@@ -57,76 +38,15 @@ export function acquireLogLock(projectRoot, options = {}) {
  * audit line must not be lost to a wedged append), but the rewrite renames the
  * log under any unlocked concurrent appender — it must refuse to run without
  * the mutex rather than silently dropping an audit line.
+ *
+ * Delegates to the shared `acquireProjectLockChecked` with lock name
+ * `decision-log`: the decision-log mutex IS that generic project lock. This
+ * module used to hand-roll an identical copy of the acquire/steal/wait logic,
+ * and the two stale/wait parameter sets could drift apart — one implementation,
+ * one set of defaults, one ownership-checked release.
  */
 export function acquireLogLockChecked(projectRoot, options = {}) {
-    const waitMs = Number.isFinite(options.waitMs) && (options.waitMs ?? 0) >= 0
-        ? options.waitMs
-        : LOCK_WAIT_MS;
-    const staleMs = Number.isFinite(options.staleMs) && (options.staleMs ?? 0) >= 0
-        ? options.staleMs
-        : LOCK_STALE_MS;
-    const dir = join(projectRoot, LOG_DIR);
-    if (!existsSync(dir)) {
-        try {
-            mkdirSync(dir, { recursive: true });
-        }
-        catch {
-            return { acquired: false, release: () => { } };
-        }
-    }
-    const lockPath = join(dir, LOCK_FILE);
-    const start = Date.now();
-    for (;;) {
-        let fd = null;
-        try {
-            fd = openSync(lockPath, 'wx');
-        }
-        catch (err) {
-            if (err.code !== 'EEXIST')
-                return { acquired: false, release: () => { } };
-            // Lock exists — steal it when the owner is gone or the lock is ancient.
-            let stale = false;
-            try {
-                const st = statSync(lockPath);
-                if (Date.now() - st.mtimeMs > staleMs)
-                    stale = true;
-                else {
-                    const pid = Number(readFileSync(lockPath, 'utf-8'));
-                    if (!processAlive(pid))
-                        stale = true;
-                }
-            }
-            catch {
-                stale = true; // unreadable/vanishing lock → retry as stale
-            }
-            if (stale) {
-                try {
-                    unlinkSync(lockPath);
-                }
-                catch { /* another holder stole it */ }
-                continue;
-            }
-            if (Date.now() - start > waitMs)
-                return { acquired: false, release: () => { } };
-            sleepSync(LOCK_POLL_MS);
-            continue;
-        }
-        // Owned the lock: stamp the holder pid, then release once on return.
-        // The release is ownership-checked (see `makeLockRelease`): a lock stolen
-        // from this process after its owner went stale must not be unlinked by us.
-        try {
-            writeSync(fd, String(process.pid));
-        }
-        catch { /* pid stamp is advisory */ }
-        try {
-            closeSync(fd);
-        }
-        catch { /* best-effort */ }
-        return {
-            acquired: true,
-            release: makeLockRelease(lockPath),
-        };
-    }
+    return acquireProjectLockChecked(projectRoot, LOG_LOCK_NAME, options);
 }
 // ─── Entry-count cache (avoid an O(n) full re-read per append) ─────────────
 /**

package/dist/tools/report.js

@@ -0,0 +1,239 @@
+/**
+ * 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 `lib/parse.js`, 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 { resolveProjectRootForExec } from "../config-loader.js";
+import { iterateDir, transcriptPath } from "../paths.js";
+import { readQualityGate } from "./quality-store.js";
+import { readExperienceBank } from "./experience-store.js";
+import { readDefenseEvents } from "./defense-store.js";
+import { resultHeadline } from "./present.js";
+import { renderRunReportMarkdown, renderRunReportSarif, REPORT_FORMATS } from "../report-render.js";
+/** Formats accepted by the tool (kept in sync with the shared renderer). */
+const FORMATS = new Set(REPORT_FORMATS);
+/** Read the persisted transcript manifest, tolerating a missing/garbled file. */
+function readManifest(projectRoot) {
+    const file = transcriptPath(projectRoot);
+    if (!existsSync(file))
+        return { manifest: {}, source: 'empty' };
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+        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) {
+    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.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 = null;
+            let experienceBank = null;
+            let defenseEvents = 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;
+            let sarif;
+            let findings = 0;
+            try {
+                if (format === 'sarif') {
+                    const doc = renderRunReportSarif(manifest, extra, {
+                        toolVersion: pluginVersion(),
+                    });
+                    sarif = doc;
+                    content = JSON.stringify(doc, null, 2);
+                    findings = Array.isArray(doc?.runs?.[0]?.results) ? doc.runs[0].results.length : 0;
+                }
+                else {
+                    content = renderRunReportMarkdown(manifest, extra, { lang });
+                    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;
+            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() {
+    try {
+        const raw = readFileSync(new URL('../../package.json', import.meta.url), 'utf-8');
+        const pkg = JSON.parse(raw);
+        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) {
+    const m = /##\s+.*?\((\d+)\)/.exec(markdown);
+    if (m && m[1]) {
+        const n = Number(m[1]);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return 0;
+}