opencode-autoresearch 3.1.0 → 3.3.1

package/dist/cli.js

@@ -1,37 +1,693 @@
 #!/usr/bin/env node
-import { spawn } from "child_process";
-import { fileURLToPath } from "url";
-import { dirname } from "path";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-function runCommand(script, args) {
-    return new Promise((resolve) => {
-        const child = spawn("node", [script, ...args], { stdio: "inherit" });
-        child.on("close", (code) => resolve(code ?? 0));
-    });
-}
-async function main() {
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { resolve } from "path";
+import { printJson, resolveRepo, parseRunState, parsePositiveInt } from "./helpers.js";
+const VERSION_FLAGS = ["--version", "-v"];
+const HELP_FLAGS = ["--help", "-h", "help"];
+const usage = () => {
+    console.error("Usage: autoresearch <command> [options]");
+    console.error("");
+    console.error("Commands:");
+    console.error("  init       Initialize a run");
+    console.error("  wizard     Generate a setup summary");
+    console.error("  status     Print run status");
+    console.error("  explain    Human-readable run state");
+    console.error("  history    Show recent iteration log");
+    console.error("  config     Show runtime configuration");
+    console.error("  summary    Aggregate stats across runs");
+    console.error("  suggest    Suggest next goal from memory");
+    console.error("  launch     Launch a background run");
+    console.error("  complete   Mark a run complete");
+    console.error("  stop       Request a background run stop");
+    console.error("  resume     Resume a background run");
+    console.error("  record     Record an experiment result");
+    console.error("  doctor     Verify package installation and version");
+    console.error("  help       Show this help");
+    console.error("");
+    console.error("Options:");
+    console.error("  --repo          Repository root (default: current directory)");
+    console.error("  --goal          Desired run outcome");
+    console.error("  --metric        Metric name to track");
+    console.error("  --direction     lower or higher");
+    console.error("  --verify        Mechanical verification command");
+    console.error("  --guard         Guard command for regression catch");
+    console.error("  --mode          foreground or background");
+    console.error("  --scope         In-scope files or subsystem");
+    console.error("  --iterations    Iteration cap");
+    console.error("  --duration      Wall-clock cap (e.g., 5h or 300m)");
+    console.error("  --json          Output raw JSON (default: human-readable)");
+    console.error("  --results-path  Custom results TSV path");
+    console.error("  --state-path    Custom state JSON path");
+    console.error("  --fresh-start   Archive previous artifacts before starting");
+    console.error("");
+    console.error("Flags:");
+    console.error("  -h, --help      Show this help");
+    console.error("  -v, --version   Show version");
+    console.error("  --verbose       Enable verbose output");
+    console.error("  --dry-run       Preview changes without executing");
+    console.error("");
+    console.error("Examples:");
+    console.error("  autoresearch wizard --goal \"optimize response time\"");
+    console.error("  autoresearch init --goal \"reduce errors\" --metric errors --direction lower --verify \"npm test\"");
+    console.error("  autoresearch status");
+    console.error("  autoresearch explain");
+    console.error("  autoresearch history");
+};
+const parseArgs = (args) => {
+    const result = {};
+    for (let i = 0; i < args.length; i++) {
+        if (args[i].startsWith("--")) {
+            const key = args[i].slice(2);
+            if (i + 1 < args.length && !args[i + 1].startsWith("--") && !args[i + 1].startsWith("-")) {
+                result[key] = args[++i];
+            }
+            else {
+                result[key] = "true";
+            }
+        }
+        else if (args[i].startsWith("-") && args[i].length === 2 && args[i] !== "--") {
+            const shortToLong = {
+                r: "repo", g: "goal", m: "metric", d: "direction",
+                v: "verify", n: "guard", o: "mode", s: "scope",
+                i: "iterations", t: "duration",
+            };
+            const key = shortToLong[args[i][1]] ?? args[i].slice(1);
+            if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+                result[key] = args[++i];
+            }
+            else {
+                result[key] = "true";
+            }
+        }
+    }
+    return result;
+};
+const formatMetricValue = (val) => {
+    if (val === undefined || val === null)
+        return "—";
+    return String(val);
+};
+const formatTimestamp = (ts) => {
+    try {
+        const d = new Date(ts);
+        return d.toLocaleString();
+    }
+    catch {
+        return ts;
+    }
+};
+const main = async () => {
     const args = process.argv.slice(2);
+    // Handle standalone flags
     if (args.length === 0) {
-        console.error("Usage: autoresearch <command> [options]");
-        console.error("Commands: init, wizard, status, launch, complete, stop, resume, record");
-        return 1;
-    }
-    const [cmd, ...rest] = args;
-    const distDir = __dirname + "/..";
-    switch (cmd) {
-        case "init": return runCommand(distDir + "/dist/init.js", rest);
-        case "wizard": return runCommand(distDir + "/dist/wizard.js", rest);
-        case "status": return runCommand(distDir + "/dist/status.js", rest);
-        case "launch": return runCommand(distDir + "/dist/launch.js", rest);
-        case "complete": return runCommand(distDir + "/dist/complete.js", rest);
-        case "stop": return runCommand(distDir + "/dist/stop.js", rest);
-        case "resume": return runCommand(distDir + "/dist/resume.js", rest);
-        case "record": return runCommand(distDir + "/dist/record.js", rest);
-        default:
-            console.error(`Unknown command: ${cmd}`);
-            return 1;
-    }
-}
+        usage();
+        return 0;
+    }
+    const first = args[0];
+    if (VERSION_FLAGS.includes(first)) {
+        const { VERSION, PACKAGE_NAME, SKILL_NAME } = await import("./constants.js");
+        console.log(`${SKILL_NAME} ${VERSION} (${PACKAGE_NAME})`);
+        console.log("Runtime: Node.js " + process.version);
+        return 0;
+    }
+    if (HELP_FLAGS.includes(first)) {
+        usage();
+        return 0;
+    }
+    const [cmd, ...cmdArgs] = args;
+    const pargs = parseArgs(cmdArgs);
+    const useJson = pargs.json === "true";
+    const verbose = pargs.verbose === "true";
+    const dryRun = pargs["dry-run"] === "true";
+    const grouped = {};
+    for (const [k, v] of Object.entries(pargs)) {
+        if (k === "required-keep-labels" || k === "required-stop-labels" || k === "labels") {
+            grouped[k] = v.split(/\s+/).filter(Boolean);
+        }
+        else {
+            grouped[k] = v;
+        }
+    }
+    try {
+        switch (cmd) {
+            case "wizard": {
+                const { buildSetupSummary } = await import("./wizard.js");
+                const config = {
+                    goal: grouped.goal,
+                    scope: grouped.scope,
+                    metric: grouped.metric,
+                    direction: grouped.direction,
+                    verify: grouped.verify,
+                    guard: grouped.guard,
+                    mode: grouped.mode,
+                    iterations: parsePositiveInt(grouped.iterations, "iterations"),
+                    duration: grouped.duration,
+                    memory_path: grouped["memory-path"],
+                    required_keep_labels: grouped["required-keep-labels"],
+                    required_stop_labels: grouped["required-stop-labels"],
+                    stop_condition: grouped["stop-condition"],
+                    rollback_strategy: grouped["rollback-strategy"],
+                };
+                printJson(buildSetupSummary(grouped.repo, config));
+                break;
+            }
+            case "init": {
+                if (verbose)
+                    console.error(`[verbose] Initializing run with goal: ${grouped.goal}`);
+                if (dryRun) {
+                    console.log("[dry-run] Would initialize run with config:");
+                    console.log(JSON.stringify({
+                        goal: grouped.goal,
+                        metric: grouped.metric,
+                        direction: grouped.direction || "lower",
+                        mode: grouped.mode || "foreground",
+                    }, null, 2));
+                    return 0;
+                }
+                const { initializeRun } = await import("./run-manager.js");
+                const config = {
+                    goal: grouped.goal,
+                    metric: grouped.metric,
+                    direction: grouped.direction || "lower",
+                    verify: grouped.verify,
+                    mode: grouped.mode || "foreground",
+                    scope: grouped.scope,
+                    guard: grouped.guard,
+                    iterations: parsePositiveInt(grouped.iterations, "iterations"),
+                    duration: grouped.duration,
+                    memory_path: grouped["memory-path"],
+                    required_keep_labels: grouped["required-keep-labels"],
+                    required_stop_labels: grouped["required-stop-labels"],
+                    run_tag: grouped["run-tag"],
+                    stop_condition: grouped["stop-condition"],
+                    baseline: grouped.baseline,
+                };
+                const state = await initializeRun(grouped.repo, grouped["results-path"], grouped["state-path"], config, grouped["fresh-start"] === "true");
+                printJson(state);
+                break;
+            }
+            case "status": {
+                const { buildSupervisorSnapshot } = await import("./run-manager.js");
+                const snapshot = await buildSupervisorSnapshot(grouped.repo, grouped["results-path"], grouped["state-path"]);
+                if (useJson) {
+                    printJson(snapshot);
+                }
+                else {
+                    const s = snapshot;
+                    const stats = s.stats;
+                    console.log(`Run:     ${s.run_id}`);
+                    console.log(`Status:  ${s.status}`);
+                    console.log(`Mode:    ${s.mode}`);
+                    console.log(`Goal:    ${s.goal}`);
+                    if (s.metric) {
+                        const m = s.metric;
+                        console.log(`Metric:  ${m.name} (${m.direction})`);
+                        console.log(`  best:  ${formatMetricValue(m.best)}`);
+                        console.log(`  latest: ${formatMetricValue(m.latest)}`);
+                    }
+                    if (stats) {
+                        console.log(`Stats:   ${stats.total_iterations} iterations, ${stats.kept} kept, ${stats.discarded} discarded`);
+                    }
+                    console.log(`Results: ${s.results_rows} rows`);
+                    const lastIter = s.last_iteration;
+                    if (lastIter && lastIter.iteration) {
+                        console.log(`Last:    iter ${lastIter.iteration} — ${lastIter.decision} (${lastIter.metric_value})`);
+                    }
+                    const flags = s.flags;
+                    if (flags?.needs_human)
+                        console.log("⚠  Needs human input");
+                    if (flags?.stop_requested)
+                        console.log("⏹  Stop requested");
+                }
+                break;
+            }
+            case "explain": {
+                const { buildSupervisorSnapshot } = await import("./run-manager.js");
+                const snapshot = await buildSupervisorSnapshot(grouped.repo, grouped["results-path"], grouped["state-path"]);
+                const s = snapshot;
+                const stats = s.stats;
+                const lastIter = s.last_iteration;
+                const flags = s.flags;
+                if (useJson) {
+                    printJson(snapshot);
+                    break;
+                }
+                const statusEmoji = {
+                    running: "🔄", completed: "✅", initialized: "📋", stopping: "⏹", stopped: "⏸",
+                };
+                console.log(`${statusEmoji[s.status] ?? "⚪"} Auto Research Run: ${s.run_id}`);
+                console.log(`   Goal:      ${s.goal ?? "—"}`);
+                console.log(`   Status:    ${s.status}`);
+                console.log(`   Mode:      ${s.mode}`);
+                if (s.metric) {
+                    const m = s.metric;
+                    console.log(`   Metric:    ${m.name} → ${formatMetricValue(m.latest)} (best: ${formatMetricValue(m.best)}, dir: ${m.direction})`);
+                }
+                if (stats) {
+                    console.log(`   Progress:  ${stats.total_iterations} iterations | ${stats.kept} kept | ${stats.discarded} discarded`);
+                }
+                if (lastIter && lastIter.iteration) {
+                    console.log(`   Last iter: #${lastIter.iteration} — ${lastIter.decision}`);
+                    if (lastIter.change_summary)
+                        console.log(`   Change:    ${lastIter.change_summary}`);
+                }
+                if (flags?.needs_human)
+                    console.log("   ⚠  Needs human review");
+                if (flags?.stop_requested)
+                    console.log("   ⏹  Stop was requested");
+                if (flags?.background_active)
+                    console.log("   📡  Background active — `autoresearch status` to check");
+                break;
+            }
+            case "history": {
+                const { resolvePath } = await import("./helpers.js");
+                const { RESULTS_DEFAULT } = await import("./constants.js");
+                const resultsPath = resolvePath(grouped.repo, grouped["results-path"], RESULTS_DEFAULT);
+                if (!existsSync(resultsPath)) {
+                    console.log("No results file found.");
+                    break;
+                }
+                const content = readFileSync(resultsPath, "utf-8");
+                const lines = content.trim().split("\n");
+                if (lines.length <= 1) {
+                    console.log("No iteration records yet.");
+                    break;
+                }
+                const limit = parsePositiveInt(grouped.limit, "limit") ?? 10;
+                const records = lines.slice(1).reverse().slice(0, limit);
+                if (useJson) {
+                    const headers = lines[0].split("\t");
+                    const parsed = records.map((r) => {
+                        const cols = r.split("\t");
+                        const obj = {};
+                        for (let i = 0; i < headers.length; i++) {
+                            obj[headers[i]] = cols[i] ?? "";
+                        }
+                        return obj;
+                    });
+                    printJson({ count: records.length, records: parsed });
+                    break;
+                }
+                for (const r of records) {
+                    const cols = r.split("\t");
+                    if (cols.length >= 8) {
+                        const emoji = cols[2] === "keep" ? "✓" : cols[2] === "discard" ? "✗" : "⚠";
+                        console.log(`${emoji}  #${cols[1]}  ${cols[2]}  (${formatMetricValue(cols[3])})  ${cols[7].substring(0, 60)}`);
+                    }
+                }
+                console.log(`\nShowing ${Math.min(limit, records.length)} of ${lines.length - 1} records.`);
+                break;
+            }
+            case "config": {
+                const { resolvePath, readJsonFile } = await import("./helpers.js");
+                const { STATE_DEFAULT } = await import("./constants.js");
+                const statePath = resolvePath(grouped.repo, grouped["state-path"], STATE_DEFAULT);
+                if (!existsSync(statePath)) {
+                    console.log("No run state found. Run 'autoresearch init' first.");
+                    break;
+                }
+                const state = parseRunState(readJsonFile(statePath));
+                if (useJson) {
+                    printJson({
+                        goal: state.goal,
+                        mode: state.mode,
+                        metric: state.metric,
+                        scope: state.scope,
+                        iterations_cap: state.iterations_cap,
+                        deadline_at: state.deadline_at,
+                        verify: state.verify,
+                        guard: state.guard,
+                        subagent_pool: state.subagent_pool ? "configured" : "none",
+                        label_requirements: state.label_requirements,
+                    });
+                    break;
+                }
+                console.log("Run Configuration:");
+                console.log(`  Goal:     ${state.goal ?? "—"}`);
+                console.log(`  Mode:     ${state.mode ?? "—"}`);
+                if (state.metric) {
+                    const m = state.metric;
+                    console.log(`  Metric:   ${m.name} (${m.direction})`);
+                }
+                console.log(`  Scope:    ${state.scope ?? "—"}`);
+                console.log(`  Iter cap: ${state.iterations_cap ?? "—"}`);
+                console.log(`  Deadline: ${state.deadline_at ? formatTimestamp(state.deadline_at) : "—"}`);
+                console.log(`  Verify:   ${state.verify ?? "—"}`);
+                console.log(`  Guard:    ${state.guard ?? "—"}`);
+                console.log(`  Pool:     ${state.subagent_pool ? "configured" : "none"}`);
+                break;
+            }
+            case "summary": {
+                const { resolvePath } = await import("./helpers.js");
+                const { RESULTS_DEFAULT } = await import("./constants.js");
+                const resultsPath = resolvePath(grouped.repo, grouped["results-path"], RESULTS_DEFAULT);
+                if (!existsSync(resultsPath)) {
+                    console.log("No results file found. No runs completed yet.");
+                    break;
+                }
+                const content = readFileSync(resultsPath, "utf-8");
+                const lines = content.trim().split("\n");
+                const records = lines.slice(1).filter(Boolean);
+                let totalKept = 0, totalDiscarded = 0, totalNeedsHuman = 0;
+                const runIds = new Set();
+                for (const r of records) {
+                    const cols = r.split("\t");
+                    const dec = cols[2];
+                    if (dec === "keep")
+                        totalKept++;
+                    else if (dec === "discard")
+                        totalDiscarded++;
+                    else if (dec === "needs_human")
+                        totalNeedsHuman++;
+                    const iterTags = cols[1].split(":");
+                    if (iterTags.length >= 2)
+                        runIds.add(iterTags[0]);
+                }
+                if (useJson) {
+                    printJson({
+                        total_records: records.length,
+                        total_kept: totalKept,
+                        total_discarded: totalDiscarded,
+                        total_needs_human: totalNeedsHuman,
+                        keep_rate: records.length > 0 ? (totalKept / records.length * 100).toFixed(1) + "%" : "0%",
+                        distinct_run_ids: Array.from(runIds),
+                    });
+                    break;
+                }
+                console.log("Auto Research Summary");
+                console.log(`  Total iterations:   ${records.length}`);
+                console.log(`  Kept:               ${totalKept}`);
+                console.log(`  Discarded:          ${totalDiscarded}`);
+                console.log(`  Needs human:        ${totalNeedsHuman}`);
+                console.log(`  Keep rate:          ${records.length > 0 ? (totalKept / records.length * 100).toFixed(1) : 0}%`);
+                console.log(`  Distinct runs:      ${runIds.size}`);
+                break;
+            }
+            case "validate": {
+                const { normalizeDirection, normalizeMode, inferVerifyCommand } = await import("./helpers.js");
+                const errors = [];
+                if (!grouped.goal)
+                    errors.push("Missing required: --goal");
+                if (!grouped.metric)
+                    errors.push("Missing required: --metric");
+                try {
+                    if (grouped.direction)
+                        normalizeDirection(grouped.direction);
+                }
+                catch (e) {
+                    errors.push(`Invalid direction: ${e.message}`);
+                }
+                try {
+                    if (grouped.mode)
+                        normalizeMode(grouped.mode);
+                }
+                catch (e) {
+                    errors.push(`Invalid mode: ${e.message}`);
+                }
+                const verify = grouped.verify || inferVerifyCommand(grouped.repo);
+                if (verify === "<set verify command>") {
+                    errors.push("Cannot infer verify command. Provide --verify explicitly.");
+                }
+                if (useJson) {
+                    printJson({ valid: errors.length === 0, errors });
+                    return errors.length > 0 ? 1 : 0;
+                }
+                if (errors.length === 0) {
+                    console.log("✓ Configuration is valid");
+                    console.log(`  Goal: ${grouped.goal}`);
+                    console.log(`  Metric: ${grouped.metric} (${grouped.direction || "lower"})`);
+                    console.log(`  Verify: ${verify}`);
+                    console.log(`  Mode: ${grouped.mode || "foreground"}`);
+                }
+                else {
+                    console.error("✗ Configuration errors:");
+                    for (const err of errors) {
+                        console.error(`  - ${err}`);
+                    }
+                    return 1;
+                }
+                break;
+            }
+            case "report": {
+                const { resolvePath, readJsonFile } = await import("./helpers.js");
+                const { STATE_DEFAULT, RESULTS_DEFAULT } = await import("./constants.js");
+                const statePath = resolvePath(grouped.repo, grouped["state-path"], STATE_DEFAULT);
+                const resultsPath = resolvePath(grouped.repo, grouped["results-path"], RESULTS_DEFAULT);
+                if (!existsSync(statePath)) {
+                    console.log("No run state found. Run 'autoresearch init' first.");
+                    break;
+                }
+                const state = parseRunState(readJsonFile(statePath));
+                let results = [];
+                if (existsSync(resultsPath)) {
+                    const content = readFileSync(resultsPath, "utf-8");
+                    results = content.trim().split("\n").slice(1).filter(Boolean);
+                }
+                if (useJson) {
+                    printJson({ state, results_count: results.length });
+                    break;
+                }
+                console.log(`# Auto Research Report`);
+                console.log(`\n**Run:** ${state.run_id}`);
+                console.log(`**Goal:** ${state.goal}`);
+                console.log(`**Status:** ${state.status}`);
+                console.log(`**Mode:** ${state.mode}`);
+                if (state.metric) {
+                    const m = state.metric;
+                    console.log(`**Metric:** ${m.name} (${m.direction})`);
+                    console.log(`**Best:** ${m.best} | **Latest:** ${m.latest}`);
+                }
+                if (state.stats) {
+                    const s = state.stats;
+                    console.log(`\n## Stats`);
+                    console.log(`- Iterations: ${s.total_iterations}`);
+                    console.log(`- Kept: ${s.kept}`);
+                    console.log(`- Discarded: ${s.discarded}`);
+                    console.log(`- Needs human: ${s.needs_human}`);
+                }
+                if (results.length > 0) {
+                    console.log(`\n## Iterations`);
+                    for (const r of results) {
+                        const cols = r.split("\t");
+                        if (cols.length >= 8) {
+                            console.log(`- ${cols[1]}: ${cols[2]} (${cols[3]}) — ${cols[7].substring(0, 60)}`);
+                        }
+                    }
+                }
+                break;
+            }
+            case "suggest": {
+                const { resolvePath } = await import("./helpers.js");
+                const { MEMORY_DEFAULT } = await import("./constants.js");
+                const memoryPath = resolvePath(grouped.repo, grouped["memory-path"], MEMORY_DEFAULT);
+                if (!existsSync(memoryPath)) {
+                    console.log("No memory file found. Run a self-improvement cycle first.");
+                    break;
+                }
+                const memory = readFileSync(memoryPath, "utf-8");
+                const patterns = memory.match(/### Pattern: [^\n]+/g) ?? [];
+                if (useJson) {
+                    printJson({ patterns_found: patterns.length, suggestions: patterns.map((p) => p.replace("### Pattern: ", "")) });
+                    break;
+                }
+                console.log("Memory Patterns — candidate next goals:");
+                for (const p of patterns) {
+                    console.log(`  → ${p.replace("### Pattern: ", "")}`);
+                }
+                console.log(`\n${patterns.length} patterns available. Use 'autoresearch init --goal "..."' to start a new run.`);
+                break;
+            }
+            case "export": {
+                const { resolvePath } = await import("./helpers.js");
+                const { RESULTS_DEFAULT, STATE_DEFAULT } = await import("./constants.js");
+                const resultsPath = resolvePath(grouped.repo, grouped["results-path"], RESULTS_DEFAULT);
+                const statePath = resolvePath(grouped.repo, grouped["state-path"], STATE_DEFAULT);
+                const format = grouped.format || "json";
+                if (!existsSync(resultsPath) || !existsSync(statePath)) {
+                    console.error("No run data found. Run 'autoresearch init' first.");
+                    return 1;
+                }
+                const results = readFileSync(resultsPath, "utf-8");
+                const state = readFileSync(statePath, "utf-8");
+                const lines = results.trim().split("\n");
+                const headers = lines[0].split("\t");
+                const records = lines.slice(1).filter(Boolean).map((r) => {
+                    const cols = r.split("\t");
+                    const obj = {};
+                    for (let i = 0; i < headers.length; i++) {
+                        obj[headers[i]] = cols[i] ?? "";
+                    }
+                    return obj;
+                });
+                const exportData = {
+                    exported_at: new Date().toISOString(),
+                    state: JSON.parse(state),
+                    iterations: records,
+                    summary: {
+                        total: records.length,
+                        kept: records.filter((r) => r.decision === "keep").length,
+                        discarded: records.filter((r) => r.decision === "discard").length,
+                    },
+                };
+                if (format === "json") {
+                    console.log(JSON.stringify(exportData, null, 2));
+                }
+                else if (format === "md" || format === "markdown") {
+                    console.log(`# Auto Research Export`);
+                    console.log(`\n**Run:** ${exportData.state.run_id}`);
+                    console.log(`**Goal:** ${exportData.state.goal}`);
+                    console.log(`**Exported:** ${exportData.exported_at}`);
+                    console.log(`\n## Summary`);
+                    console.log(`- Total iterations: ${exportData.summary.total}`);
+                    console.log(`- Kept: ${exportData.summary.kept}`);
+                    console.log(`- Discarded: ${exportData.summary.discarded}`);
+                    console.log(`\n## Iterations`);
+                    console.log(`| # | Decision | Metric | Summary |`);
+                    console.log(`|---|----------|--------|---------|`);
+                    for (const r of records) {
+                        console.log(`| ${r.iteration} | ${r.decision} | ${r.metric_value || "—"} | ${r.change_summary?.substring(0, 50) || "—"} |`);
+                    }
+                }
+                else {
+                    console.error(`Unknown format: ${format}. Supported: json, md`);
+                    return 1;
+                }
+                break;
+            }
+            case "completion": {
+                const shell = grouped.shell || "bash";
+                const commands = ["init", "wizard", "status", "explain", "history", "config", "summary", "suggest", "launch", "complete", "stop", "resume", "record", "doctor", "export", "completion", "help"];
+                const options = ["--repo", "--goal", "--metric", "--direction", "--verify", "--guard", "--mode", "--scope", "--iterations", "--duration", "--json", "--results-path", "--state-path", "--fresh-start", "--memory-path", "--format", "--shell"];
+                if (shell === "bash" || shell === "zsh") {
+                    console.log(`# Auto Research CLI completion for ${shell}`);
+                    console.log(`_autoresearch() {`);
+                    console.log(`  local cur="\${COMP_WORDS[COMP_CWORD]}"`);
+                    console.log(`  local cmds="${commands.join(" ")}"`);
+                    console.log(`  local opts="${options.join(" ")}"`);
+                    console.log(`  if [ $COMP_CWORD -eq 1 ]; then`);
+                    console.log(`    COMPREPLY=($(compgen -W "$cmds" -- "$cur"))`);
+                    console.log(`  else`);
+                    console.log(`    COMPREPLY=($(compgen -W "$opts" -- "$cur"))`);
+                    console.log(`  fi`);
+                    console.log(`}`);
+                    console.log(`complete -F _autoresearch autoresearch`);
+                }
+                else if (shell === "fish") {
+                    console.log(`# Auto Research CLI completion for fish`);
+                    for (const cmd of commands) {
+                        console.log(`complete -c autoresearch -n '__fish_use_subcommand' -a '${cmd}'`);
+                    }
+                    for (const opt of options) {
+                        console.log(`complete -c autoresearch -n '__fish_seen_subcommand_from ${commands.join(" ")}' -l ${opt.slice(2)}`);
+                    }
+                }
+                else {
+                    console.error(`Unknown shell: ${shell}. Supported: bash, zsh, fish`);
+                    return 1;
+                }
+                break;
+            }
+            case "launch": {
+                const { resolvePath } = await import("./helpers.js");
+                const { initializeRun } = await import("./run-manager.js");
+                const { writeFileSync } = await import("fs");
+                const { LAUNCH_DEFAULT } = await import("./constants.js");
+                const config = {
+                    goal: grouped.goal,
+                    metric: grouped.metric,
+                    direction: grouped.direction || "lower",
+                    verify: grouped.verify,
+                    mode: "background",
+                    scope: grouped.scope,
+                    guard: grouped.guard,
+                    iterations: parsePositiveInt(grouped.iterations, "iterations"),
+                    duration: grouped.duration,
+                    memory_path: grouped["memory-path"],
+                    required_keep_labels: grouped["required-keep-labels"],
+                    required_stop_labels: grouped["required-stop-labels"],
+                    run_tag: grouped["run-tag"],
+                    stop_condition: grouped["stop-condition"],
+                    baseline: grouped.baseline,
+                };
+                const state = await initializeRun(grouped.repo, grouped["results-path"], grouped["state-path"], config, grouped["fresh-start"] === "true");
+                const launchPath = resolvePath(grouped.repo, grouped["launch-path"], LAUNCH_DEFAULT);
+                writeFileSync(launchPath, JSON.stringify({ run_id: state.run_id, goal: state.goal, mode: "background" }, null, 2) + "\n", "utf-8");
+                printJson({ status: "launched", run_id: state.run_id, launch_path: launchPath });
+                break;
+            }
+            case "complete": {
+                const { completeRun } = await import("./run-manager.js");
+                const state = await completeRun(grouped.repo, grouped["state-path"]);
+                printJson({ status: "completed", run_id: state.run_id });
+                break;
+            }
+            case "stop": {
+                const { setStopRequested } = await import("./run-manager.js");
+                const state = await setStopRequested(grouped.repo, grouped["state-path"]);
+                printJson({ status: "stop_requested", run_id: state.run_id });
+                break;
+            }
+            case "resume": {
+                const { resumeBackgroundRun } = await import("./run-manager.js");
+                const state = await resumeBackgroundRun(grouped.repo, grouped["state-path"]);
+                printJson({ status: "resumed", run_id: state.run_id });
+                break;
+            }
+            case "record": {
+                const { appendIteration } = await import("./run-manager.js");
+                const { normalizeResultStatus } = await import("./helpers.js");
+                const vs = grouped["verify-status"] || "pass";
+                const gs = grouped["guard-status"] || "skip";
+                const state = await appendIteration(grouped.repo, grouped["results-path"], grouped["state-path"], grouped.decision, grouped["metric-value"], normalizeResultStatus(vs, "verify_status"), normalizeResultStatus(gs, "guard_status"), grouped.hypothesis, grouped["change-summary"], grouped.labels ? (Array.isArray(grouped.labels) ? grouped.labels : [grouped.labels]) : undefined, grouped.note, parsePositiveInt(grouped.iteration, "iteration"));
+                printJson(state);
+                break;
+            }
+            case "doctor": {
+                const { VERSION, PACKAGE_NAME, SKILL_NAME } = await import("./constants.js");
+                console.log(`${SKILL_NAME} ${VERSION} (${PACKAGE_NAME})`);
+                console.log("Runtime: Node.js " + process.version);
+                const base = resolveRepo(grouped.repo);
+                const checks = [];
+                const cmdDir = resolve(base, "commands");
+                const skillsDir = resolve(base, "skills/autoresearch");
+                const hooksDir = resolve(base, "hooks");
+                const cmdFiles = existsSync(cmdDir) ? readdirSync(cmdDir).filter((f) => f.endsWith(".md")) : [];
+                const skillFiles = existsSync(skillsDir) ? readdirSync(skillsDir) : [];
+                const hookFiles = existsSync(hooksDir) ? readdirSync(hooksDir).filter((f) => f.endsWith(".sh")) : [];
+                checks.push({ name: "commands", ok: cmdFiles.length > 0, detail: `${cmdFiles.length} command files` });
+                checks.push({ name: "skills", ok: skillFiles.length > 0, detail: `${skillFiles.length} skill files` });
+                checks.push({ name: "hooks", ok: hookFiles.length > 0, detail: `${hookFiles.length} hook scripts` });
+                checks.push({ name: "dist", ok: existsSync(resolve(base, "dist/cli.js")), detail: "dist/cli.js" });
+                checks.push({ name: "plugin", ok: existsSync(resolve(base, ".opencode-plugin/plugin.json")), detail: "plugin manifest" });
+                checks.push({ name: "VERSION", ok: existsSync(resolve(base, "VERSION")), detail: "version marker" });
+                let maxNameLen = 0;
+                for (const c of checks)
+                    maxNameLen = Math.max(maxNameLen, c.name.length);
+                for (const c of checks) {
+                    const padded = c.name.padEnd(maxNameLen + 2);
+                    console.log(`  ${c.ok ? "✓" : "✗"} ${padded}${c.detail ?? (c.ok ? "present" : "missing")}`);
+                }
+                const failed = checks.filter((c) => !c.ok).length;
+                if (failed > 0) {
+                    console.error(`\n${failed} check(s) failed. Reinstall with 'npm install -g opencode-autoresearch'.`);
+                    return 1;
+                }
+                console.log(`\nAll ${checks.length} checks passed.`);
+                break;
+            }
+            default: {
+                console.error(`Unknown command: ${cmd}`);
+                console.error("Run 'autoresearch --help' for usage.");
+                return 1;
+            }
+        }
+    }
+    catch (exc) {
+        console.error(exc.message);
+        return 2;
+    }
+    return 0;
+};
 main().then((code) => process.exit(code)).catch((err) => {
     console.error(err);
     process.exit(1);