co-maintainer 0.5.0 → 0.5.1-beta.2

package/dist/src/local/git_untracked.js

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { normalizePath } from "../review/revision.js";
 import { lstat, readFile, readLink } from "../util/runtime.js";
 const NUL_SCAN_BYTES = 8000;
-/** Build patch for a new untracked file (plan §10.8). */
+/** Build patch for a new untracked file. */
 export function patchFromNewFileContent(content) {
     const scan = content.subarray(0, Math.min(content.length, NUL_SCAN_BYTES));
     if (scan.includes(0)) {

package/dist/src/local/review_local.js

@@ -1,7 +1,7 @@
 import { parseArgs } from "../cli/args.js";
 import { filterReviewConfigArgs, } from "../cli/review_args.js";
-import { buildLocalReviewJson, formatHumanLocalReview, resolvedFromFirstReview, reviewExitCodeFromResolved, } from "../cli/review_result.js";
-import { emptyAiMetrics, recordAiCost, runInitOrRemake, } from "../services/setup.js";
+import { buildLocalReviewJson, formatHumanLocalReview, humanFindingsFromResolved, resolvedFromFirstReview, reviewExitCodeFromResolved, } from "../cli/review_result.js";
+import { addAiMetrics, emptyAiMetrics, recordAiCost, runInitOrRemake, } from "../services/setup.js";
 import { aiFor } from "../services/review.js";
 import { loadGuides } from "../review/guides.js";
 import { buildCarryPromptSection, classifyCarryItems, guideRebuiltSince, incrementalDiffPaths, parsePreviousVerdicts, resolveCarryOutcomes, } from "../review/carry_over.js";
@@ -11,6 +11,7 @@ import { reviewWorkspaceRevision } from "../pr/reviewer.js";
 import { runCommand } from "../pr/checkout.js";
 import { log, startHeartbeat, timed, withCliLogsToStderr, } from "../util/log.js";
 import { printRunSummary, summaryFromMetrics } from "../util/run_summary.js";
+import { emitGithubOutput } from "../cli/review_github.js";
 import { setCliInteractive } from "../cli/args.js";
 import { prepareLocalCodegraph } from "./codegraph_prepare.js";
 import { canPrompt } from "../tools/codegraph.js";
@@ -19,6 +20,7 @@ import { assertGitQuiet, currentBranch, detectRemoteRepo, gitRoot, headSha, Revi
 import { EXIT_RUNTIME, exitWith } from "../cli/error.js";
 import { buildLocalRevision, mergeBase, resolveBaseRef, } from "./git_revision.js";
 import { clearLocalCarry, localSubjectId, saveLocalCarry, tryLoadLocalCarry, } from "./carry_over_store.js";
+import { costUsage } from "../util/cost.js";
 function storedFindings(resolved) {
     return resolved
         .filter((row) => row.state === "new" || row.state === "open")
@@ -49,7 +51,7 @@ function fail(error, json) {
             console.error(`Hint: ${error.hint}`);
     }
     // Set the exit code and return; `process.exit` here would assert in libuv on
-    // Windows whenever a fetch pool is open (CORE-11).
+    // Windows whenever a fetch pool is open.
     exitWith(error.exitCode);
 }
 function installInterruptCleanup(releaseSync, json) {
@@ -159,7 +161,7 @@ export async function runLocalReview(cli) {
             let previous = carryLoad.data;
             // A guide rebuilt after the last review judged its findings under rules
             // that no longer exist. Rather than let those stale findings mask new
-            // ones, start fresh automatically (CORE-42 / F03) — the same effect as
+            // ones, start fresh automatically — the same effect as
             // `--fresh`, without making the user remember the flag.
             if (previous &&
                 guideRebuiltSince(previous.guideBuiltAt, guides.guideBuiltAt)) {
@@ -189,7 +191,7 @@ export async function runLocalReview(cli) {
                 enabled: options.useCodegraph === true,
                 allowInstall: cli.allowToolInstall,
                 // `--json` output must stay machine-readable, so never prompt then;
-                // `canPrompt` adds the TTY and CI checks (F01).
+                // `canPrompt` adds the TTY and CI checks.
                 interactive: !json && canPrompt(),
             });
             extras.prepareCodegraphTools = () => Promise.resolve(codegraphPrep.tools);
@@ -199,19 +201,13 @@ export async function runLocalReview(cli) {
             let response;
             try {
                 response = await timed("local review AI", options.logTime, () => reviewWorkspaceRevision(revision, options, sha, async (usage) => {
-                    aiMetrics.calls++;
-                    aiMetrics.tokensIn += usage.tokensIn;
-                    aiMetrics.tokensOut += usage.tokensOut;
-                    if (usage.cost === undefined)
-                        aiMetrics.costKnown = false;
-                    else
-                        aiMetrics.cost += usage.cost;
+                    addAiMetrics(aiMetrics, usage);
                     await recordAiCost(repo, "review_local", usage);
                 }, aiFor(options), (message) => log("review", message), extras));
             }
             finally {
                 // Stopping the heartbeat on the error path too, otherwise the interval
-                // keeps the event loop alive and a post-fetch exit never lands (CORE-11).
+                // keeps the event loop alive and a post-fetch exit never lands.
                 stopHeartbeat();
                 await lock?.release();
                 lock = null;
@@ -255,7 +251,7 @@ export async function runLocalReview(cli) {
             const usage = {
                 tokensIn: aiMetrics.tokensIn,
                 tokensOut: aiMetrics.tokensOut,
-                costUsd: aiMetrics.costKnown ? aiMetrics.cost : null,
+                ...costUsage(aiMetrics),
             };
             if (json) {
                 console.log(buildLocalReviewJson({
@@ -273,6 +269,13 @@ export async function runLocalReview(cli) {
                     reviewBlocking: options.reviewBlocking,
                 }));
             }
+            else if (cli.output === "github") {
+                emitGithubOutput({
+                    title: header,
+                    findings: humanFindingsFromResolved(allResolved, options.reviewBlocking),
+                    run: summaryFromMetrics(aiMetrics, performance.now() - started),
+                });
+            }
             else {
                 console.log("\n" +
                     formatHumanLocalReview(header, revision, response.guideBuiltAt, codegraphState, allResolved, warnings, options.reviewBlocking) +

package/dist/src/local/review_lock.d.ts

@@ -3,5 +3,5 @@ export type LocalReviewLock = {
     /** For signal handlers — must not await before exit. */
     releaseSync: () => void;
 };
-/** One local review per repo root (plan §13.3). */
+/** One local review per repo root. */
 export declare function acquireLocalReviewLock(gitRoot: string): Promise<LocalReviewLock>;

package/dist/src/local/review_lock.js

@@ -11,7 +11,7 @@ async function lockPath(gitRoot) {
     await mkdir(dir, { recursive: true });
     return `${dir}/${hex}.lock`;
 }
-/** One local review per repo root (plan §13.3). */
+/** One local review per repo root. */
 export async function acquireLocalReviewLock(gitRoot) {
     const path = await lockPath(gitRoot);
     let existingPid;

package/dist/src/pr/checkout.js

@@ -34,7 +34,7 @@ async function cloneInto(repo, dir, run) {
     const started = performance.now();
     // `-c core.longpaths=true` has to be in effect for the clone itself: a deep
     // source tree can overrun the Windows path limit while the objects are being
-    // written, and setting the config afterwards is too late to help. CORE-11.
+    // written, and setting the config afterwards is too late to help.
     const result = await run("git", [
         "-c",
         "core.longpaths=true",
@@ -45,7 +45,7 @@ async function cloneInto(repo, dir, run) {
     ]);
     if (result.code !== 0) {
         // One actionable line, not the raw multi-line git transcript: the caller
-        // only needs to know the clone failed and what it costs them. CORE-11.
+        // only needs to know the clone failed and what it costs them.
         const firstLine = result.stderr
             .split(/\r?\n/)
             .map((line) => line.trim())

package/dist/src/pr/findings.js

@@ -3,7 +3,7 @@ const FILE_LINE = /(?<path>(?:[\w.-]+\/)*[\w.-]+\.[A-Za-z0-9]+):(?<from>\d+)(?:-
  * sometimes writes `:` where the prompt asked for the em dash, and sometimes
  * leaves the symbol off. Both are accepted: an unrecognised heading used to
  * send every finding down the fallback path, which is what produced the
- * truncated and shifted output in F02. The separator may also sit directly
+ * truncated and shifted output. The separator may also sit directly
  * against the path (`\`src/a.ts\`: \`helper()\``), which is how the model
  * usually writes the colon form. */
 const NEW_HEADING = /^\[(?<severity>P[0-3])\s*·\s*(?<impact>blocking|non-blocking)\]\s+(?<path>.+?)(?:\s*(?:—|:)\s*(?<symbol>.+))?$/;

package/dist/src/pr/findings_json.d.ts

@@ -1,6 +1,6 @@
-/** Structured review output (CORE-40 / F02).
+/** Structured review output.
  *
- * F02: findings were truncated mid-sentence (`... while \`u`) and split at the
+ * Findings were truncated mid-sentence (`... while \`u`) and split at the
  * wrong offsets, because the model's free-form Markdown was sliced by the
  * fallback parser. The fix is to have the model return JSON and generate the
  * Markdown ourselves, so a finding's boundaries can no longer be guessed from

package/dist/src/pr/findings_json.js

@@ -78,7 +78,7 @@ function asText(value) {
 }
 /** Like {@link asText} but keeps the leading indentation. A suggestion is
  * source lines with their original indentation, so trimming the left edge
- * changes the code it proposes (CORE-40). Only the outer blank lines go. */
+ * changes the code it proposes. Only the outer blank lines go. */
 function asSource(value) {
     return typeof value === "string"
         ? value.replace(/^\s*\n/, "").replace(/\s+$/, "")

package/dist/src/pr/github_revision.js

@@ -14,7 +14,7 @@ export function githubFileToRevisionFile(file) {
     const additions = Number(file.additions ?? 0);
     const deletions = Number(file.deletions ?? 0);
     const patch = String(file.patch ?? "");
-    // GitHub omits large text patches; do not treat that as binary (plan §10.7).
+    // GitHub omits large text patches; do not treat that as binary.
     const binary = false;
     return {
         path,

package/dist/src/pr/review_copy.d.ts

@@ -1,4 +1,4 @@
-/** The severity legend and the review-copy rule (CORE-83 / D11).
+/** The severity legend and the review-copy rule.
  *
  * Product text avoids the em dash and the semicolon: the docs linter rejects
  * them, and the finding parser had to accept both a `—` and a `:` heading
@@ -15,6 +15,6 @@ export declare const SEVERITY_LEGEND: ReadonlyArray<{
 /** The `## Severity` block the review text starts with. The colon keeps it
  * free of the em dash the old prompt used. */
 export declare function severitySection(): string;
-/** What the model is told about prose (CORE-83). The review body is rendered
+/** What the model is told about prose. The review body is rendered
  * by our code, not the model, so this only has to keep the fields clean. */
 export declare const REVIEW_COPY_RULE = "Write prose without the em dash or the semicolon. Use a colon or a comma instead.";

package/dist/src/pr/review_copy.js

@@ -1,4 +1,4 @@
-/** The severity legend and the review-copy rule (CORE-83 / D11).
+/** The severity legend and the review-copy rule.
  *
  * Product text avoids the em dash and the semicolon: the docs linter rejects
  * them, and the finding parser had to accept both a `—` and a `:` heading
@@ -35,6 +35,6 @@ export function severitySection() {
     const items = SEVERITY_LEGEND.map((row) => `- ${row.level}: ${row.name}: ${row.description}.`);
     return `## Severity\n\n${items.join("\n")}\n`;
 }
-/** What the model is told about prose (CORE-83). The review body is rendered
+/** What the model is told about prose. The review body is rendered
  * by our code, not the model, so this only has to keep the fields clean. */
 export const REVIEW_COPY_RULE = "Write prose without the em dash or the semicolon. Use a colon or a comma instead.";

package/dist/src/pr/reviewer.d.ts

@@ -14,6 +14,12 @@ export declare const MERMAID_GUIDANCE = "Mermaid selection and minimal syntax:\n
  * asking for a diagram only invites invented syntax. */
 export declare const NO_DIAGRAM_RULES = "Do not use Mermaid or any other diagram. Explain with prose only.";
 export declare function reviewSystemPrompt(diagrams: boolean): string;
+/** The guide block every review sends, kept as the stable head of the system
+ * prompt rather than the user prompt so a provider with prompt caching
+ * (Anthropic's `cache_control`) reads it instead of re-billing it. Nothing
+ * time-varying may enter this string — a single differing byte makes the cache
+ * miss. */
+export declare function reviewGuidesBlock(guide: string, detailed: string, codebase: string): string;
 /** Shared PR and local/remote workspace review instructions: confirm claims
  * against the indexed graph, not only the diff slice. */
 export declare const CODEGRAPH_DIFF_VERIFICATION = "Examine the changes line by line, not just file by file. A single file can\ncontain more than one independent defect, and a change that looks fine in\nisolation can be wrong once you trace what calls it or what else it affects.\nWhen a finding depends on behavior outside the changed lines, confirm it with\ncodegraph-node, codegraph-callers, codegraph-callees, codegraph-impact, and\ncodegraph-affected before reporting it. Drop or correct findings that only seem\nplausible from the diff but contradict unchanged callers, callees, or the same\npattern elsewhere in the repo. Use those tools to check blast radius and whether\na test reaches the path. Do not guess coverage or impact from the diff alone\nwhen a tool can answer. A missing regression test is not a substitute for\nidentifying the concrete input or code path that misbehaves when you can.";

package/dist/src/pr/reviewer.js

@@ -1,4 +1,5 @@
-import { OpenRouterProvider } from "../ai/openrouter.js";
+import { createAiProvider } from "../ai/provider.js";
+import { CliError, EXIT_USAGE } from "../cli/error.js";
 import { completeWithMermaidTools, } from "../ai/mermaid_loop.js";
 import { loadGuides } from "../review/guides.js";
 import { computeScope } from "./scope.js";
@@ -7,6 +8,23 @@ import { REVIEW_COPY_RULE, severitySection } from "./review_copy.js";
 import { needsSummary, READ_FULL_DIFF_TOOL, readFullDiff, summarizeDiff, } from "./diff_summary.js";
 import { numberPatch } from "./hunks.js";
 import { FINDINGS_JSON_INSTRUCTIONS, FINDINGS_JSON_SCHEMA, findingsMarkdownFromJson, } from "./findings_json.js";
+/** A model id is never guessed here. Models go stale, and a build already
+ * installed cannot fetch a fresher one, so the id to run comes from config
+ * or a flag, set at least once by whoever runs it (Murat, 2026-09-28). */
+/** The configured provider for one model. Built only when a call needs it:
+ * a provider's constructor requires a real key, which a fake-AI run never has. */
+function reviewProvider(options, model, label) {
+    const provider = createAiProvider(options, requiredModel(model, label));
+    if (!provider) {
+        throw new CliError("missing_provider", "Review needs an AI provider.", "Run co-maintainer set --ai=... --token=...", EXIT_USAGE);
+    }
+    return provider;
+}
+function requiredModel(model, label) {
+    if (model)
+        return model;
+    throw new CliError("missing_model", `No ${label} model is configured.`, `Run co-maintainer set --${label}-model=..., or pass --${label}-model=... on the command that needs it.`, EXIT_USAGE);
+}
 const MAX_REVIEW_DIFF_CHARS = 240_000;
 export const MERMAID_GUIDANCE = `Mermaid selection and minimal syntax:
 flowchart = decisions, branches, pipelines, and fallback paths;
@@ -59,6 +77,21 @@ export function reviewSystemPrompt(diagrams) {
     return `${REVIEW_ROLE}
 ${diagrams ? REVIEW_DIAGRAM_RULES : NO_DIAGRAM_RULES}`;
 }
+/** The guide block every review sends, kept as the stable head of the system
+ * prompt rather than the user prompt so a provider with prompt caching
+ * (Anthropic's `cache_control`) reads it instead of re-billing it. Nothing
+ * time-varying may enter this string — a single differing byte makes the cache
+ * miss. */
+export function reviewGuidesBlock(guide, detailed, codebase) {
+    return `REVIEW GUIDE:
+${guide}
+
+DETAILED GUIDE:
+${detailed}
+
+CODEBASE CONVENTIONS:
+${codebase || "None recorded."}`;
+}
 /** Shared PR and local/remote workspace review instructions: confirm claims
  * against the indexed graph, not only the diff slice. */
 export const CODEGRAPH_DIFF_VERIFICATION = `Examine the changes line by line, not just file by file. A single file can
@@ -78,8 +111,8 @@ function text(value, limit = 20_000) {
         ? `${result.slice(0, limit)}\n[truncated]`
         : result;
 }
-/** Turns a model reply into the Markdown every consumer already parses
- * (CORE-40 / F02). A reply that is not usable JSON is retried once with an
+/** Turns a model reply into the Markdown every consumer already parses.
+ * A reply that is not usable JSON is retried once with an
  * explicit reminder; if that also fails, the raw text is returned so the
  * legacy Markdown parser can still read it. This keeps a provider that ignores
  * `response_format` working, and never drops a review on the floor. */
@@ -219,12 +252,10 @@ export async function reviewPullRequest(client, options, usage, snapshot, ai, pr
     if (scope) {
         report(`scope resolved · own=${ownFiles.length} files · upstream=${upstreamFiles.length} files`);
     }
-    // Built only if needed: OpenRouterProvider's constructor requires a real
-    // API key, which a fake-AI test run never has.
+    // Built only if needed, see reviewProvider.
     const filesNeedSummary = ownFiles.some(({ file }) => needsSummary(Number(file.changes ?? 0), String(file.patch ?? "")));
     const lowProvider = filesNeedSummary
-        ? (ai ??
-            new OpenRouterProvider(options.aiToken ?? "", options.lowModel ?? "openai/gpt-oss-120b"))
+        ? (ai ?? reviewProvider(options, options.lowModel, "low"))
         : undefined;
     const patchByPath = new Map();
     const [ownSections, codegraphTools] = await Promise.all([
@@ -288,8 +319,7 @@ interaction if the pull request's own change above relies on or conflicts with
 one of these files, and never mark that finding blocking:
 ${upstreamListing}${unchangedListing}`;
     report(`diff prepared · ${ownPatch.length} chars${diffWasTruncated ? " · truncated for model context" : ""}`);
-    const provider = ai ??
-        new OpenRouterProvider(options.aiToken ?? "", options.highModel ?? "openai/gpt-5.6-luna");
+    const provider = ai ?? reviewProvider(options, options.highModel, "high");
     const diagrams = provider.supportsTools !== false;
     const carryBlock = extras?.carryPrompt ? `${extras.carryPrompt}\n` : "";
     const prompt = `Review this pull request against the repository's review guide and
@@ -324,15 +354,6 @@ code to the nearest numbered line.
 ${diagrams ? DIAGRAM_PROMPT_RULES : NO_DIAGRAM_RULES}
 ${FINDINGS_JSON_INSTRUCTIONS}
 
-REVIEW GUIDE:
-${guide}
-
-DETAILED GUIDE:
-${detailed}
-
-CODEBASE CONVENTIONS:
-${codebase || "None recorded."}
-
 PULL REQUEST:
 ${JSON.stringify({
         number,
@@ -349,17 +370,17 @@ ${diff}`;
     const matrix = clampImproveMatrix(options.improveMatrix);
     const request = {
         job: "review_pull_request",
-        system: reviewSystemPrompt(diagrams),
+        system: `${reviewSystemPrompt(diagrams)}\n\n${reviewGuidesBlock(guide, detailed, codebase)}`,
         prompt,
         maxTokens: 24_000 * matrix,
         reasoningEffort: "high",
         responseFormat: FINDINGS_JSON_SCHEMA,
     };
-    report(`AI request · model=${options.highModel ?? "openrouter default"} · ` +
+    report(`AI request · ${options.ai} · model=${options.highModel ?? "unset"} · ` +
         `prompt=${prompt.length} chars · maxTokens=${request.maxTokens}`);
     if (options.debug) {
         console.log(`[debug] review prompt · ${prompt.length} chars · diff=${diff.length} chars`);
-        console.log(`[debug] openrouter request · model=${options.highModel ?? "openai/gpt-5.6-luna"} · maxTokens=${request.maxTokens}`);
+        console.log(`[debug] ${options.ai} request · model=${options.highModel ?? "unset"} · maxTokens=${request.maxTokens}`);
     }
     let response = await completeWithMermaidTools(provider, request, 1, extraTools, maxToolRounds);
     if (usage)
@@ -370,9 +391,9 @@ ${diff}`;
         console.log(`\n----- INITIAL REVIEW -----\n${response.text}\n`);
     }
     if (!response.text.trim()) {
-        throw new Error("OpenRouter returned an empty review. The reasoning budget may have been exhausted");
+        throw new Error(`${options.ai} returned an empty review. The reasoning budget may have been exhausted`);
     }
-    // The model returns JSON; we render the Markdown (CORE-40 / F02). A reply
+    // The model returns JSON; we render the Markdown. A reply
     // that is not usable JSON is retried once and then falls back to the legacy
     // Markdown parser, so a provider that ignores the schema still works.
     let reviewText = await normalizeReviewResponse(provider, request, response, extraTools, maxToolRounds, usage, report, options);
@@ -402,7 +423,7 @@ ${reviewText}`,
         report(`AI improvement response · input=${response.tokensIn} tokens · ` +
             `output=${response.tokensOut} tokens`);
         if (!response.text.trim()) {
-            throw new Error(`OpenRouter returned an empty review improvement at pass ${pass - 1}`);
+            throw new Error(`${options.ai} returned an empty review improvement at pass ${pass - 1}`);
         }
         reviewText = await normalizeReviewResponse(provider, improvementRequest, response, extraTools, maxToolRounds, usage, report, options);
         if (options.debug) {
@@ -456,8 +477,7 @@ export async function reviewWorkspaceRevision(revision, options, headSha, usage,
         const changes = Number(file.changes ?? 0);
         const patch = String(file.patch ?? "");
         const lowProvider = needsSummary(changes, patch)
-            ? (ai ??
-                new OpenRouterProvider(options.aiToken ?? "", options.lowModel ?? "openai/gpt-oss-120b"))
+            ? (ai ?? reviewProvider(options, options.lowModel, "low"))
             : undefined;
         if (!lowProvider)
             return `FILE: ${path}\n${filePatch(file)}`;
@@ -491,8 +511,7 @@ export async function reviewWorkspaceRevision(revision, options, headSha, usage,
             .join("\n")}`
         : "";
     const carryBlock = extras?.carryPrompt ? `${extras.carryPrompt}\n` : "";
-    const provider = ai ??
-        new OpenRouterProvider(options.aiToken ?? "", options.highModel ?? "openai/gpt-5.6-luna");
+    const provider = ai ?? reviewProvider(options, options.highModel, "high");
     const diagrams = provider.supportsTools !== false;
     const prompt = `Review these local changes against the repository's review guide and
 codebase conventions. Find only actionable code-level violations supported by
@@ -504,15 +523,6 @@ ${CODEGRAPH_DIFF_VERIFICATION}
 ${diagrams ? DIAGRAM_PROMPT_RULES : NO_DIAGRAM_RULES}
 ${FINDINGS_JSON_INSTRUCTIONS}
 
-REVIEW GUIDE:
-${guide}
-
-DETAILED GUIDE:
-${detailed}
-
-CODEBASE CONVENTIONS:
-${codebase || "None recorded."}
-
 WORKSPACE:
 ${JSON.stringify({
         branch: revision.baseLabel,
@@ -524,7 +534,7 @@ ${ownDiff}${unchangedListing}`;
     const matrix = clampImproveMatrix(options.improveMatrix);
     const request = {
         job: "review_local",
-        system: reviewSystemPrompt(diagrams),
+        system: `${reviewSystemPrompt(diagrams)}\n\n${reviewGuidesBlock(guide, detailed, codebase)}`,
         prompt,
         maxTokens: 24_000 * matrix,
         reasoningEffort: "high",
@@ -535,7 +545,7 @@ ${ownDiff}${unchangedListing}`;
     if (usage)
         await usage(response);
     if (!response.text.trim()) {
-        throw new Error("OpenRouter returned an empty review");
+        throw new Error(`${options.ai} returned an empty review`);
     }
     let reviewText = await normalizeReviewResponse(provider, request, response, extraTools, maxToolRounds, usage, report, options);
     for (let pass = 2; pass <= matrix; pass++) {

package/dist/src/remote/client.d.ts

@@ -1,4 +1,8 @@
 import type { ReviewCliArgs } from "../cli/review_args.ts";
+/** A plain-http, non-local host means the BYOK key travels in the clear.
+ * Pulled out as a pure function so the rule is unit-testable
+ * without standing up a plain-http fake server. */
+export declare function byokHttpWarning(host: string): string | null;
 export declare function runRemoteReview(cli: ReviewCliArgs & {
     mode: "remote";
 }): Promise<void>;

package/dist/src/remote/client.js

@@ -1,8 +1,9 @@
 import { VERSION } from "../version.js";
 import { CliError, EXIT_USAGE, exitWith } from "../cli/error.js";
 import { formatHumanReview, humanFindingsFromJson, reviewExitCodeFromJsonFindings, } from "../cli/review_result.js";
-import { baseUrl, die, readApiError, remoteFetch } from "./http.js";
+import { baseUrl, die, readApiError, remoteFetch, remoteFromEnv, } from "./http.js";
 import { readConfig, writeUserConfig } from "../config.js";
+import { getEnv } from "../util/runtime.js";
 import { prepareLocalCodegraph } from "../local/codegraph_prepare.js";
 import { canPrompt } from "../tools/codegraph.js";
 import { runRemoteToolCalls, toolHandlerMap, } from "./client_tools.js";
@@ -11,19 +12,42 @@ import { runCommand } from "../pr/checkout.js";
 import { assertGitQuiet, currentBranch, detectRemoteRepo, gitRoot, } from "../local/git_ops.js";
 import { buildLocalRevision, mergeBase, resolveBaseRef, } from "../local/git_revision.js";
 import { withCliLogsToStderr } from "../util/log.js";
-import { printRunSummary, summaryFromMetrics } from "../util/run_summary.js";
+import { printRunSummary } from "../util/run_summary.js";
+import { emitGithubOutput, neutralizeCommands } from "../cli/review_github.js";
+import { costReasonText } from "../util/cost.js";
 import { setCliInteractive } from "../cli/args.js";
 import { MIN_SERVER_SCHEMA, REMOTE_CLI_UPGRADE_COMMAND, REMOTE_SCHEMA_VERSION, } from "./schema.js";
+const LOCAL_BYOK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1"]);
+/** A plain-http, non-local host means the BYOK key travels in the clear.
+ * Pulled out as a pure function so the rule is unit-testable
+ * without standing up a plain-http fake server. */
+export function byokHttpWarning(host) {
+    const url = new URL(baseUrl(host));
+    if (url.protocol !== "http:" || LOCAL_BYOK_HOSTNAMES.has(url.hostname)) {
+        return null;
+    }
+    return (`Warning: sending your AI key over plain http to ${url.hostname}. ` +
+        "Anyone on the network path can read it.");
+}
 export async function runRemoteReview(cli) {
     const config = readConfig();
-    // Inline flags win over the saved config for this run only (CORE-25), so a
+    // Inline flags win over the saved config for this run only, so a
     // one-off review does not have to be written to disk first.
-    const host = cli.remoteHost ?? config.remoteHost;
-    const token = cli.remoteToken ?? config.remoteToken;
+    const fromEnv = remoteFromEnv();
+    const host = cli.remoteHost ?? fromEnv.host ?? config.remoteHost;
+    const token = cli.remoteToken ?? fromEnv.token ?? config.remoteToken;
     if (!host || !token) {
         die("remote_not_configured", "Remote review is not configured.", "co-maintainer config set remote-host https://your-server " +
             "&& co-maintainer config set remote-token <token> " +
-            "(or pass --remote-host=... --remote-token=... for one run)");
+            "(or pass --remote-host=... --remote-token=... for one run, or set CM_REMOTE_HOST and CM_REMOTE_TOKEN)");
+    }
+    // The client's own AI key, used only when this run turns BYOK
+    // on. The env var wins so a hosted CI runner can supply it without writing
+    // config, mirroring how CM_REMOTE_BYOK_POLICY overrides the server side.
+    const byokKey = getEnv("CM_REMOTE_BYOK") ?? config.remoteByok;
+    const byokEnabled = cli.remoteByok ?? config.remoteByokDefault ?? false;
+    if (byokEnabled && !byokKey) {
+        die("remote_byok_not_configured", "No BYOK key is set.", "co-maintainer config set remote-byok <key>");
     }
     setCliInteractive(!cli.json);
     await withCliLogsToStderr(async () => {
@@ -76,6 +100,25 @@ export async function runRemoteReview(cli) {
         if (hs.schemaVersion < MIN_SERVER_SCHEMA) {
             die("server_too_old", "The dashboard server is too old for this CLI.", undefined, 4);
         }
+        // Never silently fall back to the server's own key. Each of
+        // these is a mismatch between what this run wants and what the server
+        // will do, so all four are a hard stop.
+        const serverSupportsByok = hs.features?.includes("byok") ?? false;
+        if (byokEnabled && !serverSupportsByok) {
+            die("remote_byok_unsupported", `This server (version ${hs.serverVersion}) does not support your own key.`, "Upgrade the server or run without --remote-byok.");
+        }
+        if (byokEnabled && hs.byok?.policy === "off") {
+            die("remote_byok_rejected", "This server does not accept your own key.");
+        }
+        if (serverSupportsByok && hs.byok?.policy === "require" && !byokEnabled) {
+            die("remote_byok_required", "This server requires your own key.", "co-maintainer review --remote --remote-byok");
+        }
+        if (byokEnabled && !cli.json) {
+            const warning = byokHttpWarning(host);
+            if (warning)
+                console.error(warning);
+            console.error(`Using your own key with the server's provider: ${hs.ai?.provider ?? "unknown"}.`);
+        }
         const hostKey = baseUrl(host);
         const shown = config.remoteNoticeShownFor ?? [];
         if (!shown.includes(hostKey) && !cli.json) {
@@ -89,7 +132,7 @@ export async function runRemoteReview(cli) {
             gitRoot: root,
             enabled: !cli.disableCodegraph,
             allowInstall: cli.allowToolInstall,
-            // `--json` must stay machine-readable; `canPrompt` adds TTY and CI (F01).
+            // `--json` must stay machine-readable; `canPrompt` adds TTY and CI.
             interactive: !cli.json && canPrompt(),
         });
         const localTools = toolHandlerMap(codegraphPrep.tools);
@@ -111,6 +154,9 @@ export async function runRemoteReview(cli) {
                 files: built.revision.files,
             },
             capabilities: { tools: capabilityTools },
+            // Only present when this run turned BYOK on; `byokKey` is
+            // known to be set here because of the earlier `byokEnabled` guard.
+            ...(byokEnabled ? { byok: { key: byokKey } } : {}),
         };
         const serialized = JSON.stringify(submitBody);
         if (serialized.length > hs.limits.maxBodyBytes) {
@@ -143,14 +189,33 @@ export async function runRemoteReview(cli) {
             const payload = (await sync.json());
             for (const line of payload.logs ?? []) {
                 afterLogSeq = Math.max(afterLogSeq, line.seq);
-                if (!cli.json)
-                    console.error(line.message);
+                if (!cli.json) {
+                    console.error(cli.output === "github"
+                        ? neutralizeCommands(line.message)
+                        : line.message);
+                }
             }
             if (payload.toolCalls?.length) {
                 toolResults = await runRemoteToolCalls(payload.toolCalls, localTools);
                 continue;
             }
             if (payload.status === "done" && payload.result) {
+                const findings = (payload.result.findings ?? []);
+                const usage = payload.result.usage;
+                const known = usage !== undefined &&
+                    usage.costUsd !== null &&
+                    usage.costUsd !== undefined;
+                const run = usage
+                    ? {
+                        durationMs: performance.now() - reviewStarted,
+                        tokensIn: usage.tokensIn ?? 0,
+                        tokensOut: usage.tokensOut ?? 0,
+                        costUsd: known ? usage.costUsd : null,
+                        ...(!known && usage.costNote
+                            ? { costNote: costReasonText(usage.costNote) }
+                            : {}),
+                    }
+                    : undefined;
                 if (cli.json) {
                     console.log(JSON.stringify({
                         schemaVersion: 1,
@@ -159,9 +224,14 @@ export async function runRemoteReview(cli) {
                         ...payload.result,
                     }));
                 }
+                else if (cli.output === "github") {
+                    emitGithubOutput({
+                        title: `${repo} · ${branch} (remote)`,
+                        findings: humanFindingsFromJson(findings),
+                        run,
+                    });
+                }
                 else {
-                    const findings = (payload.result.findings ??
-                        []);
                     const resultGuide = payload.result.guide;
                     const resultCodegraph = payload.result.codegraph;
                     console.log("\n" +
@@ -172,22 +242,13 @@ export async function runRemoteReview(cli) {
                             findings: humanFindingsFromJson(findings),
                         }) +
                         "\n");
-                    const usage = payload.result.usage;
-                    if (usage) {
-                        printRunSummary(summaryFromMetrics({
-                            calls: 0,
-                            tokensIn: usage.tokensIn ?? 0,
-                            tokensOut: usage.tokensOut ?? 0,
-                            cost: usage.costUsd ?? 0,
-                            costKnown: usage.costUsd !== null && usage.costUsd !== undefined,
-                        }, performance.now() - reviewStarted));
-                    }
+                    if (run)
+                        printRunSummary(run);
                 }
-                const findings = (payload.result.findings ?? []);
                 exitWith(reviewExitCodeFromJsonFindings(findings));
                 // `done` is terminal. Without this return the loop polls `sync` again
                 // and, since the server keeps reporting the same finished job, the
-                // client reprints the result and re-requests forever (CORE-25).
+                // client reprints the result and re-requests forever.
                 return;
             }
             if (payload.status === "failed" || payload.status === "canceled") {

package/dist/src/remote/fixtures.js

@@ -1,4 +1,4 @@
-/** Fixture directory hashing for plan §15.3.
+/** Fixture directory hashing.
  *
  * The hash exists to catch schema/content drift in the wire fixtures, not
  * line-ending drift, so `\r\n` is normalized to `\n` before hashing. Without

package/dist/src/remote/http.d.ts

@@ -1,4 +1,13 @@
-/** A usage error the CLI prints with its hint and exit code (CORE-12). */
+/** Where the remote server is, as an environment variable can say it.
+ * A CI job has no config file, and a token on the command line
+ * ends up in the process list, so `CM_REMOTE_HOST` and `CM_REMOTE_TOKEN` are
+ * read here. An empty value counts as unset, so a workflow secret that did not
+ * resolve falls through to the "not configured" error instead of a blank host. */
+export declare function remoteFromEnv(): {
+    host?: string;
+    token?: string;
+};
+/** A usage error the CLI prints with its hint and exit code. */
 export declare function die(code: string, message: string, hint?: string, exitCode?: number): never;
 export declare function baseUrl(host: string): string;
 export declare function remoteFetch(host: string, token: string, path: string, init: RequestInit): Promise<Response>;