co-maintainer 0.4.13 → 0.5.0-beta.1

package/dist/src/services/probe.js

@@ -0,0 +1,133 @@
+/** The reading half of `co-maintainer probe`, shared by the CLI and the
+ * dashboard's Add repository preview (CORE-73).
+ *
+ * It only reads: no guide is written, nothing is cached here. The CLI adds
+ * the estimate, the printing and `--run`; `/api/repos/preview` adds the
+ * access check and returns the plan for confirmation. Keeping one
+ * implementation means the number an operator confirms is the number `init`
+ * would be given. */
+import { analyzeProbe } from "../knowledge/probe.js";
+import { timed } from "../util/log.js";
+/** Samples this many pull requests for diff sizes, on top of a few per year. */
+const SAMPLE_HEAD = 30;
+const SAMPLE_PER_YEAR = 3;
+export async function probePlan(client, repo, opts) {
+    const say = opts.log ?? (() => { });
+    const timedRun = (label, fn) => timed(label, opts.logTime ?? false, fn);
+    say(`reading ${repo} metadata`);
+    const meta = await timedRun("probe repository metadata", () => client.request(`repos/${repo}`));
+    let latestReleaseAt = "";
+    try {
+        const releases = await timedRun("probe release metadata", () => client.pages(`repos/${repo}/releases?per_page=1`, 1));
+        latestReleaseAt = String(releases[0]?.published_at ?? releases[0]?.created_at ?? "");
+    }
+    catch {
+        // Release metadata is an optional probe signal.
+    }
+    say("reading pull request list");
+    const pulls = await timedRun("probe pull request listing", () => client.pages(`repos/${repo}/pulls?state=all&sort=updated&direction=desc`, undefined, (page, fetched) => say(`pull request listing · page ${page} · fetched ${fetched}`)));
+    const yearBuckets = new Map();
+    for (const pull of pulls) {
+        const pullYear = new Date(String(pull.updated_at)).getFullYear();
+        yearBuckets.set(pullYear, [...(yearBuckets.get(pullYear) ?? []), pull]);
+    }
+    const sampleTargets = new Map();
+    for (const pull of pulls.slice(0, SAMPLE_HEAD)) {
+        sampleTargets.set(Number(pull.number), pull);
+    }
+    for (const yearPulls of yearBuckets.values()) {
+        for (const pull of yearPulls.slice(0, SAMPLE_PER_YEAR)) {
+            sampleTargets.set(Number(pull.number), pull);
+        }
+    }
+    const samplePulls = [...sampleTargets.values()];
+    const detailSamples = [];
+    say(`sampling ${samplePulls.length} pull request details · concurrency=${opts.ghConcurrent}`);
+    await timedRun("probe PR detail sampling", async () => {
+        const details = new Array(samplePulls.length);
+        let cursor = 0;
+        let completed = 0;
+        const worker = async () => {
+            while (cursor < samplePulls.length) {
+                const index = cursor++;
+                const pull = samplePulls[index];
+                try {
+                    details[index] = await client.request(`repos/${repo}/pulls/${Number(pull.number)}`);
+                }
+                catch {
+                    // A missing detail should not invalidate the rest of the probe.
+                }
+                finally {
+                    completed++;
+                    say(`PR detail sampling · ${completed}/${samplePulls.length}`);
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(opts.ghConcurrent, samplePulls.length) }, worker));
+        detailSamples.push(...details.filter((detail) => !!detail));
+    });
+    const branch = String(meta.default_branch ?? "main");
+    say(`sampled ${detailSamples.length} PR details · reading ${branch} commits`);
+    const commits = await timedRun("probe commit history", () => client.pages(`repos/${repo}/commits?sha=${encodeURIComponent(branch)}`, undefined, (page, fetched) => say(`commit history · page ${page} · fetched ${fetched}`)));
+    const analysis = await timedRun("probe analysis", async () => analyzeProbe({ ...meta, latest_release_at: latestReleaseAt }, pulls, detailSamples, commits));
+    const recommendation = ["--include-codebase"];
+    if (analysis.includePullRequests)
+        recommendation.push("--include-pull-requests");
+    if (analysis.includePullRequestChanges) {
+        recommendation.push("--include-pull-request-changes");
+    }
+    if (analysis.includeCommitHistory) {
+        recommendation.push("--include-commit-history");
+    }
+    if (pulls.length || Boolean(meta.has_issues)) {
+        recommendation.push("--include-how-repo-works");
+    }
+    if (analysis.maxPullRequestChangeLines) {
+        recommendation.push(`--max-pull-request-change-lines=${analysis.maxPullRequestChangeLines}`);
+    }
+    if (analysis.maxPrMonths) {
+        recommendation.push(`--max-pr-months=${analysis.maxPrMonths}`);
+    }
+    if (analysis.maxCommits) {
+        recommendation.push(`--max-commits=${analysis.maxCommits}`);
+    }
+    const command = ["co-maintainer", "init", repo, ...recommendation].join(" ");
+    const report = {
+        repo,
+        ...analysis.report,
+        recommendations: {
+            includePullRequests: analysis.includePullRequests,
+            includePullRequestChanges: analysis.includePullRequestChanges,
+            includeCommitHistory: analysis.includeCommitHistory,
+            maxPrMonths: analysis.maxPrMonths ?? "all",
+            maxCommits: analysis.maxCommits ?? "all",
+            maxPullRequestChangeLines: analysis.maxPullRequestChangeLines ?? "all",
+        },
+        reasons: analysis.reasons,
+        recommendedCommand: command,
+        createdAt: new Date().toISOString(),
+    };
+    return { analysis, recommendation, command, report };
+}
+/** The `RepoConfig` patch that matches a recommendation, so a confirmed
+ * preview stores the same limits the printed command carries. */
+export function recommendationPatch(recommendation) {
+    const has = (flag) => recommendation.includes(flag);
+    const value = (name) => {
+        const match = recommendation.find((flag) => flag.startsWith(`${name}=`));
+        if (!match)
+            return undefined;
+        const number = Number(match.slice(name.length + 1));
+        return Number.isFinite(number) ? number : undefined;
+    };
+    return {
+        includeCodebase: has("--include-codebase"),
+        includePullRequests: has("--include-pull-requests"),
+        includePullRequestChanges: has("--include-pull-request-changes"),
+        includeCommitHistory: has("--include-commit-history"),
+        includeHowRepoWorks: has("--include-how-repo-works"),
+        maxPrMonths: value("--max-pr-months"),
+        maxCommits: value("--max-commits"),
+        maxPullRequestChangeLines: value("--max-pull-request-change-lines"),
+    };
+}

package/dist/src/services/remake_cron.d.ts

@@ -1,5 +1,5 @@
 import type { Cron } from "../util/cron.ts";
-/** A remake costs model tokens, so a schedule may fire at most once an hour. */
+/** A sync costs model tokens, so a schedule may fire at most once an hour. */
 export declare function parseRemakeCron(expression: string): Cron;
 /** Each minute is handled once however often the ticker is called. A minute
  * the process slept through is not made up. */

package/dist/src/services/remake_cron.js

@@ -3,11 +3,11 @@ import { getQueuedJobByKey, getRunningJobByKey } from "../store/jobs.js";
 import { listActiveRepos } from "../store/repos.js";
 import { cronMatches, parseCron } from "../util/cron.js";
 import { enqueueSetup } from "./setup.js";
-/** A remake costs model tokens, so a schedule may fire at most once an hour. */
+/** A sync costs model tokens, so a schedule may fire at most once an hour. */
 export function parseRemakeCron(expression) {
     const cron = parseCron(expression);
     if (cron.minutes.size !== 1) {
-        throw new Error("the minute field must be a single value, so a remake runs at most once an hour");
+        throw new Error("the minute field must be a single value, so a sync runs at most once an hour");
     }
     return cron;
 }
@@ -51,7 +51,7 @@ export function startRemakeScheduler(intervalMs = 15_000) {
     const ticker = createRemakeCronTicker();
     timer = setInterval(() => {
         for (const repo of ticker(new Date())) {
-            console.log(`[cron] queued a scheduled remake for ${repo}`);
+            console.log(`[cron] queued a scheduled sync for ${repo}`);
         }
     }, intervalMs);
 }

package/dist/src/services/remote_review.js

@@ -3,11 +3,13 @@ import { resolvedFromFirstReview, revisionStats, sortResolvedFindings, summaryCo
 import { parseFindings } from "../pr/findings.js";
 import { codegraphToolHandlersForBridge } from "../pr/codegraph_tools.js";
 import { reviewWorkspaceRevision } from "../pr/reviewer.js";
-import { buildCarryPromptSection, classifyCarryItems, incrementalDiffPaths, } from "../review/carry_over.js";
+import { buildCarryPromptSection, classifyCarryItems, guideRebuiltSince, incrementalDiffPaths, } from "../review/carry_over.js";
 import { remoteBridgeToolHandlers } from "../remote/tool_bridge.js";
 import { revisionFromSubmitJson } from "../remote/revision_from_submit.js";
 import { closeRemoteSession, openRemoteSession, setRemoteSyncResult, } from "../remote/server/sessions.js";
 import { readConfig } from "../config.js";
+import { reviewBlockingFrom } from "../review/blocking.js";
+import { loadGuides } from "../review/guides.js";
 import { withLogSink } from "../util/log.js";
 import { cancel, registerHandler } from "./jobs.js";
 import { recordAiCost } from "./setup.js";
@@ -45,6 +47,7 @@ function reviewOptionsForRepo(repo, useCodegraph) {
         includeCommitHistory: true,
         includeHowRepoWorks: true,
         onlyRequestChangedPr: false,
+        reviewBlocking: reviewBlockingFrom(config.reviewBlocking),
     };
 }
 function supersedeActiveRemoteJobs(queueKey, supersededBy) {
@@ -158,7 +161,12 @@ export function registerRemoteReviewHandler() {
                 const extras = {};
                 if (subjectId) {
                     const subjectRevision = getSubjectRevision(subjectId);
-                    if (subjectRevision) {
+                    // A guide rebuilt after the previous review invalidates its verdicts
+                    // and its "unchanged" suppression (CORE-42 / F03): start fresh so a
+                    // stale finding cannot mask a new one.
+                    const guideRebuilt = subjectRevision !== undefined &&
+                        guideRebuiltSince(subjectRevision.guide_built_at, (await loadGuides(job.repo)).guideBuiltAt);
+                    if (subjectRevision && !guideRebuilt) {
                         const prevFiles = parseRevisionFiles(subjectRevision);
                         const { unchanged } = incrementalDiffPaths(revision, prevFiles);
                         extras.unchangedPaths = unchanged;
@@ -207,6 +215,7 @@ export function registerRemoteReviewHandler() {
                 const filesByPath = new Map(revision.files.map((file) => [file.path, { patch: file.patch }]));
                 const findings = sortResolvedFindings(resolvedFromFirstReview(parsed, filesByPath));
                 const durationMs = Math.round(performance.now() - started);
+                const blockingMode = reviewBlockingFrom(options.reviewBlocking);
                 setRemoteSyncResult(job.id, {
                     subject: {
                         repo: job.repo,
@@ -215,8 +224,9 @@ export function registerRemoteReviewHandler() {
                     },
                     revision: revisionStats(revision),
                     guide: { builtAt: result.guideBuiltAt },
-                    summary: summaryCounts(findings),
-                    findings: findings.map(toJsonFinding),
+                    codegraph: { state: result.codegraphState },
+                    summary: summaryCounts(findings, blockingMode),
+                    findings: findings.map((row) => toJsonFinding(row, blockingMode)),
                     usage: {
                         tokensIn,
                         tokensOut,

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

@@ -1,5 +1,6 @@
 import { type ParsedFinding } from "../pr/findings.ts";
 import { type Anchor } from "../pr/hunks.ts";
+import { type ReviewBlocking } from "../review/blocking.ts";
 import { type LogFn } from "./jobs.ts";
 import type { AiProvider, GitHubClient, Json, Options } from "../types.ts";
 import type { JobRow } from "../store/rows.ts";
@@ -13,6 +14,16 @@ export declare function splitInline(findings: ParsedFinding[], files: Json[]): {
     leftover: ParsedFinding[];
 };
 export declare function reviewEvent(findingsCount: number): "REQUEST_CHANGES" | "COMMENT";
+/** The GitHub review event for a set of stored findings (CORE-41).
+ *
+ * `model` keeps the 0.4.13 behavior: any finding requests changes, because the
+ * model's label already decided. `severity` ignores that label and requests
+ * changes only for a P0 or P1, so the same finding set always yields the same
+ * event. */
+export declare function appReviewEvent(findings: {
+    severity: string;
+    title: string;
+}[], mode?: ReviewBlocking): "REQUEST_CHANGES" | "COMMENT";
 export interface ReviewMetadata {
     jobId: string;
     model: string;

package/dist/src/services/review.js

@@ -8,11 +8,12 @@ import { parseFindings } from "../pr/findings.js";
 import { anchorFor } from "../pr/hunks.js";
 import { stripSuggestion, suggestionAnchor, withoutSuggestionLine, } from "../pr/suggestion.js";
 import { githubPullRequestToRevision } from "../pr/github_revision.js";
-import { anchorTextFromPatch, buildCarryPromptSection, classifyCarryItems, incrementalDiffPaths, parsePreviousVerdicts, resolveCarryOutcomes, } from "../review/carry_over.js";
+import { anchorTextFromPatch, buildCarryPromptSection, classifyCarryItems, guideRebuiltSince, incrementalDiffPaths, parsePreviousVerdicts, resolveCarryOutcomes, } from "../review/carry_over.js";
 import { runReviewEngine } from "../review/engine.js";
 import { loadGuides } from "../review/guides.js";
+import { reviewBlockingFrom, isBlocking, DEFAULT_REVIEW_BLOCKING, } from "../review/blocking.js";
 import { matchRepeat } from "../pr/rounds.js";
-import { readConfig } from "../config.js";
+import { readConfig, resolveAppPrivateKey } from "../config.js";
 import { outsideCode, redact } from "../util/redact.js";
 import { getRepo, setInstallationId } from "../store/repos.js";
 import { getReviewByJobId, insertReview, latestPostedReview, setReviewScope, setReviewStatus, } from "../store/reviews.js";
@@ -22,6 +23,10 @@ import { enqueue, registerHandler } from "./jobs.js";
 import { getEnv } from "../util/runtime.js";
 const ACCESS_DENIED_BODY = "The App does not have access to review this pull request.";
 export function humanCopy(text) {
+    // The semicolon is prose and always goes. The em dash is left alone here:
+    // this function also sanitizes a finding title, and a title posted before
+    // 0.5.0 uses ` — ` as its path/symbol separator, which the legacy heading
+    // reader still needs (CORE-83 keeps that one allowlisted exception).
     return outsideCode(redact(text), (prose) => prose.replaceAll(";", "."));
 }
 function hasForbiddenCopy(text) {
@@ -61,6 +66,20 @@ export function splitInline(findings, files) {
 export function reviewEvent(findingsCount) {
     return findingsCount > 0 ? "REQUEST_CHANGES" : "COMMENT";
 }
+/** The GitHub review event for a set of stored findings (CORE-41).
+ *
+ * `model` keeps the 0.4.13 behavior: any finding requests changes, because the
+ * model's label already decided. `severity` ignores that label and requests
+ * changes only for a P0 or P1, so the same finding set always yields the same
+ * event. */
+export function appReviewEvent(findings, mode = DEFAULT_REVIEW_BLOCKING) {
+    if (findings.length === 0)
+        return "COMMENT";
+    if (mode === "model")
+        return "REQUEST_CHANGES";
+    const blocking = findings.some((row) => isBlocking(mode, { severity: row.severity, text: row.title }));
+    return reviewEvent(blocking ? 1 : 0);
+}
 export function formatDuration(ms) {
     const totalSeconds = Math.max(0, Math.round(ms / 1000));
     const hours = Math.floor(totalSeconds / 3600);
@@ -132,6 +151,7 @@ export function reviewOptions(repo, prNumber) {
         includeHowRepoWorks: true,
         onlyRequestChangedPr: false,
         useCodegraph: getRepo(repo)?.use_codegraph === 1,
+        reviewBlocking: reviewBlockingFrom(config.reviewBlocking),
     };
 }
 export function aiFor(options) {
@@ -145,19 +165,21 @@ export function aiFor(options) {
 }
 export function clientFor(installationId) {
     const config = readConfig();
-    if (!config.githubAppId || !config.githubAppPrivateKey) {
+    const privateKeyPem = resolveAppPrivateKey(config);
+    if (!config.githubAppId || !privateKeyPem) {
         throw new Error("review jobs need the GitHub App configured");
     }
-    return new AppClient(config.githubAppId, config.githubAppPrivateKey, installationId);
+    return new AppClient(config.githubAppId, privateKeyPem, installationId);
 }
 export async function resolveInstallationId(fullName) {
     const current = getRepo(fullName)?.installation_id;
     if (current)
         return current;
     const config = readConfig();
-    if (!config.githubAppId || !config.githubAppPrivateKey)
+    const privateKeyPem = resolveAppPrivateKey(config);
+    if (!config.githubAppId || !privateKeyPem)
         return undefined;
-    const installationId = await findInstallationForRepo(config.githubAppId, config.githubAppPrivateKey, fullName);
+    const installationId = await findInstallationForRepo(config.githubAppId, privateKeyPem, fullName);
     if (installationId !== undefined)
         setInstallationId(fullName, installationId);
     return installationId;
@@ -244,7 +266,7 @@ async function finishCheck(client, job, checkRunId, conclusion, title, findings,
         },
     }, log);
 }
-async function publish(client, job, reviewId, headSha, files, log, metadata) {
+async function publish(client, job, reviewId, headSha, files, log, metadata, mode = DEFAULT_REVIEW_BLOCKING) {
     const stored = listFindingsForReview(reviewId);
     const replies = stored.filter((row) => row.thread_comment_id);
     const freshRows = stored.filter((row) => row.state === "new" && !row.thread_comment_id);
@@ -314,7 +336,7 @@ async function publish(client, job, reviewId, headSha, files, log, metadata) {
     const payload = {
         commit_id: headSha,
         body,
-        event: reviewEvent(stored.length),
+        event: appReviewEvent(stored, mode),
         comments,
     };
     setReviewStatus(reviewId, "posting");
@@ -523,7 +545,13 @@ async function runReviewJobCore(job, log, client, ai) {
     let carryItems = [];
     let carryPrevious = null;
     const extras = {};
-    if (subjectRevision) {
+    // A guide rebuilt after the previous review invalidates that review's
+    // verdicts and its "unchanged" suppression (CORE-42 / F03). Treat the run as
+    // if it had started fresh: carry-over off, every changed file back in scope,
+    // so a stale finding can never mask a new one.
+    const guideRebuilt = subjectRevision !== undefined &&
+        guideRebuiltSince(subjectRevision.guide_built_at, guidesBefore.guideBuiltAt);
+    if (subjectRevision && !guideRebuilt) {
         const prevFiles = parseRevisionFiles(subjectRevision);
         const { unchanged } = incrementalDiffPaths(revision, prevFiles);
         extras.unchangedPaths = scope === "incremental" ? unchanged : undefined;
@@ -564,7 +592,7 @@ async function runReviewJobCore(job, log, client, ai) {
             row.posted_comment_id,
         ]));
         const verdicts = parsePreviousVerdicts(response.text);
-        const resolved = resolveCarryOutcomes(carryItems, revision, visiblePaths, verdicts, parsed, guideBuiltAt, carryPrevious);
+        const resolved = resolveCarryOutcomes(carryItems, revision, visiblePaths, verdicts, parsed);
         totalFindings = resolved.length;
         for (const row of resolved) {
             if (row.state === "open")
@@ -636,7 +664,7 @@ async function runReviewJobCore(job, log, client, ai) {
         jobId: job.id,
         model: options.highModel ?? "unknown",
         durationMs: Date.now() - startedAt,
-    });
+    }, options.reviewBlocking);
     await finishCheck(github, job, checkRunId, totalFindings === 0 ? "success" : "neutral", totalFindings === 0 ? "Review completed" : "Review findings", listFindingsForReview(reviewId), log);
 }
 export function registerReviewJobHandler() {

package/dist/src/services/setup.js

@@ -2,18 +2,19 @@
  * directly; it used to re-spawn the CLI as a subprocess, a second
  * execution path with its own failure modes. */
 import { createAiProvider } from "../ai/provider.js";
-import { enrichFacts, synthesizeSections } from "../knowledge/synthesis.js";
+import { enrichFactsWithReport, synthesizeSections, } from "../knowledge/synthesis.js";
 import { collectSource } from "../github/collect.js";
 import { GhClient } from "../github/gh.js";
 import { PatClient } from "../github/pat.js";
 import { extractFacts } from "../knowledge/facts.js";
-import { buildReviewDocuments } from "../knowledge/guide.js";
-import { assembleSkill, extractSections, factSectionHashes, } from "../knowledge/skill.js";
+import { buildReviewDocuments, reviewSignalCount } from "../knowledge/guide.js";
+import { assembleSkill, codebaseBody, factSectionHashes, } from "../knowledge/skill.js";
 import { validateSkill } from "../knowledge/validate.js";
 import { readConfig, reposDir, writeRepoConfig } from "../config.js";
 import { readState, writeState } from "../store/skill_state.js";
 import { cacheSet } from "../store/cache_db.js";
 import { log, timed, withLogSink } from "../util/log.js";
+import { printRunSummary, summaryFromMetrics } from "../util/run_summary.js";
 import { enqueue, registerHandler } from "./jobs.js";
 import { closeAppDb, isAppDbOpen, openAppDb } from "../store/app_db.js";
 import { getRepo, markKnowledgeBuilt } from "../store/repos.js";
@@ -72,9 +73,12 @@ async function skillPath(repo) {
     await mkdir(`${reposDir()}/${repo}`, { recursive: true });
     return path;
 }
-async function writeReviewDocuments(repo, documents) {
+async function writeReviewDocuments(repo, documents, signalCount) {
     const directory = `${reposDir()}/${repo}`;
     if (!documents) {
+        // F05: this used to delete the files without a word. The plan's rule is
+        // "says why the third file is missing": keep it to one line.
+        log("write", `PR_REVIEW_GUIDE.md skipped: found ${signalCount} review signals, needs at least 3`);
         await Promise.all([
             remove(`${directory}/PR_REVIEW_GUIDE.md`).catch(() => { }),
             remove(`${directory}/PR_REVIEW_DETAILED_GUIDE.md`).catch(() => { }),
@@ -93,14 +97,12 @@ async function writeReviewDocuments(repo, documents) {
 /** Splits the codebase-description sections (layout/style/tests/devloop) out
  * of the assembled skill into their own file, so `review` can check a pull
  * request against how this repository's code actually looks, not just the
- * review-bar checklist mined from past PR comments. */
-async function writeCodebaseDocument(repo, skillMarkdown) {
+ * review-bar checklist mined from past PR comments. The skill links to this
+ * file rather than repeating it (CORE-32 / F26c), so its body is built from
+ * the facts instead of being scraped back out of the skill. */
+async function writeCodebaseDocument(repo, facts, overrides = {}) {
     const path = `${reposDir()}/${repo}/CODEBASE.md`;
-    const sections = extractSections(skillMarkdown);
-    const body = ["layout", "style", "tests", "devloop"]
-        .map((key) => sections[key])
-        .filter(Boolean)
-        .join("\n\n");
+    const body = codebaseBody(facts, overrides);
     if (!body) {
         await remove(path).catch(() => { });
         return;
@@ -133,7 +135,7 @@ async function initOrRemake(options) {
     const aiMetrics = emptyAiMetrics();
     const previous = await readState(options.repo);
     if (options.command === "remake" && !previous) {
-        throw new Error("remake requires a previous init or remake for this repository");
+        throw new Error("sync requires a previous init or sync for this repository");
     }
     if (options.command === "remake" && previous) {
         options.maxCommits ??= previous.options.maxCommits;
@@ -182,6 +184,7 @@ async function initOrRemake(options) {
         log("time", `extract deterministic facts · ${((performance.now() - factsStarted) / 1000).toFixed(2)}s`);
     }
     let overrides = {};
+    const skipped = [];
     if (lowAi) {
         log("ai", "starting extract_unit jobs");
         const usage = async (job, response) => {
@@ -196,7 +199,9 @@ async function initOrRemake(options) {
                 aiMetrics.cost += response.cost;
             await recordAiCost(options.repo, job, response);
         };
-        facts = await timed("extract_unit AI", options.logTime, () => enrichFacts(lowAi, options.repo, facts, source, options, usage));
+        const enriched = await timed("extract_unit AI", options.logTime, () => enrichFactsWithReport(lowAi, options.repo, facts, source, options, usage));
+        facts = enriched.facts;
+        skipped.push(...enriched.skipped);
         log("ai", `extract_unit complete · ${facts.length} facts`);
         const hashes = await factSectionHashes(facts);
         const synthesisChanged = previous &&
@@ -211,7 +216,9 @@ async function initOrRemake(options) {
             : undefined;
         log("ai", `starting synth_section jobs${dirtySections ? ` · ${dirtySections.size} dirty sections` : ""}`);
         if (highAi) {
-            overrides = await timed("synth_section AI", options.logTime, () => synthesizeSections(highAi, options.repo, facts, previousMarkdown, options.ai, options.highModel ?? "", options.aiConcurrent, usage, dirtySections));
+            const synth = await timed("synth_section AI", options.logTime, () => synthesizeSections(highAi, options.repo, facts, previousMarkdown, options.ai, options.highModel ?? "", options.aiConcurrent, usage, dirtySections));
+            overrides = synth.overrides;
+            skipped.push(...synth.skipped);
         }
         log("ai", `synth_section complete · ${Object.keys(overrides).length} sections`);
     }
@@ -237,8 +244,8 @@ async function initOrRemake(options) {
         const { writeTextFileAtomic } = await import("../util/atomic.js");
         await withKnowledgeLock(options.repo, async () => {
             await writeTextFileAtomic(path, result.markdown);
-            await writeCodebaseDocument(options.repo, result.markdown);
-            await writeReviewDocuments(options.repo, reviewDocuments);
+            await writeCodebaseDocument(options.repo, facts, overrides);
+            await writeReviewDocuments(options.repo, reviewDocuments, reviewSignalCount(facts));
             const head = source.commits[0];
             const baseSha = head?.sha ? String(head.sha) : new Date().toISOString();
             markKnowledgeBuilt(options.repo, baseSha);
@@ -257,7 +264,7 @@ async function initOrRemake(options) {
             },
             updatedAt: new Date().toISOString(),
         });
-        // Remember everything but the token, so `remake owner/repo` alone
+        // Remember everything but the token, so `sync owner/repo` alone
         // (no flags, no prompts) reuses what this run resolved.
         await writeRepoConfig(options.repo, {
             auth: options.auth,
@@ -281,9 +288,20 @@ async function initOrRemake(options) {
         ? `updated ${result.changed.join(", ")}`
         : "already current"}`);
     log("done", `${facts.length} facts · ${source.pullRequests.length} pull requests · ${source.commits.length} commits`);
+    if (skipped.length) {
+        // F04: a skipped unit used to vanish into a log line and recur as a "cache
+        // hit" forever. Say it in the final line instead, in the plan's shape:
+        // `1 unit skipped (PR #3: output was not JSON)`.
+        const parts = skipped.map((unit) => unit.reason);
+        const line = skipped.length === 1
+            ? `1 unit skipped (${parts[0]})`
+            : `${skipped.length} units skipped (${parts.join("; ")})`;
+        log("done", line);
+    }
+    printRunSummary(summaryFromMetrics(aiMetrics, performance.now() - operationStarted));
     if (options.logTime) {
         log("time", `AI total · calls=${aiMetrics.calls} · input=${aiMetrics.tokensIn} tokens · output=${aiMetrics.tokensOut} tokens · cost=${aiMetrics.costKnown ? aiMetrics.cost.toFixed(4) : "unknown"}`);
-        log("time", `total init/remake · ${((performance.now() - operationStarted) / 1000).toFixed(2)}s`);
+        log("time", `total init/sync · ${((performance.now() - operationStarted) / 1000).toFixed(2)}s`);
     }
 }
 /** Builds `Options` for a server-triggered `init`/`remake` from config
@@ -299,7 +317,7 @@ export function optionsFromConfig(repo, command) {
     const lowModel = repoConfig.lowModel ?? config.lowModel;
     const highModel = repoConfig.highModel ?? config.highModel;
     if (ai !== "none" && (!config.token || !lowModel || !highModel)) {
-        throw new Error("AI is enabled but token/low-model/high-model are not fully configured; run: " +
+        throw new Error("AI is enabled but token/low-model/high-model are not fully configured. Run: " +
             "co-maintainer set --token=... --low-model=... --high-model=...");
     }
     return {

package/dist/src/services/setup_checklist.d.ts

@@ -0,0 +1,10 @@
+export type SetupItem = {
+    id: string;
+    title: string;
+    detail: string;
+    done: boolean;
+    /** Where the fix lives. In-page anchors on /settings where one exists. */
+    href: string;
+    linkLabel: string;
+};
+export declare function setupChecklist(webhookUrl: string): SetupItem[];

package/dist/src/services/setup_checklist.js

@@ -0,0 +1,87 @@
+/** The "Finish setup" checklist shown on the home page (CORE-75, C01/F26).
+ *
+ * Each item is derived from state that already exists, so the card reflects
+ * what serve can actually do rather than a parallel bookkeeping of it. The
+ * webhook item reuses CORE-71's reachability check. */
+import { readConfig, resolveAppPrivateKey } from "../config.js";
+import { countReviews } from "../store/reviews.js";
+import { listRemoteTokens } from "../store/remote_tokens.js";
+import { listActiveRepos } from "../store/repos.js";
+import { lastDelivery } from "../store/deliveries.js";
+import { webhookReachabilityProblem } from "../util/webhook_reachability.js";
+export function setupChecklist(webhookUrl) {
+    const config = readConfig();
+    const aiDone = Boolean(config.ai && config.ai !== "none" && config.token);
+    const appDone = Boolean(config.githubAppId && resolveAppPrivateKey(config));
+    const repoCount = listActiveRepos().length;
+    const reviewCount = countReviews();
+    const tokenCount = listRemoteTokens().length;
+    const reach = webhookReachabilityProblem(webhookUrl);
+    const reached = reach === undefined && lastDelivery() !== undefined;
+    return [
+        {
+            id: "ai",
+            title: "Models and API key",
+            detail: aiDone
+                ? "An AI provider and key are saved."
+                : "Add a provider and API key so reviews and guides can be written.",
+            done: aiDone,
+            href: "/settings#ai",
+            linkLabel: "Open models",
+        },
+        {
+            id: "app",
+            title: "GitHub App",
+            detail: appDone
+                ? "The App is configured."
+                : "Create and install the App so reviews can be posted to pull requests.",
+            done: appDone,
+            href: "/settings#github",
+            linkLabel: "Open GitHub",
+        },
+        {
+            id: "webhook",
+            title: "Webhook reachable",
+            detail: !appDone
+                ? "Set up the GitHub App first, then point its webhook at this server."
+                : reached
+                    ? "GitHub has delivered a webhook to this server."
+                    : reach
+                        ? `GitHub cannot reach ${webhookUrl}. ${reach}`
+                        : "Waiting for the first delivery. Open a pull request to confirm.",
+            done: reached,
+            href: "/settings#github",
+            linkLabel: "Open webhook",
+        },
+        {
+            id: "repo",
+            title: "First repository",
+            detail: repoCount === 0
+                ? "Add a repository to generate its guides."
+                : `${repoCount} ${repoCount === 1 ? "repository" : "repositories"} added.`,
+            done: repoCount > 0,
+            href: "/repos/new",
+            linkLabel: "Add repository",
+        },
+        {
+            id: "review",
+            title: "First review",
+            detail: reviewCount === 0
+                ? "A review appears after the first pull request, or run one by number."
+                : `${reviewCount} ${reviewCount === 1 ? "review" : "reviews"} so far.`,
+            done: reviewCount > 0,
+            href: "/activity",
+            linkLabel: "Open activity",
+        },
+        {
+            id: "cli",
+            title: "CLI connected",
+            detail: tokenCount === 0
+                ? "Create a remote token to run co-maintainer review --remote."
+                : `${tokenCount} remote ${tokenCount === 1 ? "token" : "tokens"} created.`,
+            done: tokenCount > 0,
+            href: "/settings#remote",
+            linkLabel: "Open tokens",
+        },
+    ];
+}

package/dist/src/store/app_db.js

@@ -1,5 +1,6 @@
 import { Database } from "./sqlite.js";
 import { getCacheDir } from "../config.js";
+import { CliError, EXIT_USAGE } from "../cli/error.js";
 import { migrations } from "./migrations.js";
 import { getEnv, isNotFound, isProcessAlive, mkdir, readTextFile, remove, writeTextFile, } from "../util/runtime.js";
 export function appDbDir() {
@@ -27,7 +28,9 @@ async function acquireLock() {
     if (existingPid !== undefined &&
         Number.isInteger(existingPid) &&
         isProcessAlive(existingPid)) {
-        throw new Error(`co-maintainer serve is already running (pid ${existingPid}) against this app.db. Only one serve process may write to it at a time.`);
+        // Says what is holding the database, what to do about it, and offers the
+        // path that does not need another process. CORE-12.
+        throw new CliError("serve_already_running", `A co-maintainer serve process (pid ${existingPid}) is using this data directory.`, "Stop it, or run sync from its dashboard.", EXIT_USAGE);
     }
     await writeTextFile(path, String(process.pid));
 }
@@ -79,7 +82,7 @@ export async function openAppDb() {
 }
 export function getAppDb() {
     if (!db)
-        throw new Error("app.db is not open; call openAppDb() first");
+        throw new Error("app.db is not open. Call openAppDb() first");
     return db;
 }
 export async function closeAppDb() {