aiki-cli 0.2.0

package/dist/bench/harness.js

@@ -0,0 +1,251 @@
+// Bench harness (§17, T11). Runs the four arms on a versioned task set, scores each against the case's
+// seeded bugs, and writes bench/results/<suite>-<date>.json. Cases + arms run SEQUENTIALLY and results
+// are written INCREMENTALLY after each case, so a mid-run quota stop keeps completed work (grill 2026-07-04).
+// The bench itself is metered — verified by a scripted-adapter e2e; the real 4-arm run is the user's.
+import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { makeRunId, resolveRoles, RunCtx, setupProviders } from '../orchestration/context.js';
+import { executeRun } from '../orchestration/engine.js';
+import { RunWriter } from '../storage/runs.js';
+import { ARMS, ARM_IDS } from './arms.js';
+import { BugManifest, scoreRun } from './scoring/seeded-bugs.js';
+import { BenchResult, summarize } from './results.js';
+/** Load every case dir under bench/sets/<suite>/<set>/ (each = {diff.patch, bugs.json, source files}). */
+export async function loadCases(suite, set, root = process.cwd()) {
+    const base = join(root, 'bench', 'sets', suite, set);
+    let entries;
+    try {
+        entries = await readdir(base, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const cases = [];
+    for (const e of entries.filter((x) => x.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+        const dir = join(base, e.name);
+        const diff = await readFile(join(dir, 'diff.patch'), 'utf8');
+        const bugs = BugManifest.parse(JSON.parse(await readFile(join(dir, 'bugs.json'), 'utf8'))).bugs;
+        cases.push({ name: e.name, dir, diff, bugs });
+    }
+    return cases;
+}
+/** A/B/C need claude (the fixed single model); D needs claude+codex reviewers; E needs agy+codex
+ *  reviewers + claude judge (the Opus-thrift variant). */
+function armAvailable(arm, available) {
+    if (arm === 'D')
+        return available.includes('claude') && available.includes('codex');
+    if (arm === 'E')
+        return available.includes('agy') && available.includes('codex') && available.includes('claude');
+    return available.includes('claude');
+}
+/** Precision from FP labels in feedback.jsonl for this run, or null if the run hasn't been adjudicated. */
+async function readPrecision(runId, reported, root = process.cwd()) {
+    if (reported === 0)
+        return null;
+    try {
+        const lines = (await readFile(join(root, '.aiki', 'feedback.jsonl'), 'utf8')).trim().split('\n');
+        const forRun = lines.map((l) => JSON.parse(l)).filter((e) => e.run_id === runId && e.item_type === 'finding');
+        if (forRun.length === 0)
+            return null;
+        const fp = forRun.filter((e) => e.verdict === 'false-positive').length;
+        return (reported - fp) / reported;
+    }
+    catch {
+        return null;
+    }
+}
+async function runArmOnCase(arm, c, handles, available, root) {
+    const runId = makeRunId('code-review');
+    // Arm C's synthesis judge stays same-model; Arm E swaps the product pipeline's roles to the
+    // Opus-thrift config (agy+codex hunt, claude judge). D uses code-review defaults.
+    const overrides = arm === 'C' ? { judge: 'claude' }
+        : arm === 'E' ? { s4: ['agy', 'codex'], judge: 'claude' }
+            : undefined;
+    const roles = resolveRoles('code-review', available, overrides);
+    const ctx = new RunCtx({ runId, workflow: 'code-review', handles, roles, writer: new RunWriter(runId, join(root, '.aiki')), cwd: c.dir });
+    const started = Date.now();
+    let findings = [];
+    const outcome = await executeRun(ctx, c.diff, async (cx, input) => {
+        findings = await ARMS[arm](cx, input);
+    });
+    const wallMs = Date.now() - started;
+    if (!outcome.ok) {
+        return { arm, status: 'error', runId, reason: `${outcome.error?.code}: ${outcome.error?.message}`, calls: ctx.calls.length, wallMs };
+    }
+    // A scored outcome can still hide a mid-run provider failure: fault-tolerant arms (D) finish on the
+    // surviving providers when a reviewer crashes (e.g. Opus quota mid-run), so the result is NOT the
+    // registered pipeline. Don't score it as clean — mark it error so a `--resume` run retries it.
+    const failed = ctx.calls.filter((call) => call.error);
+    if (failed.length > 0) {
+        const detail = failed.map((call) => `${call.provider}@${call.stage}=${call.error}`).join(', ');
+        return { arm, status: 'error', runId, reason: `DEGRADED: provider call failed mid-run (${detail})`, calls: ctx.calls.length, wallMs };
+    }
+    // Persist the exact findings the scorer saw — single-call arms (A/B) have no review-map artifact,
+    // so this is what `aiki resolve` annotates for FP labels (precision's denominator = this list).
+    await ctx.writer.writeRaw('bench-findings.json', JSON.stringify(findings, null, 2));
+    const s = scoreRun(findings, c.bugs);
+    return {
+        arm,
+        status: 'scored',
+        runId,
+        seeded: s.seeded,
+        matched: s.matched,
+        recall: s.recall,
+        reported: s.reported,
+        unmatched: s.unmatched,
+        precision: await readPrecision(runId, s.reported, root),
+        calls: ctx.calls.length,
+        wallMs,
+    };
+}
+/** Approx claude/Opus calls each arm makes per case — for the pre-run quota estimate (§19). Not exact:
+ *  §14 JSON repairs can add a few, and D's cross-exam/judge vary; deliberately a round upper-ish figure. */
+export const CLAUDE_CALLS_PER_CASE = { A: 1, B: 1, C: 4, D: 2, E: 1 };
+/** ≈ claude/Opus calls for a list of case×arm pairs (the quota-sensitive cost the user cares about). */
+export function estimateClaudeCalls(pairs) {
+    return pairs.reduce((n, p) => n + (CLAUDE_CALLS_PER_CASE[p.arm] ?? 0), 0);
+}
+/** Resume target: continue the most-recent results file for this suite/set (so a run can be spread across
+ *  Opus windows, even across midnight); otherwise a fresh dated file. */
+async function resolveCampaign(resultsDir, suite, set, resume) {
+    const dated = join(resultsDir, `${suite}-${new Date().toISOString().slice(0, 10)}.json`);
+    if (!resume)
+        return { path: dated };
+    // Only real `<suite>-YYYY-MM-DD.json` campaign files — so an archived/renamed run (e.g.
+    // `<suite>-2026-07-04.void.json`) is ignored and won't be resumed by accident.
+    const campaign = new RegExp(`^${suite}-\\d{4}-\\d{2}-\\d{2}\\.json$`);
+    let names = [];
+    try {
+        names = (await readdir(resultsDir)).filter((f) => campaign.test(f));
+    }
+    catch {
+        return { path: dated };
+    }
+    names.sort(); // ISO date in the name → lexical order is chronological
+    for (const name of names.reverse()) {
+        try {
+            const parsed = BenchResult.safeParse(JSON.parse(await readFile(join(resultsDir, name), 'utf8')));
+            if (parsed.success && parsed.data.suite === suite && parsed.data.set === set) {
+                return { path: join(resultsDir, name), prior: parsed.data };
+            }
+        }
+        catch {
+            /* skip an unparseable/partial file, try the next-most-recent */
+        }
+    }
+    return { path: dated };
+}
+/** Map of `case::arm` → the prior ArmScore for pairs already `scored` (resume reuses these; error/skipped are retried). */
+function priorScored(prior) {
+    const done = new Map();
+    for (const pc of prior?.cases ?? []) {
+        for (const a of pc.arms)
+            if (a.status === 'scored')
+                done.set(`${pc.case}::${a.arm}`, a);
+    }
+    return done;
+}
+/** Dry-run: resolve what a `runBench` with these options would execute + its ≈Opus cost. No model calls. */
+export async function planBench(opts = {}) {
+    const suite = opts.suite ?? 'code-review';
+    const set = opts.set ?? 'build';
+    const arms = opts.arms ?? [...ARM_IDS];
+    const root = opts.root ?? process.cwd();
+    const handles = opts.handles ?? (await setupProviders());
+    const available = handles.map((h) => h.id);
+    const cases = await loadCases(suite, set, root);
+    const resultsDir = join(root, 'bench', 'results');
+    const { path, prior } = await resolveCampaign(resultsDir, suite, set, !!opts.resume);
+    const done = priorScored(prior);
+    const toRun = [];
+    let skipCompleted = 0;
+    let skipUnavailable = 0;
+    for (const c of cases) {
+        for (const arm of arms) {
+            if (opts.resume && done.has(`${c.name}::${arm}`))
+                skipCompleted++;
+            else if (!armAvailable(arm, available))
+                skipUnavailable++;
+            else
+                toRun.push({ case: c.name, arm });
+        }
+    }
+    return {
+        suite,
+        set,
+        arms,
+        cases: cases.map((c) => c.name),
+        toRun,
+        skipCompleted,
+        skipUnavailable,
+        estClaudeCalls: estimateClaudeCalls(toRun),
+        resultsPath: path,
+        resumedFrom: prior ? path : undefined,
+    };
+}
+export async function runBench(opts = {}) {
+    const suite = opts.suite ?? 'code-review';
+    const set = opts.set ?? 'build';
+    const arms = opts.arms ?? [...ARM_IDS];
+    const root = opts.root ?? process.cwd();
+    const handles = opts.handles ?? (await setupProviders());
+    const available = handles.map((h) => h.id);
+    const cases = await loadCases(suite, set, root);
+    const resultsDir = join(root, 'bench', 'results');
+    await mkdir(resultsDir, { recursive: true });
+    const { path, prior } = await resolveCampaign(resultsDir, suite, set, !!opts.resume);
+    const done = opts.resume ? priorScored(prior) : new Map();
+    const result = { suite, set, at: new Date().toISOString(), arms, cases: [], summary: [] };
+    for (const c of cases) {
+        const caseResult = { case: c.name, seeded: c.bugs.length, arms: [] };
+        for (const arm of arms) {
+            const kept = done.get(`${c.name}::${arm}`);
+            if (kept) {
+                caseResult.arms.push(kept); // resume: keep already-scored work across quota windows
+                continue;
+            }
+            if (!armAvailable(arm, available)) {
+                caseResult.arms.push({ arm, status: 'skipped', reason: `required provider(s) unavailable` });
+                continue;
+            }
+            caseResult.arms.push(await runArmOnCase(arm, c, handles, available, root));
+        }
+        // Carry forward prior scored pairs for arms NOT requested this run — else a narrower `--arms`
+        // re-run (e.g. C-only after B,D) would rewrite the campaign file without the paid-for B/D data.
+        const priorCase = prior?.cases.find((pc) => pc.case === c.name);
+        for (const a of priorCase?.arms ?? []) {
+            if (a.status === 'scored' && !arms.includes(a.arm))
+                caseResult.arms.push(a);
+        }
+        result.cases.push(caseResult);
+        result.summary = summarize(result.cases, arms);
+        // Survive a mid-run stop: write processed cases + the prior file's not-yet-reprocessed cases
+        // (a kill mid-loop must not drop prior scored data for later cases from the campaign file).
+        const processed = new Set(result.cases.map((x) => x.case));
+        const pending = (prior?.cases ?? []).filter((pc) => !processed.has(pc.case));
+        await writeIncremental(path, { ...result, cases: [...result.cases, ...pending] });
+    }
+    return result;
+}
+/** Atomic incremental write (temp + rename). */
+async function writeIncremental(path, result) {
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, JSON.stringify(result, null, 2), 'utf8');
+    await rename(tmp, path);
+}
+/** Render the per-arm summary table (recall micro/macro, precision, calls, wall-clock). */
+export function renderTable(result) {
+    const L = [];
+    L.push(`bench ${result.suite} — set ${result.set} — ${result.cases.length} case(s)`);
+    L.push('');
+    L.push('| Arm | Recall (micro) | Recall (macro) | Matched/Seeded | Reported | Unmatched(FP?) | Precision | Calls | Wall(s) |');
+    L.push('|---|---|---|---|---|---|---|---|---|');
+    for (const r of result.summary) {
+        const pct = (n) => `${(n * 100).toFixed(0)}%`;
+        const prec = r.precision === null ? '—' : pct(r.precision);
+        L.push(`| ${r.arm} | ${pct(r.recall)} | ${pct(r.recallMacro)} | ${r.matched}/${r.seeded} | ${r.reported} | ${r.unmatched} | ${prec} | ${r.calls} | ${(r.wallMs / 1000).toFixed(1)} |`);
+    }
+    L.push('');
+    L.push('Precision "—" = not yet adjudicated (label false positives with `aiki resolve <run>`).');
+    return L.join('\n');
+}

package/dist/bench/results.js

@@ -0,0 +1,70 @@
+// Bench result schema (§17, BENCHMARK.md §5, T11). Per-case per-arm scores + a summary, written to
+// bench/results/<suite>-<date>.json. Precision is nullable — it needs FP adjudication (resolve-CR), which
+// happens after the run; recall/calls/wall-clock are automatic. Aggregate recall is MICRO (grill 2026-07-04).
+import { z } from 'zod';
+export const ArmScore = z.object({
+    arm: z.enum(['A', 'B', 'C', 'D', 'E']),
+    status: z.enum(['scored', 'skipped', 'error']),
+    reason: z.string().optional(), // why skipped / the error message
+    runId: z.string().optional(),
+    seeded: z.number().int().nonnegative().optional(),
+    matched: z.number().int().nonnegative().optional(),
+    recall: z.number().optional(),
+    reported: z.number().int().nonnegative().optional(),
+    unmatched: z.number().int().nonnegative().optional(), // candidate FPs, UNADJUDICATED
+    precision: z.number().nullable().optional(), // null until FP-labelled via resolve
+    calls: z.number().int().nonnegative().optional(),
+    wallMs: z.number().nonnegative().optional(),
+});
+export const CaseResult = z.object({
+    case: z.string(),
+    seeded: z.number().int().nonnegative(),
+    arms: z.array(ArmScore),
+});
+/** Per-arm rollup across all cases. `recall` = micro (total matched / total seeded); `recallMacro` = mean of per-case. */
+export const SummaryRow = z.object({
+    arm: z.enum(['A', 'B', 'C', 'D', 'E']),
+    cases: z.number().int().nonnegative(), // scored cases
+    seeded: z.number().int().nonnegative(),
+    matched: z.number().int().nonnegative(),
+    recall: z.number(), // micro
+    recallMacro: z.number(),
+    reported: z.number().int().nonnegative(),
+    unmatched: z.number().int().nonnegative(),
+    precision: z.number().nullable(), // micro precision if any labels, else null
+    calls: z.number().int().nonnegative(),
+    wallMs: z.number().nonnegative(),
+});
+export const BenchResult = z.object({
+    suite: z.string(),
+    set: z.string(),
+    at: z.string(),
+    arms: z.array(z.enum(['A', 'B', 'C', 'D', 'E'])),
+    cases: z.array(CaseResult),
+    summary: z.array(SummaryRow),
+});
+/** Roll per-case arm scores up into the per-arm summary (micro recall, macro shown alongside). */
+export function summarize(cases, arms) {
+    return arms.map((arm) => {
+        const scored = cases.flatMap((c) => c.arms.filter((a) => a.arm === arm && a.status === 'scored'));
+        const sum = (pick) => scored.reduce((s, a) => s + pick(a), 0);
+        const seeded = sum((a) => a.seeded ?? 0);
+        const matched = sum((a) => a.matched ?? 0);
+        const reported = sum((a) => a.reported ?? 0);
+        const recallMacro = scored.length ? scored.reduce((s, a) => s + (a.recall ?? 0), 0) / scored.length : 0;
+        const precisions = scored.map((a) => a.precision).filter((p) => typeof p === 'number');
+        return {
+            arm,
+            cases: scored.length,
+            seeded,
+            matched,
+            recall: seeded ? matched / seeded : 0,
+            recallMacro,
+            reported,
+            unmatched: sum((a) => a.unmatched ?? 0),
+            precision: precisions.length ? precisions.reduce((s, p) => s + p, 0) / precisions.length : null,
+            calls: sum((a) => a.calls ?? 0),
+            wallMs: sum((a) => a.wallMs ?? 0),
+        };
+    });
+}

package/dist/bench/scoring/seeded-bugs.js

@@ -0,0 +1,31 @@
+// Seeded-bug scoring for code-review (§17, BENCHMARK.md §3, T11). A seeded bug is ground truth: a
+// known defect at a file + line range + category. A reported finding counts as FOUND iff it matches on
+// same file + overlapping lines + same category — which is exactly `sameFinding` (the §487 matcher).
+// Recall is fully automatic; precision needs FP adjudication (resolve-CR), so it lives elsewhere.
+import { z } from 'zod';
+import { FindingCategory } from '../../schemas/index.js';
+import { sameFinding } from '../../orchestration/stages/cr-map.js';
+/** One ground-truth seeded bug. `category` is the frozen match key; `class` is a fine, doc-only label. */
+export const SeededBug = z.object({
+    id: z.string().min(1),
+    file: z.string().min(1),
+    line_start: z.number().int().nonnegative(),
+    line_end: z.number().int().nonnegative(),
+    category: FindingCategory,
+    class: z.string().optional(), // "off-by-one" | "race" | ... (documentation only)
+});
+/** The bugs.json in each build case: the seeded defects for its diff. */
+export const BugManifest = z.object({ bugs: z.array(SeededBug) });
+/** Score one arm's findings against a case's seeded bugs (BENCHMARK.md §3). Pure. */
+export function scoreRun(findings, bugs) {
+    const matchedBugIds = bugs.filter((bug) => findings.some((f) => sameFinding(f, bug))).map((b) => b.id);
+    const unmatched = findings.filter((f) => !bugs.some((bug) => sameFinding(f, bug))).length;
+    return {
+        seeded: bugs.length,
+        matched: matchedBugIds.length,
+        recall: bugs.length === 0 ? 0 : matchedBugIds.length / bugs.length,
+        reported: findings.length,
+        unmatched,
+        matchedBugIds,
+    };
+}

package/dist/cli/bench.js

@@ -0,0 +1,50 @@
+// `aiki bench <workflow> [--arms A,B,C,D] [--set build] [--resume] [--yes]` (§5, §17, §19) — run the
+// benchmark arms on a task set, write bench/results/<suite>-<date>.json, print the per-arm summary table.
+// Without --yes it prints a pre-run Opus-call estimate and exits (so a big sweep never silently drains the
+// quota). --resume continues the latest results file, keeping already-scored case×arm pairs.
+import { planBench, renderTable, runBench } from '../bench/harness.js';
+import { setupProviders } from '../orchestration/context.js';
+const VALID_ARMS = ['A', 'B', 'C', 'D', 'E'];
+/** One-block pre-run summary: what will run + the ≈Opus cost, so the user commits knowingly (§19). */
+function renderPlan(plan) {
+    const L = [`bench ${plan.suite} — set ${plan.set} — ${plan.cases.length} case(s) × arms ${plan.arms.join(',')}`];
+    if (plan.resumedFrom)
+        L.push(`resume: continuing ${plan.resumedFrom} — ${plan.skipCompleted} case×arm already scored (kept)`);
+    const unavail = plan.skipUnavailable ? ` · ${plan.skipUnavailable} skipped (provider unavailable)` : '';
+    L.push(`to run: ${plan.toRun.length} case×arm pair(s) → ≈${plan.estClaudeCalls} claude/Opus call(s)${unavail}`);
+    return L.join('\n');
+}
+export async function benchCommand(workflow, opts = {}) {
+    if (workflow !== 'code-review') {
+        process.stderr.write(`bench supports only "code-review" in v1 (got "${workflow}")\n`);
+        return 1;
+    }
+    const arms = (opts.arms ?? 'A,B,C,D')
+        .split(',')
+        .map((s) => s.trim().toUpperCase())
+        .filter((a) => VALID_ARMS.includes(a));
+    if (arms.length === 0) {
+        process.stderr.write(`no valid arms in "${opts.arms}". Valid: A,B,C,D\n`);
+        return 1;
+    }
+    const set = opts.set ?? 'build';
+    const handles = await setupProviders(); // detection only (no model calls); shared by plan + run
+    const plan = await planBench({ suite: 'code-review', set, arms, resume: opts.resume, handles });
+    if (plan.cases.length === 0) {
+        process.stderr.write(`no cases found in bench/sets/code-review/${set}/ — create <name>/{diff.patch,bugs.json} case dirs first\n`);
+        return 1;
+    }
+    process.stdout.write(`\n${renderPlan(plan)}\n`);
+    if (plan.toRun.length === 0) {
+        process.stdout.write(`\nnothing to run — every requested arm is already scored on every case.\n\n`);
+        return 0;
+    }
+    if (!opts.yes) {
+        const resumeHint = opts.resume ? '' : ' (add --resume to continue a partial run across quota windows)';
+        process.stdout.write(`\nThis makes ≈${plan.estClaudeCalls} claude/Opus call(s). Re-run with --yes to execute${resumeHint}.\n\n`);
+        return 0;
+    }
+    const result = await runBench({ suite: 'code-review', set, arms, resume: opts.resume, handles });
+    process.stdout.write(`\n${renderTable(result)}\n\n  results: ${plan.resultsPath}\n\n`);
+    return 0;
+}

package/dist/cli/config.js

@@ -0,0 +1,51 @@
+// `aiki config` (§5/§128) — print the effective config (defaults merged with .aiki/config.json);
+// `--edit` opens .aiki/config.json in $VISUAL/$EDITOR, creating it with `{}` if missing.
+import { spawn } from 'node:child_process';
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ConfigError, effectiveConfig, loadLayeredConfig } from '../config/config.js';
+const ROOT = '.aiki';
+const CONFIG_PATH = join(ROOT, 'config.json');
+/** Open the config file in the user's editor, creating an empty `{}` scaffold first if it's missing. */
+async function editConfig() {
+    await mkdir(ROOT, { recursive: true });
+    try {
+        await access(CONFIG_PATH);
+    }
+    catch {
+        await writeFile(CONFIG_PATH, '{}\n', 'utf8');
+    }
+    const editor = process.env.VISUAL || process.env.EDITOR;
+    if (!editor) {
+        process.stdout.write(`no $VISUAL/$EDITOR set — edit ${CONFIG_PATH} manually.\n`);
+        return 0;
+    }
+    const parts = editor.split(/\s+/);
+    const cmd = parts[0];
+    const args = parts.slice(1);
+    return new Promise((res) => {
+        const child = spawn(cmd, [...args, CONFIG_PATH], { stdio: 'inherit' });
+        child.on('exit', (code) => res(code ?? 0));
+        child.on('error', () => {
+            process.stderr.write(`failed to launch editor "${editor}" — edit ${CONFIG_PATH} manually.\n`);
+            res(1);
+        });
+    });
+}
+export async function config(opts = {}) {
+    if (opts.edit)
+        return editConfig();
+    try {
+        const eff = effectiveConfig(await loadLayeredConfig()); // global ~/.aiki base + this project's .aiki
+        process.stdout.write(`${JSON.stringify(eff, null, 2)}\n`);
+        process.stderr.write('(roles shown are config pins; the actual per-run assignment also depends on which providers are available)\n');
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof ConfigError) {
+            process.stderr.write(`${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+}

package/dist/cli/doctor.js

@@ -0,0 +1,115 @@
+import { DISPLAY_NAME, PROVIDER_IDS } from '../providers/types.js';
+import { detect } from '../providers/detect.js';
+import { probeFlags } from '../providers/probe.js';
+import { smokeTest } from '../providers/smoke.js';
+import { entryToSmoke, isFresh, readSmokeCache, toEntry, writeSmokeCache } from '../config/smoke-cache.js';
+// Default role labels for the status panel (§4.1 / §10). Assignment logic is T5+.
+// NOTE: agy = Gemini 3.1 Pro (strong + metered), not the old cheap/free gemini — §10 role
+// rationale should be revisited at T5.
+const ROLE_LABEL = {
+    claude: 'judge',
+    codex: 'critic/verifier',
+    agy: 'analyst/prompt-builder',
+};
+const READONLY_LABEL = {
+    plan: 'plan',
+    sandbox: 'sandbox',
+    none: '⚠ none',
+};
+const pad = (s, w) => s.padEnd(w);
+/**
+ * `aiki doctor` — detection + flag probe + (optional) smoke test, table output, actionable
+ * fixes. Exit 0 iff ≥2 providers are "ready" (§5, §8 quorum). With smoke on, ready = smoke
+ * passed; with --no-smoke, ready = detected.
+ *
+ * Smoke results are cached 6h in `.aiki/smoke-cache.json` (§242); `--fresh` bypasses the cache.
+ * A cache entry is reused only when its provider version still matches (an upgrade re-smokes).
+ */
+export async function doctor(opts = {}) {
+    const runSmoke = opts.smoke !== false;
+    const cache = runSmoke ? await readSmokeCache() : {};
+    const now = Date.now();
+    const updates = {};
+    const rows = await Promise.all(PROVIDER_IDS.map(async (id) => {
+        const det = await detect(id);
+        if (det.status !== 'READY')
+            return { det };
+        const flags = await probeFlags(id);
+        if (!runSmoke)
+            return { det, flags };
+        const cached = opts.fresh ? undefined : cache[id];
+        if (cached && isFresh(cached, det.version ?? null, now)) {
+            return { det, flags, smoke: entryToSmoke(cached), cached: true };
+        }
+        const smoke = await smokeTest(id, flags);
+        updates[id] = toEntry(smoke, det.version ?? null, new Date(now));
+        return { det, flags, smoke };
+    }));
+    if (Object.keys(updates).length)
+        await writeSmokeCache({ ...cache, ...updates });
+    const lines = [];
+    lines.push('');
+    lines.push(`  aiki doctor — provider status${runSmoke ? '' : ' (smoke skipped)'}`);
+    lines.push('');
+    lines.push(`  ${pad('PROVIDER', 10)}${pad('VERSION', 11)}${pad('STATUS', 15)}${pad('JSON', 6)}${pad('READ-ONLY', 11)}${pad('SMOKE', 14)}ROLE`);
+    lines.push(`  ${'─'.repeat(82)}`);
+    let ready = 0;
+    const fixes = [];
+    for (const row of rows) {
+        lines.push(renderRow(row, runSmoke));
+        if (isReady(row, runSmoke))
+            ready++;
+        fixes.push(...fixLines(row));
+    }
+    lines.push('');
+    lines.push(`  ${ready}/3 providers ready. Engine minimum quorum: 2.`);
+    if (rows.some((r) => r.cached))
+        lines.push('  (smoke: cached ≤6h — `aiki doctor --fresh` re-runs)');
+    if (fixes.length) {
+        lines.push('');
+        lines.push('  Fixes:');
+        lines.push(...fixes);
+    }
+    lines.push('');
+    process.stdout.write(lines.join('\n') + '\n');
+    return ready >= 2 ? 0 : 1;
+}
+function isReady(row, runSmoke) {
+    if (row.det.status !== 'READY')
+        return false;
+    return runSmoke ? row.smoke?.ok === true : true;
+}
+function renderRow(row, runSmoke) {
+    const { det, flags, smoke } = row;
+    const status = det.status === 'READY' ? '✔ ready' : '✖ NOT_INSTALLED';
+    const version = det.version ?? '—';
+    const json = flags ? (flags.jsonOutput ? 'yes' : 'no') : '—';
+    const ro = flags ? READONLY_LABEL[flags.readOnlyFlag] : '—';
+    const smokeCell = renderSmoke(det.status === 'READY', runSmoke, smoke);
+    return `  ${pad(DISPLAY_NAME[det.id], 10)}${pad(version, 11)}${pad(status, 15)}${pad(json, 6)}${pad(ro, 11)}${pad(smokeCell, 14)}${ROLE_LABEL[det.id]}`;
+}
+function renderSmoke(detected, runSmoke, smoke) {
+    if (!detected || !runSmoke)
+        return '—';
+    if (!smoke)
+        return '—';
+    if (smoke.ok)
+        return `✔ ${(smoke.durationMs / 1000).toFixed(1)}s`;
+    return `✖ ${smoke.error ?? 'FAIL'}`;
+}
+function fixLines(row) {
+    const { det, smoke } = row;
+    const name = DISPLAY_NAME[det.id];
+    // Fixes are user-facing (show display name) but reference the real binary for commands.
+    if (det.status !== 'READY' && det.hint)
+        return [`  ${name}: ${det.hint}`];
+    if (smoke && !smoke.ok) {
+        const fix = smoke.error === 'AUTH'
+            ? `run \`${det.id}\` once to log in`
+            : smoke.error === 'QUOTA'
+                ? 'provider quota/rate limited — retry later'
+                : (smoke.detail ?? 'smoke failed');
+        return [`  ${name}: ${fix}`];
+    }
+    return [];
+}