opencode-autoresearch 3.13.2 → 3.14.1

package/dist/cli.js

@@ -1,12 +1,27 @@
 #!/usr/bin/env node
-import { closeSync, existsSync, fstatSync, openSync, readFileSync, readSync, readdirSync } from "fs";
+import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, readdirSync } from "fs";
 import { resolve } from "path";
 import { execSync } from "child_process";
 import { MAX_DRAFTS } from "./constants.js";
-import { printJson, resolveRepo, parseRunState, parsePositiveInt, sanitizeForTerminal, getInstalledPackagePath, getInstalledPackageInfo, readUpdateCache, getGlobalNpmPrefix, readGoalDoc, atomicWriteTextInRepo } from "./helpers.js";
+import { printJson, printJsonEnvelope, resolveRepo, parseRunState, parsePositiveInt, sanitizeForTerminal, getInstalledPackagePath, getInstalledPackageInfo, readUpdateCache, getGlobalNpmPrefix, readGoalDoc, atomicWriteTextInRepo } from "./helpers.js";
 const VERSION_FLAGS = ["--version", "-v"];
 const HELP_FLAGS = ["--help", "-h", "help"];
 const BRANCH_POLICIES = ["best", "roulette", "diverse"];
+const shouldSkipUpdateCheck = (args) => {
+    if (args.length > 0 && VERSION_FLAGS.includes(args[0])) {
+        return { skip: true, reason: "version_flag" };
+    }
+    if (args.length > 0 && HELP_FLAGS.includes(args[0])) {
+        return { skip: true, reason: "help_flag" };
+    }
+    if (process.env.AUTORESEARCH_NO_UPDATE === "1") {
+        return { skip: true, reason: "env_opt_out" };
+    }
+    if (process.env.CI === "true" || process.env.CI === "1") {
+        return { skip: true, reason: "ci_environment" };
+    }
+    return { skip: false, reason: null };
+};
 const usage = () => {
     console.error("Usage: autoresearch <command> [options]");
     console.error("");
@@ -22,6 +37,7 @@ const usage = () => {
     console.error("  score      Run the configured scorer and show normalized output");
     console.error("  digest     Generate re-entry digest for operator handoff");
     console.error("  config     Show runtime configuration");
+    console.error("  contract   Print runtime contract schemas");
     console.error("  summary    Aggregate stats across runs");
     console.error("  suggest    Suggest next goal from memory");
     console.error("  launch     Launch a background run");
@@ -29,6 +45,9 @@ const usage = () => {
     console.error("  stop       Request a background run stop");
     console.error("  resume     Resume a background run");
     console.error("  record     Record an experiment result");
+    console.error("  queue      Manage background task queue");
+    console.error("  pack       Export and inspect strategy packs");
+    console.error("  leaderboard Show local leaderboard across runs");
     console.error("  doctor     Verify package installation and version");
     console.error("  help       Show this help");
     console.error("");
@@ -55,6 +74,7 @@ const usage = () => {
     console.error("  --duration      Wall-clock cap (e.g., 5h or 300m)");
     console.error(`  --num-drafts    Number of parallel drafts (default: 1, max: ${MAX_DRAFTS})`);
     console.error("  --branch-policy Branch selection policy: best, roulette, diverse");
+    console.error('  --branch-policy-overrides JSON object mapping draft IDs to policies (e.g. {"draft-0":"diverse"})');
     console.error("  --max-debug-depth   Max debug experiment depth before stop");
     console.error("  --branch-failure-budget  Per-branch failure budget before stop");
     console.error("  --json          Output raw JSON (default: human-readable)");
@@ -84,7 +104,13 @@ const parseArgs = (args) => {
     const result = {};
     for (let i = 0; i < args.length; i++) {
         if (args[i].startsWith("--")) {
-            const key = args[i].slice(2);
+            const longArg = args[i];
+            const equalsIndex = longArg.indexOf("=");
+            if (equalsIndex > 2) {
+                result[longArg.slice(2, equalsIndex)] = longArg.slice(equalsIndex + 1);
+                continue;
+            }
+            const key = longArg.slice(2);
             if (i + 1 < args.length && !args[i + 1].startsWith("--") && !args[i + 1].startsWith("-")) {
                 result[key] = args[++i];
             }
@@ -183,6 +209,39 @@ const formatTimestamp = (ts) => {
         return ts;
     }
 };
+const MAX_SCORE_HISTORY_BYTES = 10 * 1024 * 1024;
+const assertRegularBoundedFile = (filePath) => {
+    const linkStats = lstatSync(filePath);
+    if (linkStats.isSymbolicLink()) {
+        throw new Error(`Refusing to read score history symlink: ${filePath}`);
+    }
+    if (!linkStats.isFile()) {
+        throw new Error(`Refusing to read non-regular score history file: ${filePath}`);
+    }
+    if (linkStats.size > MAX_SCORE_HISTORY_BYTES) {
+        throw new Error(`Score history is too large to read safely (${linkStats.size} bytes; max ${MAX_SCORE_HISTORY_BYTES} bytes): ${filePath}`);
+    }
+};
+const readScoreHistoryFile = (filePath) => {
+    assertRegularBoundedFile(filePath);
+    if (typeof fsConstants.O_NOFOLLOW !== "number") {
+        throw new Error(`Refusing to read score history because this platform does not support O_NOFOLLOW: ${filePath}`);
+    }
+    const fd = openSync(filePath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    try {
+        const fileStats = fstatSync(fd);
+        if (!fileStats.isFile()) {
+            throw new Error(`Refusing to read non-regular score history file: ${filePath}`);
+        }
+        if (fileStats.size > MAX_SCORE_HISTORY_BYTES) {
+            throw new Error(`Score history is too large to read safely (${fileStats.size} bytes; max ${MAX_SCORE_HISTORY_BYTES} bytes): ${filePath}`);
+        }
+        return readFileSync(fd, "utf-8");
+    }
+    finally {
+        closeSync(fd);
+    }
+};
 const readTailLines = (filePath, limit) => {
     if (limit <= 0)
         return [];
@@ -245,6 +304,41 @@ const normalizeBranchPolicy = (value) => {
         return value;
     throw new Error(`Invalid branch policy: ${value}. Expected one of: ${BRANCH_POLICIES.join(", ")}`);
 };
+const PROTO_POISON_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+const normalizeOverrideBranchPolicy = (branchId, value) => {
+    const trimmed = value.trim();
+    if (trimmed === "") {
+        throw new Error(`Invalid branch policy override for ${branchId}: value must not be empty`);
+    }
+    if (BRANCH_POLICIES.includes(trimmed))
+        return trimmed;
+    throw new Error(`Invalid branch policy override for ${branchId}: "${trimmed}" is not one of: ${BRANCH_POLICIES.join(", ")}`);
+};
+const parseBranchPolicyOverrides = (value) => {
+    if (value == null || value === "")
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error("Invalid branch policy overrides: expected a JSON object mapping draft IDs to branch policies");
+    }
+    if (parsed == null || Array.isArray(parsed) || typeof parsed !== "object") {
+        throw new Error("Invalid branch policy overrides: expected a JSON object mapping draft IDs to branch policies");
+    }
+    const overrides = Object.create(null);
+    for (const [branchId, branchPolicy] of Object.entries(parsed)) {
+        if (PROTO_POISON_KEYS.has(branchId)) {
+            throw new Error(`Invalid branch policy override key: "${branchId}" is not a valid draft ID`);
+        }
+        if (typeof branchPolicy !== "string") {
+            throw new Error(`Invalid branch policy override for ${branchId}: expected a string policy`);
+        }
+        overrides[branchId] = normalizeOverrideBranchPolicy(branchId, branchPolicy);
+    }
+    return overrides;
+};
 const main = async () => {
     const args = process.argv.slice(2);
     // Handle standalone flags
@@ -298,7 +392,7 @@ const main = async () => {
                     stop_condition: grouped["stop-condition"],
                     rollback_strategy: grouped["rollback-strategy"],
                 };
-                printJson(buildSetupSummary(grouped.repo, config));
+                printJsonEnvelope("wizard", buildSetupSummary(grouped.repo, config));
                 break;
             }
             case "init": {
@@ -335,6 +429,7 @@ const main = async () => {
                     baseline: grouped.baseline,
                     num_drafts: parsePositiveInt(grouped["num-drafts"], "num_drafts", { max: MAX_DRAFTS }) ?? 1,
                     branch_selection_policy: normalizeBranchPolicy(grouped["branch-policy"]),
+                    branch_policy_overrides: parseBranchPolicyOverrides(grouped["branch-policy-overrides"]),
                     outcome_metric: grouped["outcome-metric"],
                     outcome_direction: grouped["outcome-direction"],
                     instrument_metric: grouped["instrument-metric"],
@@ -350,7 +445,7 @@ const main = async () => {
                 const { buildSupervisorSnapshot } = await import("./run-manager.js");
                 const snapshot = await buildSupervisorSnapshot(grouped.repo, grouped["results-path"], grouped["state-path"]);
                 if (useJson) {
-                    printJson(snapshot);
+                    printJsonEnvelope("status", snapshot);
                 }
                 else {
                     const s = snapshot;
@@ -372,7 +467,8 @@ const main = async () => {
                     console.log(`Results: ${s.results_rows} rows`);
                     const lastIter = s.last_iteration;
                     if (lastIter && lastIter.iteration) {
-                        console.log(`Last:    iter ${formatDisplayValue(lastIter.iteration)} — ${formatDisplayValue(lastIter.decision)} (${formatMetricValue(lastIter.metric_value)})`);
+                        const stageTag = lastIter.stage ? ` [${lastIter.stage}]` : "";
+                        console.log(`Last:    iter ${formatDisplayValue(lastIter.iteration)}${stageTag} — ${formatDisplayValue(lastIter.decision)} (${formatMetricValue(lastIter.metric_value)})`);
                         if (lastIter.score_components != null && typeof lastIter.score_components === "object") {
                             const parts = Object.entries(lastIter.score_components)
                                 .map(([k, v]) => `${formatDisplayValue(k)}:${typeof v === "number" ? v.toFixed(4) : formatDisplayValue(v)}`)
@@ -380,12 +476,21 @@ const main = async () => {
                             if (parts.length > 0)
                                 console.log(`  Components: [${parts}]`);
                         }
+                        if (lastIter.selected_action)
+                            console.log(`  Action:   ${formatDisplayValue(lastIter.selected_action)}`);
                     }
                     const flags = s.flags;
                     if (flags?.needs_human)
                         console.log("⚠  Needs human input");
                     if (flags?.stop_requested)
                         console.log("⏹  Stop requested");
+                    if (flags?.context_pressure) {
+                        const cp = flags.context_pressure;
+                        if (cp.warnings.length > 0) {
+                            for (const w of cp.warnings)
+                                console.log(`🆘 Context pressure: ${w}`);
+                        }
+                    }
                 }
                 break;
             }
@@ -397,7 +502,7 @@ const main = async () => {
                 const lastIter = s.last_iteration;
                 const flags = s.flags;
                 if (useJson) {
-                    printJson(snapshot);
+                    printJsonEnvelope("explain", snapshot);
                     break;
                 }
                 const statusEmoji = {
@@ -466,7 +571,7 @@ const main = async () => {
                         }
                         return obj;
                     });
-                    printJson({ count: records.length, records: parsed });
+                    printJsonEnvelope("history", { count: records.length, records: parsed });
                     break;
                 }
                 for (const r of records) {
@@ -493,7 +598,7 @@ const main = async () => {
                 const limit = parsePositiveInt(grouped.limit, "limit") ?? 10;
                 const showTopComponents = grouped["top-components"] === "true";
                 if (showTopComponents) {
-                    const allLines = readFileSync(scoreHistoryPath, "utf-8")
+                    const allLines = readScoreHistoryFile(scoreHistoryPath)
                         .split("\n")
                         .map((l) => l.trim())
                         .filter(Boolean);
@@ -512,7 +617,7 @@ const main = async () => {
                     const { rankComponents } = await import("./score-parser.js");
                     const ranking = rankComponents(allParsed);
                     if (useJson) {
-                        printJson({ count: allParsed.length, scores: allParsed.slice(-limit), ranking });
+                        printJsonEnvelope("scores", { count: allParsed.length, scores: allParsed.slice(-limit), ranking });
                         break;
                     }
                     console.log("Component Rankings:");
@@ -548,7 +653,7 @@ const main = async () => {
                             return null;
                         }
                     }).filter(Boolean);
-                    printJson({ count: parsed.length, scores: parsed });
+                    printJsonEnvelope("scores", { count: parsed.length, scores: parsed });
                     break;
                 }
                 console.log("Score History (latest " + Math.min(limit, records.length) + "):");
@@ -651,7 +756,7 @@ const main = async () => {
                 const normalized = scored.score / scored.max;
                 const percent = (normalized * 100).toFixed(1) + "%";
                 if (useJson) {
-                    printJson({
+                    printJsonEnvelope("score", {
                         score: scored.score,
                         max: scored.max,
                         normalized,
@@ -687,7 +792,7 @@ const main = async () => {
                 }
                 const state = parseRunState(readJsonFile(statePath));
                 if (useJson) {
-                    printJson({
+                    printJsonEnvelope("config", {
                         goal: state.goal,
                         mode: state.mode,
                         metric: state.metric,
@@ -719,6 +824,148 @@ const main = async () => {
                 console.log(`  Pool:     ${state.subagent_pool ? "configured" : "none"}`);
                 break;
             }
+            case "contract": {
+                const schemas = {
+                    schema_version: "1.0.0",
+                    description: "Auto Research runtime contract schemas",
+                    state: {
+                        type: "object",
+                        required: ["schema_version", "run_id", "created_at", "updated_at", "status", "mode", "operating_mode", "goal", "scope", "metric", "verify", "label_requirements", "artifact_paths", "stats", "flags"],
+                        properties: {
+                            schema_version: { type: "number", description: "State schema version" },
+                            run_id: { type: "string", description: "Unique run identifier" },
+                            created_at: { type: "string", format: "date-time", description: "Run creation timestamp" },
+                            updated_at: { type: "string", format: "date-time", description: "Last update timestamp" },
+                            status: { type: "string", enum: ["initialized", "running", "stopping", "stopped", "completed", "needs_human"], description: "Run status" },
+                            mode: { type: "string", enum: ["foreground", "background"], description: "Execution mode" },
+                            operating_mode: { type: "string", enum: ["converge", "continuous", "supervised"], description: "Operating mode" },
+                            goal: { type: "string", description: "Run goal description" },
+                            scope: { type: "string", description: "Target scope" },
+                            metric: {
+                                type: "object",
+                                required: ["name", "direction"],
+                                properties: {
+                                    name: { type: "string" },
+                                    direction: { type: "string", enum: ["higher", "lower"] },
+                                    baseline: { type: "string" },
+                                    best: { type: "string" },
+                                    latest: { type: "string" },
+                                },
+                            },
+                            instrument_metric: { type: "object", description: "Optional secondary metric" },
+                            verify: { type: "string", description: "Verification command" },
+                            guard: { type: "string", description: "Guard command" },
+                            scorer: { type: "string", description: "Scorer command" },
+                            iterations_cap: { type: "number", description: "Maximum iterations" },
+                            duration: { type: "string", description: "Duration limit" },
+                            duration_seconds: { type: "number" },
+                            deadline_at: { type: "string", format: "date-time" },
+                            label_requirements: {
+                                type: "object",
+                                required: ["keep", "stop"],
+                                properties: {
+                                    keep: { type: "array", items: { type: "string" } },
+                                    stop: { type: "array", items: { type: "string" } },
+                                },
+                            },
+                            artifact_paths: {
+                                type: "object",
+                                required: ["results", "state"],
+                                properties: {
+                                    results: { type: "string" },
+                                    state: { type: "string" },
+                                },
+                            },
+                            stats: {
+                                type: "object",
+                                required: ["total_iterations", "kept", "discarded", "needs_human"],
+                                properties: {
+                                    total_iterations: { type: "number" },
+                                    kept: { type: "number" },
+                                    discarded: { type: "number" },
+                                    needs_human: { type: "number" },
+                                    consecutive_discards: { type: "number" },
+                                    best_iteration: { type: "number" },
+                                    debug_depth: { type: "number" },
+                                },
+                            },
+                            flags: {
+                                type: "object",
+                                required: ["stop_requested", "needs_human", "background_active", "stop_ready"],
+                                properties: {
+                                    stop_requested: { type: "boolean" },
+                                    needs_human: { type: "boolean" },
+                                    background_active: { type: "boolean" },
+                                    stop_ready: { type: "boolean" },
+                                },
+                            },
+                            last_iteration: {
+                                type: "object",
+                                properties: {
+                                    iteration: { type: "number" },
+                                    decision: { type: "string", enum: ["keep", "discard", "needs_human"] },
+                                    metric_value: { type: "string" },
+                                    change_summary: { type: "string" },
+                                    labels: { type: "array", items: { type: "string" } },
+                                    timestamp: { type: "string", format: "date-time" },
+                                },
+                            },
+                            draft_pool: { type: "object", description: "Draft pool configuration" },
+                            lineage: { type: "object", description: "Experiment lineage" },
+                            budget_exhausted: { type: "boolean" },
+                            budget_blocker_reason: { type: "string" },
+                        },
+                    },
+                    result_row: {
+                        type: "object",
+                        description: "Single iteration result row in TSV format",
+                        properties: {
+                            iteration: { type: "number" },
+                            decision: { type: "string" },
+                            metric_value: { type: "string" },
+                            verify_status: { type: "string" },
+                            guard_status: { type: "string" },
+                            change_summary: { type: "string" },
+                            labels: { type: "array", items: { type: "string" } },
+                            timestamp: { type: "string" },
+                            note: { type: "string" },
+                        },
+                    },
+                    goal_doc: {
+                        type: "object",
+                        required: ["goal", "metric", "direction", "verify"],
+                        properties: {
+                            goal: { type: "string" },
+                            metric: { type: "string" },
+                            direction: { type: "string", enum: ["higher", "lower"] },
+                            verify: { type: "string" },
+                            guard: { type: "string" },
+                            constraints: { type: "string" },
+                            file_map: { type: "string" },
+                            stop_conditions: { type: "string" },
+                        },
+                    },
+                };
+                if (useJson) {
+                    printJsonEnvelope("contract", schemas);
+                    break;
+                }
+                console.log("Auto Research Contract Schemas");
+                console.log("==============================");
+                console.log("");
+                console.log("State Schema:");
+                console.log(`  Version:    ${schemas.state.properties.schema_version.type}`);
+                console.log(`  Required:   ${schemas.state.required.join(", ")}`);
+                console.log("");
+                console.log("Result Row Schema:");
+                console.log(`  Properties: ${Object.keys(schemas.result_row.properties).join(", ")}`);
+                console.log("");
+                console.log("Goal Doc Schema:");
+                console.log(`  Required:   ${schemas.goal_doc.required.join(", ")}`);
+                console.log("");
+                console.log("Use --json for full machine-readable schema output.");
+                break;
+            }
             case "summary": {
                 const { resolvePath } = await import("./helpers.js");
                 const { RESULTS_DEFAULT } = await import("./constants.js");
@@ -746,7 +993,7 @@ const main = async () => {
                         runIds.add(iterTags[0]);
                 }
                 if (useJson) {
-                    printJson({
+                    printJsonEnvelope("summary", {
                         total_records: records.length,
                         total_kept: totalKept,
                         total_discarded: totalDiscarded,
@@ -789,7 +1036,7 @@ const main = async () => {
                 if (!grouped.verify)
                     errors.push("Missing required: --verify");
                 if (useJson) {
-                    printJson({ valid: errors.length === 0, errors });
+                    printJsonEnvelope("validate", { valid: errors.length === 0, errors });
                     return errors.length > 0 ? 1 : 0;
                 }
                 if (errors.length === 0) {
@@ -827,7 +1074,7 @@ const main = async () => {
                     results = resultLines.slice(1).filter(Boolean);
                 }
                 if (useJson) {
-                    printJson({ state, results_count: results.length });
+                    printJsonEnvelope("report", { state, results_count: results.length });
                     break;
                 }
                 console.log(`# Auto Research Report`);
@@ -861,6 +1108,40 @@ const main = async () => {
                         }
                     }
                 }
+                // Milestone Progress
+                console.log(`\n## Milestone Progress`);
+                if (state.stats) {
+                    const s = state.stats;
+                    const total = s.total_iterations;
+                    const successRate = total > 0 ? ((s.kept / total) * 100).toFixed(1) : "0";
+                    console.log(`- **Progress:** ${formatMarkdownField(s.kept)} kept / ${formatMarkdownField(total)} total iterations (${formatMarkdownField(successRate)}% success rate)`);
+                    if (state.iterations_cap) {
+                        const progressPct = ((total / state.iterations_cap) * 100).toFixed(1);
+                        console.log(`- **Cap:** ${formatMarkdownField(total)} / ${formatMarkdownField(state.iterations_cap)} iterations (${formatMarkdownField(progressPct)}% of cap)`);
+                    }
+                    if (state.created_at) {
+                        const startedAtMs = Date.parse(state.created_at);
+                        const endedAtMs = state.updated_at ? Date.parse(state.updated_at) : Date.now();
+                        if (!Number.isNaN(startedAtMs) && !Number.isNaN(endedAtMs) && endedAtMs >= startedAtMs) {
+                            const elapsedMin = Math.round((endedAtMs - startedAtMs) / 1000 / 60);
+                            console.log(`- **Elapsed:** ${formatMarkdownField(elapsedMin)} minutes`);
+                        }
+                    }
+                    // Next candidate
+                    if (state.last_iteration && state.last_iteration.decision === "keep") {
+                        console.log(`- **Next candidate:** Iteration ${formatMarkdownField(state.last_iteration.iteration)} (kept)`);
+                    }
+                    else if (s.best_iteration) {
+                        console.log(`- **Best candidate:** Iteration ${formatMarkdownField(s.best_iteration)}`);
+                    }
+                }
+                // Artifact pointers
+                console.log(`\n## Artifacts`);
+                console.log(`- State: ${formatMarkdownField(state.artifact_paths?.state || ".autoresearch/state.json")}`);
+                console.log(`- Results: ${formatMarkdownField(state.artifact_paths?.results || "autoresearch-results.tsv")}`);
+                if (grouped.repo) {
+                    console.log(`- Repository: ${formatMarkdownField(grouped.repo)}`);
+                }
                 // Failed branches information
                 if (state.draft_pool && state.draft_pool.active_drafts) {
                     const failedBranches = state.draft_pool.active_drafts.filter(draft => draft.status === "discarded");
@@ -920,6 +1201,37 @@ const main = async () => {
                 break;
             }
             case "suggest": {
+                const evidenceGated = grouped["evidence"] === "true";
+                if (evidenceGated) {
+                    const { generateIssueCandidate } = await import("./evidence.js");
+                    const candidate = generateIssueCandidate(grouped.repo, grouped.goal, grouped.metric, grouped.verify, grouped["score-history-path"]);
+                    if (!candidate) {
+                        if (useJson) {
+                            printJsonEnvelope("suggest", { candidates: [], reason: "insufficient_evidence" });
+                        }
+                        else {
+                            console.log("No evidence-gated issue candidates found.");
+                            console.log("Insufficient failure clusters or score history not available.");
+                        }
+                        break;
+                    }
+                    if (useJson) {
+                        printJsonEnvelope("suggest", { candidates: [candidate], evidence_gated: true });
+                    }
+                    else {
+                        console.log(`Evidence-Gated Issue Candidate:`);
+                        console.log(`  Title:   ${candidate.title}`);
+                        console.log(`  Goal:    ${candidate.goal}`);
+                        console.log(`  Metric:  ${candidate.metric}`);
+                        console.log(`  Evidence: ${candidate.evidence.total_discards} discards in ${candidate.evidence.total_runs} cluster(s)`);
+                        console.log(``);
+                        console.log(`  Suggested command:`);
+                        console.log(`    ${candidate.suggest_command}`);
+                        console.log(``);
+                        console.log(`Review before opening. This candidate is NOT auto-submitted.`);
+                    }
+                    break;
+                }
                 const { resolvePath } = await import("./helpers.js");
                 const { MEMORY_DEFAULT } = await import("./constants.js");
                 const memoryPath = resolvePath(grouped.repo, grouped["memory-path"], MEMORY_DEFAULT);
@@ -928,10 +1240,10 @@ const main = async () => {
                     break;
                 }
                 const memory = readFileSync(memoryPath, "utf-8");
-                const patterns = memory.match(/### Pattern: [^\n]+/g) ?? [];
+                const patterns = memory.match(/^### Pattern: [^\n]+/gm) ?? [];
                 const suggestions = patterns.map(parseMemoryPatternHeading);
                 if (useJson) {
-                    printJson({ patterns_found: suggestions.length, suggestions });
+                    printJsonEnvelope("suggest", { patterns_found: suggestions.length, suggestions });
                     break;
                 }
                 console.log("Memory Patterns — candidate next goals:");
@@ -974,7 +1286,7 @@ const main = async () => {
                     },
                 };
                 if (format === "json") {
-                    console.log(JSON.stringify(exportData, null, 2));
+                    printJsonEnvelope("export", exportData);
                 }
                 else if (format === "md" || format === "markdown") {
                     console.log(`# Auto Research Export`);
@@ -1000,8 +1312,8 @@ const main = async () => {
             }
             case "completion": {
                 const shell = grouped.shell || "bash";
-                const commands = ["init", "goal", "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", "--num-drafts", "--branch-policy", "--json", "--results-path", "--state-path", "--fresh-start", "--memory-path", "--format", "--shell", "--goal-path", "--template"];
+                const commands = ["init", "goal", "wizard", "status", "explain", "history", "config", "summary", "suggest", "launch", "complete", "stop", "resume", "record", "doctor", "pack", "export", "completion", "help"];
+                const options = ["--repo", "--goal", "--metric", "--direction", "--verify", "--guard", "--mode", "--scope", "--iterations", "--duration", "--num-drafts", "--branch-policy", "--branch-policy-overrides", "--json", "--results-path", "--state-path", "--fresh-start", "--memory-path", "--format", "--shell", "--goal-path", "--template"];
                 if (shell === "bash" || shell === "zsh") {
                     console.log(`# Auto Research CLI completion for ${shell}`);
                     console.log(`_autoresearch() {`);
@@ -1056,6 +1368,7 @@ const main = async () => {
                     baseline: grouped.baseline,
                     num_drafts: parsePositiveInt(grouped["num-drafts"], "num_drafts", { max: MAX_DRAFTS }) ?? 1,
                     branch_selection_policy: normalizeBranchPolicy(grouped["branch-policy"]),
+                    branch_policy_overrides: parseBranchPolicyOverrides(grouped["branch-policy-overrides"]),
                     outcome_metric: grouped["outcome-metric"],
                     outcome_direction: grouped["outcome-direction"],
                     instrument_metric: grouped["instrument-metric"],
@@ -1071,7 +1384,7 @@ const main = async () => {
                 const { writeFileSync } = await import("fs");
                 const state = await initializeRun(grouped.repo, grouped["results-path"], grouped["state-path"], config, grouped["fresh-start"] === "true");
                 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 });
+                printJsonEnvelope("launch", { status: "launched", run_id: state.run_id, launch_path: launchPath });
                 break;
             }
             case "complete": {
@@ -1081,7 +1394,7 @@ const main = async () => {
                 }
                 const { completeRun } = await import("./run-manager.js");
                 const state = await completeRun(grouped.repo, grouped["state-path"]);
-                printJson({ status: "completed", run_id: state.run_id });
+                printJsonEnvelope("complete", { status: "completed", run_id: state.run_id });
                 break;
             }
             case "stop": {
@@ -1091,7 +1404,7 @@ const main = async () => {
                 }
                 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 });
+                printJsonEnvelope("stop", { status: "stop_requested", run_id: state.run_id });
                 break;
             }
             case "resume": {
@@ -1101,7 +1414,7 @@ const main = async () => {
                 }
                 const { resumeBackgroundRun } = await import("./run-manager.js");
                 const state = await resumeBackgroundRun(grouped.repo, grouped["state-path"]);
-                printJson({ status: "resumed", run_id: state.run_id });
+                printJsonEnvelope("resume", { status: "resumed", run_id: state.run_id });
                 break;
             }
             case "record": {
@@ -1139,12 +1452,21 @@ const main = async () => {
                         note: grouped.note,
                         iteration,
                         score_components: scoreComponents,
+                        stage: grouped.stage || "improve",
+                        selected_action: grouped["selected-action"],
                     }, null, 2));
                     return 0;
                 }
                 const { appendIteration } = await import("./run-manager.js");
-                const state = await appendIteration(grouped.repo, grouped["results-path"], grouped["state-path"], grouped.decision, grouped["metric-value"], grouped["instrument-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, iteration, undefined, scorerStatus, scoreComponents);
-                printJson(state);
+                const lineage = {};
+                const stage = grouped.stage;
+                if (stage)
+                    lineage.stage = stage;
+                const selectedAction = grouped["selected-action"];
+                if (selectedAction)
+                    lineage.selected_action = selectedAction;
+                const state = await appendIteration(grouped.repo, grouped["results-path"], grouped["state-path"], grouped.decision, grouped["metric-value"], grouped["instrument-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, iteration, undefined, scorerStatus, scoreComponents, Object.keys(lineage).length > 0 ? lineage : undefined);
+                printJsonEnvelope("record", state);
                 break;
             }
             case "digest": {
@@ -1155,7 +1477,7 @@ const main = async () => {
                 const { buildRunDigest } = await import("./run-manager.js");
                 const digest = await buildRunDigest(grouped.repo, grouped["results-path"], grouped["state-path"]);
                 if (useJson) {
-                    printJson(digest);
+                    printJsonEnvelope("digest", digest);
                 }
                 else {
                     console.log(`# Auto Research Digest`);
@@ -1199,7 +1521,7 @@ const main = async () => {
                     if (digest.flags && Object.keys(digest.flags).length > 0) {
                         console.log(`\n## Flags`);
                         for (const [key, value] of Object.entries(digest.flags)) {
-                            console.log(`- ${key}: ${formatMarkdownField(value)}`);
+                            console.log(`- ${formatMarkdownField(key)}: ${formatMarkdownField(value)}`);
                         }
                     }
                 }
@@ -1225,6 +1547,7 @@ const main = async () => {
                 const installedPath = getInstalledPackagePath(PACKAGE_NAME);
                 const installedInfo = installedPath ? getInstalledPackageInfo(PACKAGE_NAME) : null;
                 const updateCache = readUpdateCache();
+                const { skip: updateSkipped, reason: skipReason } = shouldSkipUpdateCheck(process.argv.slice(2));
                 const updateStatus = {
                     cache_exists: updateCache !== null,
                     last_check: updateCache?.last_check || null,
@@ -1232,9 +1555,13 @@ const main = async () => {
                     latest_version: updateCache?.latest_version || null,
                     update_available: updateCache?.update_available || false,
                     update_disabled: process.env.AUTORESEARCH_NO_UPDATE === "1",
+                    skipped: updateSkipped,
+                    skip_reason: skipReason,
                 };
                 if (useJson) {
-                    printJson({
+                    const { getWhatsNew } = await import("./whats-new.js");
+                    const wn = getWhatsNew(base);
+                    printJsonEnvelope("doctor", {
                         version: VERSION,
                         skill_name: SKILL_NAME,
                         runtime: `Node.js ${process.version}`,
@@ -1249,6 +1576,7 @@ const main = async () => {
                         update: updateStatus,
                         checks: checks,
                         checks_passed: checks.filter((c) => !c.ok).length === 0,
+                        whats_new: wn ? { features: wn.features, fixes: wn.fixes } : null,
                     });
                     break;
                 }
@@ -1269,7 +1597,10 @@ const main = async () => {
                 }
                 console.log("");
                 console.log("Update:");
-                if (updateCache) {
+                if (updateSkipped) {
+                    console.log(`  Skipped:    yes (${skipReason})`);
+                }
+                else if (updateCache) {
                     console.log(`  Last check: ${updateCache.last_check}`);
                     console.log(`  Current:    ${updateCache.current_version}`);
                     console.log(`  Latest:     ${updateCache.latest_version}`);
@@ -1294,6 +1625,20 @@ const main = async () => {
                     return 1;
                 }
                 console.log(`\nAll ${checks.length} checks passed.`);
+                const showWhatsNew = grouped["whats-new"] === "true";
+                if (showWhatsNew || useJson) {
+                    const { getWhatsNew, formatWhatsNew } = await import("./whats-new.js");
+                    const wn = getWhatsNew(base);
+                    if (wn) {
+                        if (useJson) {
+                            // Already displayed in JSON envelope — add it for next re-entry
+                        }
+                        else {
+                            console.log("");
+                            console.log(formatWhatsNew(wn));
+                        }
+                    }
+                }
                 break;
             }
             case "goal": {
@@ -1336,7 +1681,7 @@ const main = async () => {
                     }
                     const doc = readGoalDoc(goalPath);
                     if (useJson) {
-                        printJson(doc);
+                        printJsonEnvelope("goal", doc);
                         break;
                     }
                     console.log(`Goal:             ${formatDisplayValue(doc.goal)}`);
@@ -1456,7 +1801,7 @@ const main = async () => {
                 const result = buildGoalInitResult(goalPath, config, !hasRequiredFlags && isTTY);
                 if (isGoalDryRun) {
                     if (useGoalJson) {
-                        printJson({ ...result, dry_run: true });
+                        printJsonEnvelope("goal", { ...result, dry_run: true });
                     }
                     else {
                         console.log("[dry-run] Would write goal document to: " + goalPath);
@@ -1472,7 +1817,7 @@ const main = async () => {
                 }
                 atomicWriteTextInRepo(goalGrouped.repo, goalPath, document);
                 if (useGoalJson) {
-                    printJson(result);
+                    printJsonEnvelope("goal", result);
                 }
                 else {
                     console.log(`✓ Goal definition written to ${goalPath}`);
@@ -1487,6 +1832,181 @@ const main = async () => {
                 }
                 break;
             }
+            case "queue": {
+                const subCmd = cmdArgs[0] || "list";
+                if (subCmd === "help") {
+                    console.error("Usage: autoresearch queue <subcommand> [options]");
+                    console.error("");
+                    console.error("Subcommands:");
+                    console.error("  list     List tasks in the queue (default)");
+                    console.error("  enqueue  Enqueue a new task");
+                    console.error("  clean    Remove completed and failed tasks");
+                    break;
+                }
+                if (subCmd === "enqueue") {
+                    if (!grouped.goal || !grouped.metric || !grouped.verify) {
+                        console.error("--goal, --metric, and --verify are required for enqueue");
+                        return 1;
+                    }
+                    const { enqueueTasks } = await import("./task-queue.js");
+                    const tasks = await enqueueTasks(grouped.repo, [{ goal: grouped.goal, metric: grouped.metric, verify: grouped.verify }]);
+                    if (useJson) {
+                        printJson({ enqueued: tasks });
+                    }
+                    else {
+                        for (const t of tasks) {
+                            console.log(`Enqueued: ${t.id} - ${t.goal}`);
+                        }
+                    }
+                    break;
+                }
+                if (subCmd === "clean") {
+                    const { listTasks, writeManifest, resolveQueuePath } = await import("./task-queue.js");
+                    const queuePath = resolveQueuePath(grouped.repo);
+                    const manifest = await listTasks(grouped.repo);
+                    const before = manifest.tasks.length;
+                    manifest.tasks = manifest.tasks.filter((t) => t.status === "pending" || t.status === "leased");
+                    manifest.updated_at = new Date().toISOString();
+                    const removed = before - manifest.tasks.length;
+                    await writeManifest(queuePath, manifest);
+                    if (useJson) {
+                        printJson({ removed });
+                    }
+                    else {
+                        console.log(`Cleaned ${removed} completed/failed tasks. ${manifest.tasks.length} remain.`);
+                    }
+                    break;
+                }
+                const { listTasks } = await import("./task-queue.js");
+                const manifest = await listTasks(grouped.repo);
+                if (useJson) {
+                    printJson(manifest);
+                }
+                else {
+                    if (manifest.tasks.length === 0) {
+                        console.log("No tasks in queue.");
+                    }
+                    else {
+                        console.log(`Task Queue (${manifest.tasks.length} tasks):`);
+                        for (const task of manifest.tasks) {
+                            const icon = task.status === "completed" ? "v" : task.status === "failed" ? "x" : task.status === "leased" ? ">" : "*";
+                            console.log(`  ${icon} ${task.id}  [${task.status}]  ${task.goal}`);
+                        }
+                    }
+                }
+                break;
+            }
+            case "pack": {
+                const subCmd = cmdArgs[0] || "help";
+                if (subCmd === "help" || (subCmd !== "export" && subCmd !== "list" && subCmd !== "inspect")) {
+                    console.error("Usage: autoresearch pack <subcommand> [options]");
+                    console.error("Subcommands:");
+                    console.error("  export   Export validated run as a strategy pack");
+                    console.error("  list     List available strategy packs");
+                    console.error("  inspect  View a specific strategy pack");
+                    break;
+                }
+                if (subCmd === "export") {
+                    const { exportPack } = await import("./strategy-pack.js");
+                    const result = exportPack(grouped.repo, grouped["state-path"], grouped["goal-path"]);
+                    if (!result) {
+                        console.error("No run state found. Complete a run first.");
+                        return 1;
+                    }
+                    if (useJson) {
+                        printJsonEnvelope("pack", { exported: result.path, pack: result.pack });
+                    }
+                    else {
+                        console.log(`Strategy pack exported: ${result.path}`);
+                        console.log(`  Goal:    ${result.pack.goal}`);
+                        console.log(`  Metric:  ${result.pack.metric}`);
+                        console.log(`  Success: ${result.pack.evidence.success_rate}`);
+                    }
+                    break;
+                }
+                if (subCmd === "list") {
+                    const { listPacks } = await import("./strategy-pack.js");
+                    const packs = listPacks(grouped.repo);
+                    if (useJson) {
+                        printJsonEnvelope("pack", { packs });
+                    }
+                    else if (packs.length === 0) {
+                        console.log("No strategy packs found.");
+                    }
+                    else {
+                        console.log(`Strategy Packs (${packs.length}):`);
+                        for (const p of packs)
+                            console.log(`  ${p.name}`);
+                    }
+                    break;
+                }
+                if (subCmd === "inspect") {
+                    const name = cmdArgs[1];
+                    if (!name) {
+                        console.error("Usage: autoresearch pack inspect <name>");
+                        return 1;
+                    }
+                    const { readPack } = await import("./strategy-pack.js");
+                    const content = readPack(grouped.repo, name);
+                    if (!content) {
+                        console.error(`Pack not found: ${name}`);
+                        return 1;
+                    }
+                    console.log(content);
+                    break;
+                }
+                break;
+            }
+            case "leaderboard": {
+                const { generateLeaderboard, formatLeaderboardMarkdown, formatLeaderboardText } = await import("./leaderboard.js");
+                const { resolveRepo } = await import("./helpers.js");
+                const repo = resolveRepo(grouped.repo);
+                const leaderboard = generateLeaderboard(repo);
+                if (useJson) {
+                    printJson(leaderboard);
+                    break;
+                }
+                if (leaderboard.entries.length === 0) {
+                    console.log("No runs found. Complete some runs to see the leaderboard.");
+                    break;
+                }
+                if (grouped.format === "markdown") {
+                    console.log(formatLeaderboardMarkdown(leaderboard));
+                }
+                else {
+                    console.log(formatLeaderboardText(leaderboard));
+                }
+                break;
+            }
+            case "worker": {
+                const { workerOnce } = await import("./worker.js");
+                const once = grouped["once"] === "true";
+                if (!once) {
+                    console.error("worker requires --once flag");
+                    console.error("Usage: autoresearch worker --once [--json] [--repo <path>]");
+                    return 1;
+                }
+                const result = workerOnce(grouped.repo, grouped["state-path"], grouped["results-path"]);
+                if (useJson) {
+                    printJsonEnvelope("worker", result);
+                }
+                else {
+                    if (result.ready) {
+                        console.log(`✓ Ready for iteration ${result.iteration}`);
+                        console.log(`  Run ID:  ${result.run_id}`);
+                        console.log(`  Status:  ${result.status}`);
+                        console.log(`  Goal:    ${result.goal}`);
+                        if (result.metric)
+                            console.log(`  Metric:  ${result.metric}`);
+                    }
+                    else {
+                        console.log(`✗ Not ready: ${result.reason || "unknown"}`);
+                        console.log(`  Run ID: ${result.run_id}`);
+                        console.log(`  Iter:   ${result.iteration}`);
+                    }
+                }
+                return result.ready ? 0 : 1;
+            }
             default: {
                 console.error(`Unknown command: ${cmd}`);
                 console.error("Run 'autoresearch --help' for usage.");
@@ -1495,7 +2015,14 @@ const main = async () => {
         }
     }
     catch (exc) {
-        console.error(exc.message);
+        const { categorizeError, formatStructuredError } = await import("./error-categories.js");
+        const structured = categorizeError(exc);
+        if (useJson) {
+            console.error(formatStructuredError(structured, true));
+        }
+        else {
+            console.error(formatStructuredError(structured, false));
+        }
         return 2;
     }
     return 0;