co-maintainer 0.4.12 → 0.5.0-beta.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Murat Kirazkaya
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Murat Kirazkaya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,15 +2,14 @@
 
 [![NPM Version](https://img.shields.io/npm/v/co-maintainer)](https://www.npmjs.com/package/co-maintainer) [![](https://img.shields.io/badge/blog-co_maintainer_an_imitator_of_yours-blue)](https://muratkirazkaya.com/blogs/co-maintainer-an-imitator-of-yours)
 
-[Website](https://groophylifefor.github.io/co-maintainer/) ·
-[Docs](https://groophylifefor.github.io/co-maintainer/getting-started.html) ·
-[Cloud](https://dashboard.cm.ordu.dev/) (hosted, free, early access, invite only for now)
+[Website](https://co-maintainer.com) ·
+[Docs](https://co-maintainer.com/docs) ·
+[Cloud](https://cloud.co-maintainer.com) (hosted, free, early access, invite only for now)
 
-`co-maintainer` analyzes a GitHub repository and writes repository-specific
-`SKILL.md` guidance that helps developers contribute changes more reliably.
+An imitator of yours, A PR review tool like co-maintainer.
 
 It collects current code and workflows, selected pull requests and diffs, and
-default-branch commits. A low-cost model extracts evidence-bound observations; a
+default-branch commits. A low-cost model extracts evidence-bound observations. A
 higher-reasoning model turns them into concise contribution guidance for
 implementation, testing, review, and release decisions.
 
@@ -27,7 +26,7 @@ Requires Node.js 24 or newer.
 ```sh
 co-maintainer probe owner/repo --auth=gh
 
-co-maintainer init owner/repo --auth=gh --ai=openrouter --token=... \
+co-maintainer init owner/repo --auth=gh --ai=openrouter \
   --low-model=openai/gpt-oss-120b \
   --high-model=openai/gpt-5.6-luna \
   --include-codebase --include-pull-requests \
@@ -37,30 +36,39 @@ co-maintainer init owner/repo --auth=gh --ai=openrouter --token=... \
 co-maintainer review owner/repo 123 --improve-matrix=2 --debug
 
 co-maintainer review              # local branch (staged, unstaged, untracked)
-co-maintainer review --json       # machine-readable stdout; logs on stderr
+co-maintainer review --json       # machine-readable stdout, logs on stderr
+```
+
+Settings live in `config.json`, so a flag you use every time can be saved once:
 
-npm run review-local-e2e        # fake-AI local loop (developers, from repo root)
+```sh
+co-maintainer config set ai-key sk-or-...        # OpenRouter key
+co-maintainer config set high-model openai/gpt-5.6-luna
+co-maintainer config set low-model openai/gpt-oss-120b
+co-maintainer config list                        # every key, its value and its source
 ```
 
-Documentation: [Getting started](https://groophylifefor.github.io/co-maintainer/getting-started.html)
-(install → first review), [full docs site](https://groophylifefor.github.io/co-maintainer/),
+Documentation: [Getting started](https://co-maintainer.com/docs/getting-started.html)
+(install to first review) and the [full docs site](https://co-maintainer.com/docs),
 sources in [`docs/md/`](docs/md/).
 
 Use `co-maintainer help`, `co-maintainer -h`, or `co-maintainer --help` for the
-full CLI help.
+full CLI help. Every guide the CLI writes is also readable from the dashboard,
+and the dashboard keeps its guides separate from the CLI's. See
+[dashboard.md](docs/md/dashboard.md).
 
 ## Compared to other tools
 
 co-maintainer is a new tool, so it has not been compared with many others yet.
-It was benchmarked against [OCR](https://open-codereview.ai/). I cannot offer any
-guarantees because the datasets are very small, but it shows promise.
+It was benchmarked against [OCR](https://open-codereview.ai/) on `core_v2`. The
+datasets are small, so read the numbers as a signal, not a guarantee.
 
-In core_v2 benchmarks:
-
-- **2-3x better results** than OCR
-- **2-8x faster** than OCR
-- **70-200x fewer tokens** than OCR
-- **60-270x cheaper** than OCR
+| Claim, as measured on `core_v2` | Result             |
+| ------------------------------- | ------------------ |
+| Result quality against OCR      | 2 to 3x better     |
+| Speed against OCR               | 2 to 8x faster     |
+| Tokens per review against OCR   | 70 to 200x fewer   |
+| Cost per review against OCR     | 60 to 270x cheaper |
 
 ```mermaid
 xychart-beta
@@ -71,26 +79,37 @@ xychart-beta
     line "co-maintainer" [2, 10, 20, 40, 60, 80, 100, 120, 140, 160, 200]
 ```
 
-_Calculated based on co-maintainer's `core_v2` benchmark, which reports co-maintainer as 65x cheaper per review than OCR ($0.025/review vs. $1.62/review). Assumes 80 PR reviews per developer per month (40 PRs merged, avg. ~2 reviews each)._
+_Calculated from co-maintainer's `core_v2` benchmark, which reports co-maintainer as 65x cheaper per review than OCR ($0.025/review vs. $1.62/review). Assumes 80 PR reviews per developer per month (40 PRs merged, about 2 reviews each)._
 
 ## Benchmarks
 
-We recommend consider core_v3 benchmark results because of more suits for
-co-maintainer use cases. It is a much more meaningful metric than other
-benchmarks. core_v3 is co-maintainer only benchmark.
-
-Unlike the OCR comparison above (real human review comments as gold, see
-`benchmark/swe-prbench`), `bench core v3` scores against deliberately seeded,
-hand-verified defects in a dedicated target repo, half of the PRs kept as
-defect-free controls so precision is measurable too, not just recall. Full
-breakdown, per-PR results, and methodology:
+`core_v3` fits co-maintainer's use case better than the OCR comparison, so it is
+the more meaningful metric here. Unlike the OCR comparison (real human review
+comments as gold, see `benchmark/swe-prbench`), `bench core v3` scores against
+deliberately seeded, hand-verified defects in a dedicated target repo. Half of
+the PRs are kept as defect-free controls, so precision is measurable too, not
+just recall. Full breakdown, per-PR results, and methodology:
 [`benchmark/core_v3/README.md`](benchmark/core_v3/README.md).
 
-| metric        | value                         |
-| ------------- | ----------------------------- |
-| PRs reviewed  | 30 (14 defective, 16 control) |
-| F1            | 0.500                         |
-| Precision     | 0.353                         |
-| Recall        | 0.857                         |
-| Avg cost / PR | $0.0045                       |
-| Avg time / PR | 28.9s                         |
+| metric        | value                         | context                     |
+| ------------- | ----------------------------- | --------------------------- |
+| PRs reviewed  | 30 (14 defective, 16 control) | one target repo             |
+| F1            | 0.500                         | against seeded defects only |
+| Precision     | 0.353                         | 1.00 on the control PRs     |
+| Recall        | 0.857                         | 12 of 14 defects found      |
+| Avg cost / PR | $0.0045                       | low and high model together |
+| Avg time / PR | 28.9s                         | sequential, no concurrency  |
+
+## Development
+
+From a checkout:
+
+```sh
+npm install
+npm test                 # unit, script and benchmark tests
+npm run check            # tsc --noEmit
+npm run docs:build       # rebuild docs/ from docs/md/
+npm run e2e              # end-to-end CLI loop
+npm run review-local-e2e # fake-AI local review loop
+npm run dashboard:smoke  # browser smoke test
+```

package/dist/main.js

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
-import { run } from "./src/cli/main.js";
+import { reportCliError, run } from "./src/cli/main.js";
 try {
     await run(process.argv.slice(2));
 }
 catch (error) {
-    console.error(`[error] ${error instanceof Error ? error.message : String(error)}`);
-    process.exit(1);
+    reportCliError(error);
 }

package/dist/package.json

@@ -1,23 +1,23 @@
 {
     "name": "co-maintainer",
-    "version": "0.4.12",
-    "description": "Analyzes a GitHub repository and writes repository-specific contribution guidance.",
+    "version": "0.5.0-beta.1",
+    "description": "An imitator of yours, A PR review tool like co-maintainer.",
+    "keywords": [
+        "ai",
+        "code-review",
+        "github",
+        "maintainer",
+        "pull-request"
+    ],
+    "homepage": "https://co-maintainer.com",
+    "bugs": {
+        "url": "https://github.com/GroophyLifefor/co-maintainer/issues"
+    },
     "license": "MIT",
     "repository": {
         "type": "git",
         "url": "https://github.com/GroophyLifefor/co-maintainer"
     },
-    "homepage": "https://github.com/GroophyLifefor/co-maintainer#readme",
-    "bugs": {
-        "url": "https://github.com/GroophyLifefor/co-maintainer/issues"
-    },
-    "keywords": [
-        "github",
-        "pull-request",
-        "code-review",
-        "maintainer",
-        "ai"
-    ],
     "bin": {
         "co-maintainer": "dist/main.js"
     },
@@ -34,7 +34,7 @@
         "build": "npm run assets:embed && tsc -p tsconfig.build.json",
         "assets:embed": "node scripts/embed_assets.mjs",
         "prepack": "npm run build",
-        "test": "node --test \"src/**/*.test.ts\" \"benchmark/**/*.test.ts\"",
+        "test": "node --test \"src/**/*.test.ts\" \"scripts/**/*.test.ts\" \"benchmark/**/*.test.ts\"",
         "check": "tsc --noEmit",
         "lint": "oxlint",
         "fmt": "oxfmt --write .",
@@ -43,6 +43,7 @@
         "probe": "node main.ts probe",
         "init": "node main.ts init",
         "remake": "node main.ts remake",
+        "sync": "node main.ts sync",
         "review": "node main.ts review",
         "serve": "node main.ts serve",
         "bench": "node benchmark/core_v2/run.ts",
@@ -52,7 +53,11 @@
         "swe-prbench-prepare": "node benchmark/swe-prbench/prepare_dataset.ts",
         "e2e": "node scripts/e2e.ts",
         "review-local-e2e": "node scripts/review_local_e2e.ts",
-        "docs:build": "node scripts/build_docs.ts"
+        "docs:build": "node scripts/build_docs.ts",
+        "pack:smoke": "node scripts/pack_smoke.ts",
+        "downgrade:check": "node scripts/downgrade_check.ts",
+        "dx:scenario": "node scripts/dx_scenario.ts",
+        "dashboard:smoke": "node scripts/dashboard_smoke.ts"
     },
     "dependencies": {
         "marked": "^15.0.7"
@@ -61,6 +66,7 @@
         "@types/node": "^24.0.0",
         "oxfmt": "^0.68.0",
         "oxlint": "^1.83.0",
+        "playwright": "^1.63.0",
         "typescript": "^5.7.0"
     },
     "engines": {

package/dist/src/ai/batch.d.ts

@@ -1,5 +1,16 @@
 import type { AiProvider, AiRequest, AiResponse } from "../types.ts";
 type UsageSink = (job: string, response: AiResponse) => Promise<void>;
+/** Returns `null` when a response is usable, or a short reason when it is not.
+ * `synthesis.ts` supplies one that parses the model text, because a syntactically
+ * fine HTTP response can still be unparseable output, and caching that is what
+ * poisoned every later `sync` (CORE-30 / F04). */
+export type AiValidator = (request: AiRequest, response: AiResponse) => string | null;
+/** A unit whose output never parsed, kept so the run can say what it dropped. */
+export type SkippedUnit = {
+    index: number;
+    job: string;
+    reason: string;
+};
 export declare class AiBatch {
     private records;
     private loaded;
@@ -8,8 +19,20 @@ export declare class AiBatch {
     private readonly repo;
     private readonly concurrency;
     private readonly profile;
-    constructor(provider: AiProvider, repo: string, concurrency: number, profile: string);
+    private readonly validate?;
+    private readonly skipped;
+    constructor(provider: AiProvider, repo: string, concurrency: number, profile: string, validate?: AiValidator);
+    /** Units whose output did not parse this run (or on re-try), in request order. */
+    skippedUnits(): SkippedUnit[];
     run(requests: AiRequest[], usage?: UsageSink): Promise<(AiResponse | undefined)[]>;
+    /** Runs one unit, caching its response only when the validator accepts it.
+     * A rejected response is retried once; a second rejection is recorded as
+     * skipped and never cached, so the next `sync` retries it rather than
+     * replaying the same unusable output (CORE-30 / F04). */
+    private completeUnit;
+    /** Records a unit as skipped: no cache write, so it stays retried and its
+     * absence is never mistaken for a deliberate empty result. */
+    private markSkipped;
     private load;
     private persist;
 }

package/dist/src/ai/batch.js

@@ -1,5 +1,6 @@
 import { cacheGet, cacheSet } from "../store/cache_db.js";
 import { isNotFound, readTextFile } from "../util/runtime.js";
+import { formatError } from "../cli/error.js";
 async function digest(value) {
     const bytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
     return [...new Uint8Array(bytes)]
@@ -14,11 +15,18 @@ export class AiBatch {
     repo;
     concurrency;
     profile;
-    constructor(provider, repo, concurrency, profile) {
+    validate;
+    skipped = [];
+    constructor(provider, repo, concurrency, profile, validate) {
         this.provider = provider;
         this.repo = repo;
         this.concurrency = concurrency;
         this.profile = profile;
+        this.validate = validate;
+    }
+    /** Units whose output did not parse this run (or on re-try), in request order. */
+    skippedUnits() {
+        return [...this.skipped];
     }
     async run(requests, usage) {
         await this.load();
@@ -35,8 +43,20 @@ export class AiBatch {
             }));
             const cached = this.records[id];
             if (cached?.status === "done" && cached.response) {
-                results[index] = cached.response;
-                console.log(`[ai] cache hit ${request.job} ${id.slice(0, 8)}`);
+                // A `done` record from 0.4.x can hold output that never parsed. Treat
+                // that as a miss and delete it so the retry below replaces it; the
+                // corrupted record heals on its own the next time its unit runs.
+                const reason = this.validate?.(request, cached.response) ?? null;
+                if (reason === null) {
+                    results[index] = cached.response;
+                    console.log(`[ai] cache hit ${request.job} ${id.slice(0, 8)}`);
+                }
+                else {
+                    delete this.records[id];
+                    await this.persist();
+                    console.log(`[ai] dropped unusable cache record ${request.job} ${id.slice(0, 8)}: ${reason}`);
+                    pending.push({ index, id, request });
+                }
             }
             else if (cached?.status === "quarantine") {
                 console.log(`[ai] quarantined job skipped: ${request.job} ${id.slice(0, 8)}`);
@@ -57,26 +77,7 @@ export class AiBatch {
                     console.log(`[ai] still running ${item.request.job} ${item.id.slice(0, 8)} · ${seconds}s`);
                 }, 15_000);
                 try {
-                    const response = await this.provider.complete(item.request);
-                    this.records[item.id] = {
-                        status: "done",
-                        response,
-                        updatedAt: new Date().toISOString(),
-                    };
-                    results[item.index] = response;
-                    await this.persist();
-                    if (usage)
-                        await usage(item.request.job, response);
-                    console.log(`[ai] done ${item.request.job} ${item.id.slice(0, 8)} · ${Math.round((Date.now() - startedAt) / 1000)}s`);
-                }
-                catch (error) {
-                    this.records[item.id] = {
-                        status: "quarantine",
-                        error: String(error),
-                        updatedAt: new Date().toISOString(),
-                    };
-                    await this.persist();
-                    console.log(`[ai] quarantined ${item.request.job} ${item.id.slice(0, 8)}: ${String(error)}`);
+                    await this.completeUnit(item, results, usage, startedAt);
                 }
                 finally {
                     clearInterval(heartbeat);
@@ -87,6 +88,57 @@ export class AiBatch {
         await this.saveChain;
         return results;
     }
+    /** Runs one unit, caching its response only when the validator accepts it.
+     * A rejected response is retried once; a second rejection is recorded as
+     * skipped and never cached, so the next `sync` retries it rather than
+     * replaying the same unusable output (CORE-30 / F04). */
+    async completeUnit(item, results, usage, startedAt) {
+        for (const attempt of [1, 2]) {
+            try {
+                const response = await this.provider.complete(item.request);
+                const reason = this.validate?.(item.request, response) ?? null;
+                if (reason !== null) {
+                    if (attempt === 2) {
+                        this.markSkipped(item, reason);
+                        return;
+                    }
+                    console.log(`[ai] retrying ${item.request.job} ${item.id.slice(0, 8)}: ${reason}`);
+                    continue;
+                }
+                this.records[item.id] = {
+                    status: "done",
+                    response,
+                    updatedAt: new Date().toISOString(),
+                };
+                results[item.index] = response;
+                await this.persist();
+                if (usage)
+                    await usage(item.request.job, response);
+                console.log(`[ai] ${attempt === 1 ? "done" : "retried"} ${item.request.job} ${item.id.slice(0, 8)} · ${Math.round((Date.now() - startedAt) / 1000)}s`);
+                return;
+            }
+            catch (error) {
+                this.records[item.id] = {
+                    status: "quarantine",
+                    error: formatError(error),
+                    updatedAt: new Date().toISOString(),
+                };
+                await this.persist();
+                console.log(`[ai] quarantined ${item.request.job} ${item.id.slice(0, 8)}: ${formatError(error)}`);
+                return;
+            }
+        }
+    }
+    /** Records a unit as skipped: no cache write, so it stays retried and its
+     * absence is never mistaken for a deliberate empty result. */
+    markSkipped(item, reason) {
+        this.skipped.push({
+            index: item.index,
+            job: item.request.job,
+            reason,
+        });
+        console.log(`[ai] skipped ${item.request.job} ${item.index}: ${reason}`);
+    }
     async load() {
         if (this.loaded)
             return;

package/dist/src/ai/estimate.d.ts

@@ -0,0 +1,40 @@
+import type { ModelPrice } from "./pricing.ts";
+type RecordedJob = {
+    tokensIn: number;
+    tokensOut: number;
+    seconds: number;
+};
+/** Averages this repository's recorded AI jobs from cache.db. `recordAiCost`
+ * keys each job `${repo}:${uuid}`, so the history belongs to the repo the
+ * estimate is for. Fewer than four jobs is not a trend, so it is ignored. */
+export declare function readJobHistory(repo: string): Promise<RecordedJob | undefined>;
+export type EstimateInput = {
+    /** How many pull requests the recommended flags would read. */
+    pullRequests: number;
+    /** Whether the recommended flags read the codebase. */
+    includeCodebase: boolean;
+    lowModel?: string;
+    highModel?: string;
+    prices: Map<string, ModelPrice>;
+    history?: RecordedJob;
+};
+export type Estimate = {
+    extract: number;
+    synth: number;
+    seconds: [number, number];
+    tokensIn: [number, number];
+    tokensOut: [number, number];
+    /** Absent when no price is known for the models. */
+    usd?: [number, number];
+    basis: "history" | "calibration";
+};
+/** The number of `extract_unit` jobs the recommended init would queue: one per
+ * pull request plus one for the codebase/documents, matching
+ * `extractAiFacts`. */
+export declare function extractJobCount(input: {
+    pullRequests: number;
+    includeCodebase: boolean;
+    includeHowRepoWorks: boolean;
+}): number;
+export declare function estimateInit(input: EstimateInput): Estimate;
+export {};

package/dist/src/ai/estimate.js

@@ -0,0 +1,113 @@
+/** Cost and time estimate for the recommended `init` (CORE-24, F17).
+ *
+ * Three sources, in order of trust:
+ *
+ * 1. Job counts come from the same inputs the real run uses — the number of
+ *    pull requests, whether the codebase is read, and the ten synthesis
+ *    sections — so the shape is exact.
+ * 2. Dollars come from the live OpenRouter price for the configured models.
+ *    When prices are unavailable the estimate reports tokens but no dollars
+ *    rather than guessing one.
+ * 3. Time and per-job tokens come from this repository's recorded jobs when
+ *    there are enough, and from the calibration below otherwise.
+ *
+ * Calibration (plan §CORE-24): cm-dx-lab, 4 pull requests and 8 files, 5
+ * extract and 9 synth jobs, 151 s, $0.0014 — about 151/14 ≈ 10.8 s per job.
+ * Token counts per job are near 2.4k in and 0.7k out. The text always says
+ * the numbers are an estimate. */
+import { cacheValues } from "../store/cache_db.js";
+import { sectionKeys } from "../knowledge/sections.js";
+/** Measured averages used when no history exists (cm-dx-lab calibration). */
+const CALIBRATION = {
+    seconds: 10.8,
+    tokensIn: 2_400,
+    tokensOut: 700,
+};
+/** A spread around the point estimate, since a real run varies. */
+const SPREAD = 0.25;
+const MAX_HISTORY_ROWS = 200;
+/** Averages this repository's recorded AI jobs from cache.db. `recordAiCost`
+ * keys each job `${repo}:${uuid}`, so the history belongs to the repo the
+ * estimate is for. Fewer than four jobs is not a trend, so it is ignored. */
+export async function readJobHistory(repo) {
+    let rows;
+    try {
+        rows = await cacheValues("cost", `${repo}:`);
+    }
+    catch {
+        return undefined;
+    }
+    if (rows.length < 4)
+        return undefined;
+    let tokensIn = 0;
+    let tokensOut = 0;
+    let seconds = 0;
+    let counted = 0;
+    for (const raw of rows.slice(0, MAX_HISTORY_ROWS)) {
+        try {
+            const row = JSON.parse(raw);
+            tokensIn += Number(row.tokensIn ?? 0);
+            tokensOut += Number(row.tokensOut ?? 0);
+            seconds += Number(row.seconds ?? CALIBRATION.seconds);
+            counted++;
+        }
+        catch {
+            // A malformed row is skipped, not counted as a zero.
+        }
+    }
+    if (counted === 0)
+        return undefined;
+    return {
+        tokensIn: tokensIn / counted,
+        tokensOut: tokensOut / counted,
+        seconds: seconds / counted,
+    };
+}
+/** A low/high band around a point estimate. */
+function band(value) {
+    return [value * (1 - SPREAD), value * (1 + SPREAD)];
+}
+/** The number of `extract_unit` jobs the recommended init would queue: one per
+ * pull request plus one for the codebase/documents, matching
+ * `extractAiFacts`. */
+export function extractJobCount(input) {
+    let count = input.pullRequests;
+    if (input.includeCodebase || input.includeHowRepoWorks)
+        count += 1;
+    return count;
+}
+export function estimateInit(input) {
+    const extract = extractJobCount({
+        pullRequests: input.pullRequests,
+        includeCodebase: input.includeCodebase,
+        includeHowRepoWorks: true,
+    });
+    const synth = sectionKeys.length;
+    const jobs = extract + synth;
+    const per = input.history ?? CALIBRATION;
+    const seconds = band(jobs * per.seconds);
+    const tokensIn = band(jobs * per.tokensIn);
+    const tokensOut = band(jobs * per.tokensOut);
+    // Price the extract jobs with the low model and the synth jobs with the
+    // high model, which is how `init` splits the work. A model with no known
+    // price makes the dollar range unavailable rather than zero.
+    const low = input.lowModel ? input.prices.get(input.lowModel) : undefined;
+    const high = input.highModel ? input.prices.get(input.highModel) : undefined;
+    let usd;
+    if (low && high) {
+        const costPerJob = (per.tokensIn / 1_000_000) * low.usdPerMillionIn +
+            (per.tokensOut / 1_000_000) * low.usdPerMillionOut;
+        const costPerSynth = (per.tokensIn / 1_000_000) * high.usdPerMillionIn +
+            (per.tokensOut / 1_000_000) * high.usdPerMillionOut;
+        usd = band(extract * costPerJob + synth * costPerSynth);
+    }
+    return {
+        extract,
+        synth,
+        seconds,
+        tokensIn,
+        tokensOut,
+        usd,
+        basis: input.history ? "history" : "calibration",
+    };
+}

package/dist/src/ai/fake.d.ts

@@ -1,5 +1,5 @@
 import type { AiProvider, AiRequest, AiResponse } from "../types.ts";
-export declare const FAKE_REVIEW_MARKDOWN = "## Findings\n\n### [P2 \u00B7 non-blocking] `src/app.ts` \u2014 `helper()`\nLocation: `src/app.ts:4`\n\nThe helper ignores its argument, so the new behavior is never applied.\n\nThe helper accepts an argument but returns the same result without reading it.\n\nIf you'd like me to explain it in more detail, please ask.\n";
+export declare const FAKE_REVIEW_MARKDOWN = "## Findings\n\n### [P2 \u00B7 non-blocking] `src/app.ts`: `helper()`\nLocation: `src/app.ts:4`\n\nThe helper ignores its argument, so the new behavior is never applied.\n\nThe helper accepts an argument but returns the same result without reading it.\n\nIf you'd like me to explain it in more detail, please ask.\n";
 export declare class FakeAiProvider implements AiProvider {
     private readonly text;
     constructor(text?: string);

package/dist/src/ai/fake.js

@@ -1,7 +1,7 @@
 import { getEnv, readTextFileSync } from "../util/runtime.js";
 export const FAKE_REVIEW_MARKDOWN = `## Findings
 
-### [P2 · non-blocking] \`src/app.ts\` — \`helper()\`
+### [P2 · non-blocking] \`src/app.ts\`: \`helper()\`
 Location: \`src/app.ts:4\`
 
 The helper ignores its argument, so the new behavior is never applied.

package/dist/src/ai/hetzner.js

@@ -59,7 +59,7 @@ export class HetznerProvider {
         const wait = this.nextRequest - Date.now();
         if (wait > 0) {
             const jittered = this.jitter(wait);
-            console.log(`[ai] hetzner quota spacing; waiting ${Math.round(jittered / 1000)}s`);
+            console.log(`[ai] hetzner quota spacing, waiting ${Math.round(jittered / 1000)}s`);
             await this.sleeper(jittered);
         }
     }

package/dist/src/ai/openrouter.d.ts

@@ -1,9 +1,22 @@
 import type { AiProvider, AiRequest, AiResponse } from "../types.ts";
+import { CliError } from "../cli/error.ts";
+/** Provider failures as actionable text (CORE-12, F24/F28). A 401 and a 400 for
+ * an unknown model are preconditions the user can fix, so they are usage
+ * errors; anything else is a runtime failure. Only the provider's own
+ * `error.message` is surfaced: the raw body can carry account metadata
+ * (`user_id`) that has no business in a terminal. */
+export declare function openRouterError(model: string, status: number, body: string): CliError;
 export declare class OpenRouterProvider implements AiProvider {
     readonly supportsTools = true;
+    /** `CM_OPENROUTER_URL` points the provider at a local fake in tests. It is
+     * only a default override: with the env unset the real endpoint is used, so
+     * nothing changes for users. */
     private readonly endpoint;
     private readonly apiKey;
     private readonly model;
     constructor(apiKey: string, model: string);
+    /** One POST. Returns the raw response so `complete` can decide whether the
+     * failure is worth a retry without the schema. */
+    private post;
     complete(request: AiRequest): Promise<AiResponse>;
 }