co-maintainer 0.4.13 → 0.5.0-beta.1

package/dist/src/remote/client.js

@@ -1,53 +1,33 @@
 import { VERSION } from "../version.js";
-import { printLocalReview } from "../cli/review_output.js";
-import { formatHumanJsonFindings, reviewExitCodeFromJsonFindings, } from "../cli/review_result.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 { readConfig, writeUserConfig } from "../config.js";
 import { prepareLocalCodegraph } from "../local/codegraph_prepare.js";
+import { canPrompt } from "../tools/codegraph.js";
 import { runRemoteToolCalls, toolHandlerMap, } from "./client_tools.js";
 import { REMOTE_KNOWN_TOOL_NAMES } from "./schema.js";
 import { runCommand } from "../pr/checkout.js";
-import { assertGitQuiet, currentBranch, detectRemoteRepo, gitRoot, ReviewCliError, } from "../local/git_ops.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 { setCliInteractive } from "../cli/args.js";
 import { MIN_SERVER_SCHEMA, REMOTE_CLI_UPGRADE_COMMAND, REMOTE_SCHEMA_VERSION, } from "./schema.js";
-function die(code, message, hint, exitCode = 2) {
-    throw new ReviewCliError(code, message, hint, exitCode);
-}
-function baseUrl(host) {
-    const trimmed = host.trim().replace(/\/+$/, "");
-    if (!/^https?:\/\//i.test(trimmed)) {
-        die("remote_not_configured", "remoteHost must be an absolute http(s) URL.", "co-maintainer set --remote-host=https://your-server");
-    }
-    return trimmed;
-}
-async function remoteFetch(host, token, path, init) {
-    const url = `${baseUrl(host)}${path}`;
-    const headers = new Headers(init.headers);
-    headers.set("authorization", `Bearer ${token}`);
-    if (init.body && !headers.has("content-type")) {
-        headers.set("content-type", "application/json");
-    }
-    return await fetch(url, { ...init, headers });
-}
-async function readApiError(response) {
-    try {
-        const body = await response.json();
-        return String(body.error?.message ?? response.statusText);
-    }
-    catch {
-        return response.statusText;
-    }
-}
 export async function runRemoteReview(cli) {
     const config = readConfig();
-    const host = config.remoteHost;
-    const token = config.remoteToken;
+    // Inline flags win over the saved config for this run only (CORE-25), 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;
     if (!host || !token) {
-        die("remote_not_configured", "Remote review is not configured.", "co-maintainer set --remote-host=... --remote-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)");
     }
     setCliInteractive(!cli.json);
     await withCliLogsToStderr(async () => {
+        const reviewStarted = performance.now();
         const root = await gitRoot(process.cwd());
         await assertGitQuiet(root);
         const repo = await detectRemoteRepo(root, cli.repoOverride);
@@ -76,7 +56,7 @@ export async function runRemoteReview(cli) {
             else {
                 console.log("No changes to review.");
             }
-            process.exit(0);
+            exitWith(0);
         }
         const handshake = await remoteFetch(host, token, "/api/remote/handshake", {
             method: "POST",
@@ -109,7 +89,8 @@ export async function runRemoteReview(cli) {
             gitRoot: root,
             enabled: !cli.disableCodegraph,
             allowInstall: cli.allowToolInstall,
-            interactive: !cli.json,
+            // `--json` must stay machine-readable; `canPrompt` adds TTY and CI (F01).
+            interactive: !cli.json && canPrompt(),
         });
         const localTools = toolHandlerMap(codegraphPrep.tools);
         const capabilityTools = [...localTools.keys()]
@@ -181,14 +162,33 @@ export async function runRemoteReview(cli) {
                 else {
                     const findings = (payload.result.findings ??
                         []);
-                    const summary = payload.result.summary;
-                    const summaryLine = summary
-                        ? `${summary.new ?? 0} new · ${summary.open ?? 0} open · ${summary.closed ?? 0} closed · ${summary.blocking ?? 0} blocking`
-                        : "";
-                    printLocalReview(`co-maintainer review · ${repo} · ${branch} (remote)\n${summaryLine}`, formatHumanJsonFindings(findings));
+                    const resultGuide = payload.result.guide;
+                    const resultCodegraph = payload.result.codegraph;
+                    console.log("\n" +
+                        formatHumanReview({
+                            title: `co-maintainer review · ${repo} · ${branch} (remote)`,
+                            guideBuiltAt: resultGuide?.builtAt ?? null,
+                            codegraphState: resultCodegraph?.state ?? null,
+                            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));
+                    }
                 }
                 const findings = (payload.result.findings ?? []);
-                process.exit(reviewExitCodeFromJsonFindings(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).
+                return;
             }
             if (payload.status === "failed" || payload.status === "canceled") {
                 die(payload.abort?.reason ?? "remote_failed", payload.abort?.message ?? "Remote review did not complete.");

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

@@ -0,0 +1,5 @@
+/** A usage error the CLI prints with its hint and exit code (CORE-12). */
+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>;
+export declare function readApiError(response: Response): Promise<string>;

package/dist/src/remote/http.js

@@ -0,0 +1,49 @@
+/** Shared HTTPS plumbing for the remote endpoints (CORE-25, CORE-44).
+ *
+ * `review --remote` and `view --remote` talk to the same server with the same
+ * bearer token, so the base URL, the token header and the explanations for a
+ * rejected token or an unreachable host live here rather than in the review
+ * client alone. */
+import { CliError, EXIT_USAGE, networkFailure } from "../cli/error.js";
+/** A usage error the CLI prints with its hint and exit code (CORE-12). */
+export function die(code, message, hint, exitCode = EXIT_USAGE) {
+    throw new CliError(code, message, hint, exitCode);
+}
+export function baseUrl(host) {
+    const trimmed = host.trim().replace(/\/+$/, "");
+    if (!/^https?:\/\//i.test(trimmed)) {
+        die("remote_not_configured", "remoteHost must be an absolute http(s) URL.", "co-maintainer config set remote-host https://your-server");
+    }
+    return trimmed;
+}
+export async function remoteFetch(host, token, path, init) {
+    const url = `${baseUrl(host)}${path}`;
+    const headers = new Headers(init.headers);
+    headers.set("authorization", `Bearer ${token}`);
+    if (init.body && !headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+    }
+    try {
+        const response = await fetch(url, { ...init, headers });
+        // The server's 401 text is `invalid or missing token`, which does not say
+        // where the token comes from or how to get another one (CORE-12).
+        if (response.status === 401 || response.status === 403) {
+            die("remote_token_rejected", `The server at ${baseUrl(host)} rejected the remote review token.`, "Create one in its dashboard under Settings, Remote review tokens.", EXIT_USAGE);
+        }
+        return response;
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw networkFailure(url, error);
+    }
+}
+export async function readApiError(response) {
+    try {
+        const body = await response.json();
+        return String(body.error?.message ?? response.statusText);
+    }
+    catch {
+        return response.statusText;
+    }
+}

package/dist/src/remote/server/guides.d.ts

@@ -0,0 +1,22 @@
+export type RemoteGuide = {
+    kind: string;
+    file: string;
+    size: number;
+    builtAt: string;
+    content: string;
+};
+/** Canonicalizes `owner/repo` from the query string. A value that escapes is
+ * refused before any directory is touched, the same guard the revision payload
+ * uses. */
+export declare function parseRepoQuery(value: string | null): {
+    repo: string;
+} | {
+    error: string;
+};
+/** Every file in `repo`'s guide directory, in `GUIDES` order first so the
+ * reading order matches a local `view`, with an unexpected file (an older
+ * name, a hand-written note) last. */
+export declare function readRemoteGuides(repo: string): Promise<{
+    guides: RemoteGuide[];
+    guideBuiltAt: string | null;
+}>;

package/dist/src/remote/server/guides.js

@@ -0,0 +1,81 @@
+/** `GET /api/remote/guides?repo=owner/repo` — read a repository's guides with a
+ * remote token (CORE-44).
+ *
+ * This is what `view --remote` calls. It is a read-only addition: no existing
+ * route changes, and it uses the same bearer model the review endpoints use
+ * (valid token, active token, lockout after repeated failures). The response
+ * carries every file in the guide directory with its size and build date, so
+ * the CLI prints the same headers a local `view` prints without a round trip
+ * per file. */
+import { reposDir } from "../../config.js";
+import { loadGuides } from "../../review/guides.js";
+import { readDir, readTextFile, stat } from "../../util/runtime.js";
+import { validateRemotePath } from "../validate.js";
+/** The four generated guides, in the order a reader wants them (CORE-23). */
+const GUIDES = [
+    { kind: "skill", file: "SKILL.md" },
+    { kind: "codebase", file: "CODEBASE.md" },
+    { kind: "review-guide", file: "PR_REVIEW_GUIDE.md" },
+    { kind: "detailed-guide", file: "PR_REVIEW_DETAILED_GUIDE.md" },
+];
+/** Canonicalizes `owner/repo` from the query string. A value that escapes is
+ * refused before any directory is touched, the same guard the revision payload
+ * uses. */
+export function parseRepoQuery(value) {
+    if (!value)
+        return { error: "repo: required" };
+    if (!/^[^/]+\/[^/]+$/.test(value)) {
+        return { error: "repo: must be owner/repo" };
+    }
+    const pathErr = validateRemotePath("repo", value);
+    if (pathErr)
+        return { error: pathErr };
+    return { repo: value };
+}
+/** Every file in `repo`'s guide directory, in `GUIDES` order first so the
+ * reading order matches a local `view`, with an unexpected file (an older
+ * name, a hand-written note) last. */
+export async function readRemoteGuides(repo) {
+    const loaded = await loadGuides(repo);
+    const byFile = new Map([
+        ["PR_REVIEW_GUIDE.md", loaded.shortGuide],
+        ["PR_REVIEW_DETAILED_GUIDE.md", loaded.detailed],
+        ["CODEBASE.md", loaded.codebase],
+        ["SKILL.md", loaded.skill],
+    ]);
+    const dir = `${reposDir()}/${repo}`;
+    const names = [];
+    try {
+        for await (const entry of readDir(dir)) {
+            if (entry.isFile)
+                names.push(entry.name);
+        }
+    }
+    catch {
+        // No directory: `loadGuides` already returned empty strings, so the caller
+        // gets an empty list rather than an error.
+        return { guides: [], guideBuiltAt: loaded.guideBuiltAt };
+    }
+    const order = (name) => {
+        const index = GUIDES.findIndex((guide) => guide.file === name);
+        return index === -1 ? GUIDES.length : index;
+    };
+    const guides = [];
+    for (const file of names.sort((a, b) => order(a) - order(b) || a.localeCompare(b))) {
+        try {
+            const info = await stat(`${dir}/${file}`);
+            guides.push({
+                kind: GUIDES.find((guide) => guide.file === file)?.kind ?? "other",
+                file,
+                size: info.size,
+                builtAt: info.mtime.toISOString(),
+                content: byFile.get(file) ?? (await readTextFile(`${dir}/${file}`)),
+            });
+        }
+        catch {
+            // The file vanished between the listing and the read: skip it rather
+            // than fail the whole directory.
+        }
+    }
+    return { guides, guideBuiltAt: loaded.guideBuiltAt };
+}

package/dist/src/remote/server/routes.js

@@ -11,6 +11,7 @@ import { MIN_CLIENT_SCHEMA, REMOTE_CLI_UPGRADE_COMMAND, REMOTE_MAX_BODY_BYTES, R
 import { readBoundedJson } from "./body.js";
 import { submitRemoteReview } from "../../services/remote_review.js";
 import { handleRemoteCancel, handleRemoteSync } from "./sync.js";
+import { parseRepoQuery, readRemoteGuides } from "./guides.js";
 import { validateHandshakeRequest, validateSubmitRequest, } from "../validate.js";
 import { stat } from "../../util/runtime.js";
 const REPO_UNAVAILABLE = "Sorry, we could not access this repository.";
@@ -128,10 +129,33 @@ async function handleSubmit(request, ip) {
         reviewId: result.reviewId,
     }, { status: 202 });
 }
+async function handleGuides(request, ip, url) {
+    const auth = await authenticateRemote(request, ip);
+    if (auth instanceof Response)
+        return auth;
+    const parsed = parseRepoQuery(url.searchParams.get("repo"));
+    if ("error" in parsed) {
+        return errorResponse(400, "bad_request", parsed.error);
+    }
+    const repoRow = findRepoByFullName(parsed.repo);
+    if (!repoRow || repoRow.active !== 1) {
+        return errorResponse(404, "repo_unavailable", REPO_UNAVAILABLE);
+    }
+    const { guides, guideBuiltAt } = await readRemoteGuides(repoRow.full_name);
+    return Response.json({
+        schemaVersion: REMOTE_SCHEMA_VERSION,
+        repo: { fullName: repoRow.full_name },
+        guideBuiltAt,
+        guides,
+    });
+}
 export async function handleRemoteRoute(request, url, remoteAddr) {
     if (url.pathname === "/api/remote/handshake" && request.method === "POST") {
         return await handleHandshake(request, remoteAddr);
     }
+    if (url.pathname === "/api/remote/guides" && request.method === "GET") {
+        return await handleGuides(request, remoteAddr, url);
+    }
     if (url.pathname === "/api/remote/reviews" && request.method === "POST") {
         return await handleSubmit(request, remoteAddr);
     }

package/dist/src/review/blocking.d.ts

@@ -0,0 +1,35 @@
+/** How a review decides a blocking finding (CORE-41, plan decision 2 option C).
+ *
+ * F19: the same pull request was reviewed twice, the same P2 finding came back
+ * `non-blocking` the first time and `blocking` the second, and the exit code
+ * changed because the model's own label moved. `model` keeps that behavior
+ * (the model decides) because it is what 0.4.13 shipped; `severity` ignores
+ * the model's label and uses a fixed threshold, so the same finding set always
+ * yields the same exit code.
+ *
+ * This is the one place that answers "does this finding block". Every review
+ * path — local, PR, remote and the GitHub App — calls it, so the modes cannot
+ * drift apart.
+ */
+export type ReviewBlocking = "model" | "severity";
+export declare const DEFAULT_REVIEW_BLOCKING: ReviewBlocking;
+/** Reads a config, flag or env value. Anything but `severity` is the default,
+ * so an unset or mistyped value never silently tightens the rule. */
+export declare function reviewBlockingFrom(value: unknown): ReviewBlocking;
+/** One finding, in the shape any of the review paths happens to have. Only
+ * `severity` is always available; the other two describe the model's own
+ * claim, which `severity` mode ignores. */
+export type BlockingInput = {
+    severity?: string;
+    /** The model's structured `blocking` field, when the answer was JSON. */
+    blocked?: boolean;
+    /** The heading or title text, when the answer came from Markdown. */
+    text?: string;
+};
+/** Whether one finding blocks under the configured rule.
+
+ * `model`: the model decides. A P0 always blocks even when the model labeled
+ * it otherwise, which is the 0.4.13 rule and is kept so no existing review
+ * changes its exit code.
+ * `severity`: P0 and P1 block, P2 and P3 do not, whatever the model said. */
+export declare function isBlocking(mode: ReviewBlocking, finding: BlockingInput): boolean;

package/dist/src/review/blocking.js

@@ -0,0 +1,45 @@
+/** How a review decides a blocking finding (CORE-41, plan decision 2 option C).
+ *
+ * F19: the same pull request was reviewed twice, the same P2 finding came back
+ * `non-blocking` the first time and `blocking` the second, and the exit code
+ * changed because the model's own label moved. `model` keeps that behavior
+ * (the model decides) because it is what 0.4.13 shipped; `severity` ignores
+ * the model's label and uses a fixed threshold, so the same finding set always
+ * yields the same exit code.
+ *
+ * This is the one place that answers "does this finding block". Every review
+ * path — local, PR, remote and the GitHub App — calls it, so the modes cannot
+ * drift apart.
+ */
+export const DEFAULT_REVIEW_BLOCKING = "model";
+/** Reads a config, flag or env value. Anything but `severity` is the default,
+ * so an unset or mistyped value never silently tightens the rule. */
+export function reviewBlockingFrom(value) {
+    return value === "severity" ? "severity" : DEFAULT_REVIEW_BLOCKING;
+}
+/** The model's claim as written into a heading: `[P2 · non-blocking] …`. An
+ * unrecognised heading says nothing, rather than guessing "not blocking". */
+function claimFromText(text) {
+    if (/non-blocking\]/i.test(text))
+        return false;
+    if (/·\s*blocking\]/i.test(text))
+        return true;
+    return undefined;
+}
+/** Whether one finding blocks under the configured rule.
+
+ * `model`: the model decides. A P0 always blocks even when the model labeled
+ * it otherwise, which is the 0.4.13 rule and is kept so no existing review
+ * changes its exit code.
+ * `severity`: P0 and P1 block, P2 and P3 do not, whatever the model said. */
+export function isBlocking(mode, finding) {
+    const severity = finding.severity?.toUpperCase();
+    if (mode === "severity") {
+        return severity === "P0" || severity === "P1";
+    }
+    if (severity === "P0")
+        return true;
+    if (finding.blocked === true)
+        return true;
+    return finding.text ? claimFromText(finding.text) === true : false;
+}

package/dist/src/review/carry_over.d.ts

@@ -45,6 +45,17 @@ export declare function relocate(anchorText: string | null, oldFrom: number, pat
     from: number;
     to: number;
 } | null;
+/** CORE-42 / F03: a guide rebuilt after the previous review invalidates that
+ * review's verdicts, its "unchanged" suppression and its open findings — they
+ * were all judged against the old rules. Such a run starts fresh instead:
+ * every file is scanned again and old findings are no longer carried over.
+ *
+ * `previousBuiltAt` is the guide's own build time as of that review. A
+ * previous review that never recorded one (a snapshot written before CORE-42)
+ * counts as rebuilt too: re-scanning once is cheaper than letting a stale
+ * verdict mask a new violation. With no current time there is nothing to
+ * compare, so nothing is treated as rebuilt. */
+export declare function guideRebuiltSince(previousBuiltAt: string | null, currentBuiltAt: string | null): boolean;
 export declare function classifyCarryItems(previous: CarryPrevious, current: Revision, visiblePaths: Set<string>, currentGuideBuiltAt: string | null): CarryItem[];
 export declare function buildCarryPromptSection(items: CarryItem[], current: Revision): string;
 export type PreviousVerdict = {
@@ -56,7 +67,7 @@ export type PreviousVerdict = {
 };
 export declare function parsePreviousVerdicts(markdown: string): PreviousVerdict[];
 export declare function findingsMarkdownForParse(markdown: string): string;
-export declare function resolveCarryOutcomes(items: CarryItem[], current: Revision, visiblePaths: Set<string>, verdicts: PreviousVerdict[], parsedNew: ParsedFinding[], currentGuideBuiltAt: string | null, previous: CarryPrevious): ResolvedFinding[];
+export declare function resolveCarryOutcomes(items: CarryItem[], current: Revision, visiblePaths: Set<string>, verdicts: PreviousVerdict[], parsedNew: ParsedFinding[]): ResolvedFinding[];
 export declare function incrementalDiffPaths(current: Revision, previousFiles: RevisionFile[] | null): {
     changed: RevisionFile[];
     unchanged: string[];

package/dist/src/review/carry_over.js

@@ -1,6 +1,6 @@
 import { spansOverlap } from "../pr/rounds.js";
 import { rightLines } from "../pr/hunks.js";
-import { normalizeAnchor, normalizeBody, normalizePath, revisionFilesEquivalent, resolvePathAfterRename, } from "./revision.js";
+import { normalizeAnchor, normalizePath, revisionFilesEquivalent, resolvePathAfterRename, } from "./revision.js";
 export function anchorTextFromPatch(patch, from, to) {
     const lines = rightLines(patch);
     const low = Math.min(from, to);
@@ -70,6 +70,28 @@ export function relocate(anchorText, oldFrom, patch) {
 function guideChanged(previous, currentGuideBuiltAt) {
     return (previous.guideBuiltAt ?? "") !== (currentGuideBuiltAt ?? "");
 }
+/** CORE-42 / F03: a guide rebuilt after the previous review invalidates that
+ * review's verdicts, its "unchanged" suppression and its open findings — they
+ * were all judged against the old rules. Such a run starts fresh instead:
+ * every file is scanned again and old findings are no longer carried over.
+ *
+ * `previousBuiltAt` is the guide's own build time as of that review. A
+ * previous review that never recorded one (a snapshot written before CORE-42)
+ * counts as rebuilt too: re-scanning once is cheaper than letting a stale
+ * verdict mask a new violation. With no current time there is nothing to
+ * compare, so nothing is treated as rebuilt. */
+export function guideRebuiltSince(previousBuiltAt, currentBuiltAt) {
+    if (!currentBuiltAt)
+        return false;
+    if (!previousBuiltAt)
+        return true;
+    const before = Date.parse(previousBuiltAt);
+    const after = Date.parse(currentBuiltAt);
+    if (!Number.isFinite(before) || !Number.isFinite(after)) {
+        return previousBuiltAt !== currentBuiltAt;
+    }
+    return after > before;
+}
 export function classifyCarryItems(previous, current, visiblePaths, currentGuideBuiltAt) {
     const currentByPath = new Map(current.files.map((file) => [normalizePath(file.path), file]));
     const items = [];
@@ -86,7 +108,6 @@ export function classifyCarryItems(previous, current, visiblePaths, currentGuide
         const prevFile = finding.path
             ? previous.files.find((f) => normalizePath(f.path) === normalizePath(finding.path))
             : undefined;
-        const prevPatch = prevFile?.patch ?? "";
         const sameBody = Boolean(prevFile && file && revisionFilesEquivalent(prevFile, file));
         if (!finding.path) {
             klass = "unverifiable";
@@ -178,12 +199,17 @@ export function buildCarryPromptSection(items, current) {
     if (verify.length === 0 && unchanged.length === 0)
         return "";
     const lines = [
-        "PREVIOUS FINDINGS:",
-        "These were raised by an earlier review of this same change. For each one",
-        "listed under VERIFY, decide whether the code in the DIFF still has the",
-        'problem. Report every decision in a final "## Previous findings" section,',
-        'one line per id, exactly as "- F1: open path:from-to" or "- F1: closed".',
-        'Do not repeat an open previous finding under "## Findings".',
+        "PREVIOUS FINDINGS (this run has two separate jobs):",
+        "1. Scan the DIFF from scratch for every actionable violation under the",
+        "   current review guide, exactly as a first review would. Do not let the",
+        "   list below shorten or replace that scan. A changed file can contain a",
+        "   new finding even when a previous finding already covers its location.",
+        "2. For each entry under VERIFY, decide whether the code in the DIFF still",
+        "   has that problem. Report every decision in a final section headed",
+        '   exactly "## Previous findings", one line per id, exactly as',
+        '   "- F1: open path:from-to" or "- F1: closed".',
+        'Do not repeat an open previous finding under "## Findings"; report there',
+        "only findings from job 1 that are not already covered below.",
         "",
     ];
     if (verify.length) {
@@ -219,7 +245,7 @@ export function findingsMarkdownForParse(markdown) {
     const cut = markdown.search(/^## Previous findings\b/im);
     return cut === -1 ? markdown : markdown.slice(0, cut);
 }
-export function resolveCarryOutcomes(items, current, visiblePaths, verdicts, parsedNew, currentGuideBuiltAt, previous) {
+export function resolveCarryOutcomes(items, current, visiblePaths, verdicts, parsedNew) {
     const verdictByPromptId = new Map(verdicts.map((v) => [v.id, v]));
     const promptIds = new Map();
     let seq = 0;

package/dist/src/review/engine.d.ts

@@ -9,5 +9,6 @@ type ProgressSink = (message: string) => void;
 export declare function runReviewEngine(client: GitHubClient, options: Options, usage?: UsageSink, snapshot?: Snapshot, ai?: AiProvider, progress?: ProgressSink, extras?: ReviewExtras): Promise<AiResponse & {
     visiblePaths: string[];
     guideBuiltAt: string | null;
+    codegraphState: "used" | "disabled" | "unavailable";
 }>;
 export {};

package/dist/src/review/guides.js

@@ -1,7 +1,7 @@
 import { reposDir } from "../config.js";
 import { getRepo } from "../store/repos.js";
 import { withKeyedLock } from "../util/keyed_lock.js";
-import { readTextFile } from "../util/runtime.js";
+import { readTextFile, stat } from "../util/runtime.js";
 export function knowledgeLockKey(repo) {
     return `knowledge:${repo}`;
 }
@@ -13,6 +13,29 @@ async function readGuideFile(repo, name) {
         return "";
     }
 }
+/** When the guides were generated, taken from the files themselves when this
+ * process has no `repos` row (a plain local `review` never opens app.db).
+ * The newest mtime wins, so rewriting any guide file counts as a rebuild. */
+async function guideFilesBuiltAt(repo) {
+    const names = [
+        "PR_REVIEW_GUIDE.md",
+        "PR_REVIEW_DETAILED_GUIDE.md",
+        "CODEBASE.md",
+        "SKILL.md",
+    ];
+    const times = await Promise.all(names.map(async (name) => {
+        try {
+            return (await stat(`${reposDir()}/${repo}/${name}`)).mtime;
+        }
+        catch {
+            return null;
+        }
+    }));
+    const known = times
+        .filter((time) => time !== null)
+        .map((time) => time.getTime());
+    return known.length ? new Date(Math.max(...known)).toISOString() : null;
+}
 /** Reads all review guides and `knowledge_built_at` under one lock so every
  * file belongs to the same generation. */
 export async function loadGuides(repo) {
@@ -30,6 +53,10 @@ export async function loadGuides(repo) {
         catch {
             // Local CLI review without `serve` — guides still load from disk.
         }
+        // With no `repos` row, the files are the only evidence of when the guide
+        // was built. Without this a local review always says `guide unknown` and
+        // can never notice that a rebuild made its carry-over stale (CORE-42).
+        guideBuiltAt ??= await guideFilesBuiltAt(repo);
         return {
             shortGuide,
             detailed,

package/dist/src/server/api/installations.js

@@ -6,7 +6,7 @@ export async function handleInstallationsRoute(request, githubApp) {
         return errorResponse(404, "not_found", "no route for /api/installations");
     }
     if (!githubApp) {
-        return errorResponse(422, "app_not_configured", "GitHub App is not configured; run: co-maintainer set --github-app-id=... --github-app-private-key=...");
+        return errorResponse(422, "app_not_configured", "GitHub App is not configured. Run: co-maintainer set --github-app-id=... --github-app-private-key=...");
     }
     const installations = await listInstallationsWithRepos(githubApp.appId, githubApp.privateKeyPem);
     return Response.json({