gentle-pi 2.4.0 → 2.6.0

package/runtime/review-risk-assessment.mjs

@@ -0,0 +1,340 @@
+// Generated by scripts/build-runtime-modules.mjs. Do not edit.
+// gentle-pi#662: pure decoding, tier mapping, and verification-plan logic for
+// the native read-only `gentle-ai review assess` command (gentle-ai#4295).
+// Kept independent of the native review CLI wrapper (`lib/native-review-cli.ts`)
+// so the decoder and the verificationPlan table can be unit-tested without a
+// child process, and so the parent tool and the delegation asset agree on one
+// deterministic mapping.
+//
+// Native reference (gentle-ai#4295, landing in parallel with this change):
+// `gentle-ai review assess --cwd <repo> [--base-ref <ref> --committed-only] --json`
+// prints `{"schema":"gentle-ai.review-assessment/v1","risk":"passive|medium|high",
+// "reasons":[{"code":"…","path":"…","detail":"…"}],"changed_paths":1,
+// "changed_lines":1,"candidate":{"kind":"current-changes|base-diff","base_ref":"…"}}`.
+// A non-zero exit or a failure envelope means the candidate could not be
+// assessed; hosts treat that as `high`. Older binaries without the verb (or
+// any other decode/process failure) fail closed the same way -- see
+// `verificationTierForUnassessable` below.
+
+export const REVIEW_ASSESSMENT_SCHEMA = "gentle-ai.review-assessment/v1"         ;
+
+export const REVIEW_ASSESSMENT_RISK = {
+	PASSIVE: "passive",
+	MEDIUM: "medium",
+	HIGH: "high",
+}         ;
+
+
+export const REVIEW_ASSESSMENT_CANDIDATE_KIND = {
+	CURRENT_CHANGES: "current-changes",
+	BASE_DIFF: "base-diff",
+}         ;
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+function isRecord(value         )                                   {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function decodeReason(value         )                         {
+	if (!isRecord(value)) throw new TypeError("review assessment reason must be an object");
+	const { code, path, detail } = value;
+	if (typeof code !== "string" || code.length === 0) throw new TypeError("review assessment reason.code must be a non-empty string");
+	if (typeof path !== "string") throw new TypeError("review assessment reason.path must be a string");
+	if (typeof detail !== "string") throw new TypeError("review assessment reason.detail must be a string");
+	return Object.freeze({ code, path, detail });
+}
+
+function decodeCandidate(value         )                            {
+	if (!isRecord(value)) throw new TypeError("review assessment candidate must be an object");
+	const { kind, base_ref: baseRef } = value;
+	if (kind !== REVIEW_ASSESSMENT_CANDIDATE_KIND.CURRENT_CHANGES && kind !== REVIEW_ASSESSMENT_CANDIDATE_KIND.BASE_DIFF) {
+		throw new TypeError("review assessment candidate.kind must be current-changes or base-diff");
+	}
+	if (baseRef !== undefined && (typeof baseRef !== "string" || baseRef.length === 0)) {
+		throw new TypeError("review assessment candidate.base_ref must be a non-empty string when present");
+	}
+	return Object.freeze({ kind, baseRef: baseRef                       });
+}
+
+/**
+ * Decodes and validates one `gentle-ai.review-assessment/v1` envelope. Rejects
+ * any other schema, an unrecognized risk value, or a malformed shape -- the
+ * native review CLI wrapper turns a thrown error here into the same
+ * schema-incompatible failure it already produces for every other decoded
+ * native response.
+ */
+export function decodeReviewAssessmentV1(value         )                     {
+	if (!isRecord(value)) throw new TypeError("review assessment must be an object");
+	if (value.schema !== REVIEW_ASSESSMENT_SCHEMA) throw new TypeError(`review assessment schema must be ${REVIEW_ASSESSMENT_SCHEMA}`);
+	const { risk, reasons, changed_paths: changedPaths, changed_lines: changedLines, candidate } = value;
+	if (risk !== REVIEW_ASSESSMENT_RISK.PASSIVE && risk !== REVIEW_ASSESSMENT_RISK.MEDIUM && risk !== REVIEW_ASSESSMENT_RISK.HIGH) {
+		throw new TypeError("review assessment risk must be passive, medium, or high");
+	}
+	if (!Array.isArray(reasons)) throw new TypeError("review assessment reasons must be an array");
+	if (!Number.isSafeInteger(changedPaths) || (changedPaths          ) < 0) throw new TypeError("review assessment changed_paths must be a non-negative integer");
+	if (!Number.isSafeInteger(changedLines) || (changedLines          ) < 0) throw new TypeError("review assessment changed_lines must be a non-negative integer");
+	return Object.freeze({
+		schema: REVIEW_ASSESSMENT_SCHEMA,
+		risk,
+		reasons: Object.freeze(reasons.map(decodeReason)),
+		changedPaths: changedPaths          ,
+		changedLines: changedLines          ,
+		candidate: decodeCandidate(candidate),
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Verification-plan tiering (gentle-pi#662).
+// ---------------------------------------------------------------------------
+
+export const VERIFICATION_TIER = {
+	PASSIVE: "passive",
+	MEDIUM: "medium",
+	HIGH: "high",
+	UNASSESSABLE: "unassessable",
+}         ;
+
+
+export const RDD_LINE = {
+	ON: "on",
+	OFF: "off",
+	UNKNOWN: "unknown",
+}         ;
+
+
+export const WRITER_PROFILE = {
+	SMALL: "small",
+	LARGE: "large",
+}         ;
+
+
+// gentle-pi#668: whether the native review actually reached a terminal
+// outcome for the current candidate. The `on` branch of `verificationPlan`
+// (the writer self-verifies, the native review is the independent check, no
+// separate verifier) holds only for `CLOSED` -- a human decline for this
+// candidate, a clone-local RDD disable, a refused START/STATUS, or any other
+// non-terminal outcome falls back to the exact same risk-gated path as `off`.
+// `UNKNOWN` is the fail-closed default for an omitted outcome: never treated
+// as `CLOSED`.
+export const NATIVE_REVIEW_OUTCOME = {
+	CLOSED: "closed",
+	DECLINED: "declined",
+	UNAVAILABLE: "unavailable",
+	UNKNOWN: "unknown",
+}         ;
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+/**
+ * Builds the risk-gated verification plan shared by the `off`/`unknown` RDD
+ * lines and by an `on` line whose native review did not close for this
+ * candidate (gentle-pi#668). `gatePrefix` supplies the sentence fragment
+ * naming which branch fired, up to and including the word "and"; the
+ * tier-specific clause is appended after it.
+ */
+function riskGatedPlan(gatePrefix        , risk                  , writerProfile               )                   {
+	if (risk === VERIFICATION_TIER.PASSIVE) {
+		return Object.freeze({
+			writerSelfVerification: false,
+			structuralReadbackOnly: true,
+			independentVerifier: false,
+			reason: `${gatePrefix} the native assessment reports passive risk: a structural readback by the parent is the complete check, with no separate verifier and no tests.`,
+		});
+	}
+
+	if (risk === VERIFICATION_TIER.MEDIUM) {
+		const smallModelBias = writerProfile === WRITER_PROFILE.SMALL;
+		return Object.freeze({
+			writerSelfVerification: true,
+			structuralReadbackOnly: false,
+			independentVerifier: smallModelBias,
+			reason: smallModelBias
+				? `${gatePrefix} the native assessment reports medium risk, but the small-model bias raises it one tier to high for verification purposes: the writer self-verifies and a separate independent verifier also runs.`
+				: `${gatePrefix} the native assessment reports medium risk with a large writer profile: the writer's self-verification stands and no separate verifier is required.`,
+		});
+	}
+
+	// high or unassessable.
+	return Object.freeze({
+		writerSelfVerification: true,
+		structuralReadbackOnly: false,
+		independentVerifier: true,
+		reason: risk === VERIFICATION_TIER.UNASSESSABLE
+			? `${gatePrefix} the native risk assessment could not be produced, so the candidate is treated as high risk: the writer self-verifies and a separate independent verifier always runs.`
+			: `${gatePrefix} the native assessment reports high risk: the writer self-verifies and a separate independent verifier always runs.`,
+	});
+}
+
+// Names why an `on` line falls back to the risk-gated path, for every
+// non-closed native review outcome (gentle-pi#668). `UNKNOWN` covers both an
+// omitted outcome and a caller-supplied one this decoder does not
+// recognize -- both fail closed the same way.
+function nonClosedOutcomeClause(outcome                     )         {
+	switch (outcome) {
+		case NATIVE_REVIEW_OUTCOME.DECLINED:
+			return "the native review was declined for this candidate";
+		case NATIVE_REVIEW_OUTCOME.UNAVAILABLE:
+			return "the native review is unavailable for this candidate";
+		default:
+			return "the native review outcome for this candidate is unknown";
+	}
+}
+
+/**
+ * Computes who verifies a delegated writer's change, exactly as
+ * gentle-pi#662/#668 specify:
+ *
+ * - `rdd: "on"` AND the native review reached `NATIVE_REVIEW_OUTCOME.CLOSED`
+ *   for this candidate: the writer self-verifies and no independent verifier
+ *   runs, because the closed native review is the check -- except `passive`,
+ *   which gets a structural readback by the parent instead.
+ * - `rdd: "on"` with any other outcome (`declined`, `unavailable`, or the
+ *   fail-closed `unknown` default for an omitted/unrecognized outcome): the
+ *   `on` branch never held for this candidate, so the risk-gated path below
+ *   applies exactly as `off` -- declining a review is candidate-scoped and
+ *   never lowers the bar below the RDD-off path.
+ * - `rdd: "off"` or `"unknown"` (both gate identically, so an unknown RDD line
+ *   never lowers a tier relative to `off`; `nativeReviewOutcome` is ignored
+ *   entirely on these lines):
+ *   - `passive`: structural readback by the parent only; no verifier, no
+ *     tests.
+ *   - `medium`: the writer self-verifies; a separate independent verifier
+ *     runs only when `writerProfile` is `"small"` -- the small-model bias
+ *     raises the tier by one for verification purposes (medium -> high). An
+ *     unknown or omitted writer profile resolves to `"small"` before it
+ *     reaches this function (see `resolveWriterProfile`), so an unrecognized
+ *     profile never lowers a tier below what a known small model would get.
+ *   - `high` or `unassessable` (a failed or unrecognized native assessment is
+ *     always treated as high): the writer self-verifies and an independent
+ *     verifier always runs.
+ */
+export function verificationPlan(input                       )                   {
+	const { rddLine, risk, writerProfile } = input;
+
+	if (rddLine === RDD_LINE.ON) {
+		const outcome = input.nativeReviewOutcome ?? NATIVE_REVIEW_OUTCOME.UNKNOWN;
+		if (outcome === NATIVE_REVIEW_OUTCOME.CLOSED) {
+			if (risk === VERIFICATION_TIER.PASSIVE) {
+				return Object.freeze({
+					writerSelfVerification: false,
+					structuralReadbackOnly: true,
+					independentVerifier: false,
+					reason: "receipt-driven development is on and the native review closed for this candidate; the assessment also reports passive risk: a structural readback by the parent replaces both the writer's self-verification and any separate verifier.",
+				});
+			}
+			return Object.freeze({
+				writerSelfVerification: true,
+				structuralReadbackOnly: false,
+				independentVerifier: false,
+				reason: "receipt-driven development is on and the native review closed for this candidate: the writer's self-verification is the record and the closed native review was the independent check the writer cannot influence, so no separate verifier is required.",
+			});
+		}
+		// The on branch holds only while the native review reaches a terminal
+		// outcome for this candidate. Anything else -- declined, unavailable, or
+		// unknown -- falls back to the exact same risk-gated path as off.
+		return riskGatedPlan(
+			`receipt-driven development is on, but ${nonClosedOutcomeClause(outcome)}, so the risk-gated path applies exactly as receipt-driven development off, and`,
+			risk,
+			writerProfile,
+		);
+	}
+
+	// rddLine is "off" or "unknown" here -- both gate on the native risk
+	// assessment identically, so an unknown RDD line never lowers a tier, and
+	// neither line ever consults nativeReviewOutcome.
+	return riskGatedPlan(`receipt-driven development is ${rddLine} and`, risk, writerProfile);
+}
+
+// ---------------------------------------------------------------------------
+// Small-writer-profile predicate (gentle-pi#662).
+// ---------------------------------------------------------------------------
+
+/**
+ * The minimal shape of `lib/agents-config.ts`'s `ResolvedProfile` this
+ * predicate needs: the resolved model reference and its resolved effort
+ * (`ResolvedProfile.thinking`, one of `ThinkingLevel`).
+ */
+
+
+
+
+
+// Matches `mini` only as a whole token of the model id -- delimited by the
+// string start/end or one of `-_./:` or whitespace -- never a bare substring.
+// `gpt-5.4-mini`, `o4-mini`, `openai/gpt-5.4-mini`, `claude-mini`, and
+// `mini-high` all match; `gemini`, `gemini-2.5-pro`, and `gemini-2.5-flash`
+// do not, because their `mini` is preceded by `ge`, not a delimiter.
+const SMALL_MODEL_ID_TOKEN = /(?:^|[-_./:\s])mini(?:$|[-_./:\s])/i;
+
+/**
+ * A writer profile counts as a "small model" for the medium-risk bias when:
+ * - its resolved effort is `low`, or
+ * - its resolved model id carries `mini` as a whole token (see
+ *   `SMALL_MODEL_ID_TOKEN`), or
+ * - it carries NO signal at all -- no profile object, or a profile with
+ *   neither a model id nor a resolved effort. An unknown or omitted writer
+ *   profile fails closed to small rather than defaulting to large, so a
+ *   caller that cannot resolve the writer's profile never gets a weaker
+ *   verification plan than a known small model would (gentle-pi#662).
+ *
+ * A profile that carries a model id or an effort, just not a matching one
+ * (for example `{model: {id: "claude-sonnet-5"}, thinking: "high"}`), is
+ * "known large" and returns `false` -- fail-closed applies only to a truly
+ * unknown/omitted profile, not to an explicitly resolved large one.
+ */
+export function isSmallWriterProfile(profile                                    )          {
+	if (profile === undefined) return true;
+	if (profile.thinking === "low") return true;
+	const modelId = profile.model?.id;
+	if (typeof modelId === "string") return SMALL_MODEL_ID_TOKEN.test(modelId);
+	// No model id was resolved. Fail closed to small only when effort is also
+	// unknown -- there is no signal at all to call this a known large model.
+	return profile.thinking === undefined;
+}
+
+/**
+ * Maps a resolved writer profile to the `writerProfile` input `verificationPlan`
+ * expects. An unknown or omitted profile never lowers a tier: it resolves to
+ * `"small"`, exactly like `isSmallWriterProfile` (gentle-pi#662).
+ */
+export function resolveWriterProfile(profile                                    )                {
+	return isSmallWriterProfile(profile) ? WRITER_PROFILE.SMALL : WRITER_PROFILE.LARGE;
+}

package/runtime/telemetry-trigger.mjs

@@ -0,0 +1,154 @@
+// Generated by scripts/build-runtime-modules.mjs. Do not edit.
+import { spawn as nodeSpawn } from "node:child_process";
+
+// gentle-ai#4309 owns anonymous usage telemetry end to end: install and
+// heartbeat events, the notice, every kill switch, and the wire contract.
+// gentle-pi#677 only nudges the local binary once per process, best-effort,
+// and never surfaces the outcome to the user. This module is the pure,
+// testable core of that nudge (`shouldTriggerTelemetry`,
+// `spawnTelemetryTrigger`) plus the decode helper the foreground
+// `/gentle:telemetry` slash command uses to relay `<op> --json` output
+// (`decodeTelemetryTriggerDecision`).
+
+export const TELEMETRY_TRIGGER_KILL_TIMEOUT_MS = 3_000;
+
+export const TELEMETRY_TRIGGER_CONTRACT = "gentle-ai.telemetry-trigger/v1";
+
+export const TELEMETRY_TRIGGER_DECISIONS = [
+	"enrolled",
+	"sent_install",
+	"sent_heartbeat",
+	"rate_limited",
+	"backoff",
+	"disabled",
+]         ;
+
+
+
+
+
+
+
+
+/**
+ * Decodes `gentle-ai telemetry trigger --json` stdout. An older binary
+ * without the verb prints `unknown telemetry command` and exits non-zero, so
+ * its stdout never parses as JSON here; that -- along with malformed JSON, a
+ * mismatched schema, an unrecognized decision, or a missing/non-string
+ * source -- means "nothing to do" and returns undefined rather than
+ * throwing.
+ */
+export function decodeTelemetryTriggerDecision(stdout        )                                         {
+	let parsed         ;
+	try {
+		parsed = JSON.parse(stdout);
+	} catch {
+		return undefined;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+	const record = parsed                           ;
+	if (record.schema !== TELEMETRY_TRIGGER_CONTRACT) return undefined;
+	if (typeof record.decision !== "string") return undefined;
+	if (!(TELEMETRY_TRIGGER_DECISIONS                     ).includes(record.decision)) return undefined;
+	if (typeof record.source !== "string" || record.source.length === 0) return undefined;
+	return {
+		schema: TELEMETRY_TRIGGER_CONTRACT,
+		decision: record.decision                            ,
+		source: record.source,
+	};
+}
+
+
+
+function telemetryKillSwitchReason(env                                              )                                        {
+	if (env.DO_NOT_TRACK === "1") return "do-not-track";
+	if (env.GENTLE_AI_TELEMETRY === "0") return "telemetry-disabled";
+	if (env.CI === "true") return "ci";
+	return undefined;
+}
+
+/**
+ * True unless one of Gentle Pi's own kill switches is set
+ * (`DO_NOT_TRACK=1`, `GENTLE_AI_TELEMETRY=0`, or `CI=true`). The binary
+ * enforces its own opt-out and rate limiting independently; this predicate
+ * only decides whether Gentle Pi spawns the trigger at all.
+ */
+export function shouldTriggerTelemetry(env                                              )          {
+	return telemetryKillSwitchReason(env) === undefined;
+}
+
+// A minimal structural subset of node:child_process's ChildProcess, mirroring
+// the ChildLike/Spawn seam already used by lib/agents-runner.ts: narrow
+// enough that tests can stub it without touching a real process.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+/**
+ * Nudges `<executable> telemetry trigger --json`, detached and
+ * fire-and-forget. Never throws, never awaits the child's exit, and never
+ * blocks session start: a missing binary, an old binary without the verb, or
+ * a spawn failure all just report `{ spawned: false, ... }`. A 3 s timer
+ * kills a runaway child; the timer is unref'd so it can never keep the host
+ * process alive on its own, matching the detached child's own `unref()`.
+ */
+export function spawnTelemetryTrigger(options                              )                         {
+	const killSwitch = telemetryKillSwitchReason(options.env);
+	if (killSwitch !== undefined) return { spawned: false, reason: killSwitch };
+	const spawnImpl = options.spawn ?? (nodeSpawn                                    );
+	try {
+		const child = spawnImpl(options.executable, ["telemetry", "trigger", "--json"], {
+			cwd: options.cwd,
+			env: options.env,
+			detached: true,
+			windowsHide: true,
+			stdio: "ignore",
+		});
+		child.on("error", () => {
+			// Fire-and-forget: a spawn-time or runtime child error never surfaces
+			// to the caller and never affects session start.
+		});
+		const killTimer = setTimeout(() => {
+			try {
+				child.kill();
+			} catch {
+				// Best effort only; the child may already have exited.
+			}
+		}, TELEMETRY_TRIGGER_KILL_TIMEOUT_MS);
+		killTimer.unref?.();
+		child.unref();
+		return { spawned: true, reason: "spawned" };
+	} catch {
+		return { spawned: false, reason: "spawn-error" };
+	}
+}

package/scripts/build-runtime-modules.mjs

@@ -10,7 +10,9 @@ const sources = [
 	"gentle-ai-binary",
 	"review-relay-contract",
 	"review-integration-v2",
+	"review-risk-assessment",
 	"native-review-cli",
+	"telemetry-trigger",
 ];
 const header = "// Generated by scripts/build-runtime-modules.mjs. Do not edit.\n";
 
@@ -36,6 +38,14 @@ async function main() {
 	if ((mode !== "--write" && mode !== "--check") || process.argv.length !== 3) {
 		throw new Error("usage: build-runtime-modules.mjs --write|--check");
 	}
+	// Pi loads these directly as TypeScript. Check syntax without generating
+	// another runtime copy or expanding the published module boundary.
+	for (const path of ["lib/runtime-metrics-delivery.ts", "lib/runtime-metrics-native.ts",
+		"lib/runtime-metrics-children.ts", "extensions/runtime-metrics.ts"]) {
+		const source = await readFile(join(root, path), "utf8");
+		assertNoTrailingWhitespace(source, path);
+		stripTypeScriptTypes(source, { mode: "strip" });
+	}
 	const runtime = join(root, "runtime");
 	if (mode === "--write") await mkdir(runtime, { recursive: true });
 	const drift = [];
@@ -57,7 +67,7 @@ async function main() {
 	if (drift.length > 0) {
 		throw new Error(`generated runtime is stale: ${drift.join(", ")}`);
 	}
-	process.stdout.write(`runtime ${mode === "--write" ? "generated" : "matches TypeScript sources"} (${sources.length} modules)\n`);
+	process.stdout.write(`runtime ${mode === "--write" ? "generated" : "matches TypeScript sources"} (${sources.length} generated modules; one-shot metrics sources validated)\n`);
 }
 
 main().catch((error) => {

package/scripts/check-types.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// Type gate for a project that does not compile cleanly yet.
+//
+// `tsc --noEmit` reports a fixed set of diagnostics on this repository today, so
+// the gate is a ratchet rather than a clean pass: it fails when the number of
+// diagnostics grows for any (file, error code) pair, or when the total grows.
+// Fixing diagnostics and refreshing the baseline is the intended way to shrink
+// it.
+//
+// Known blind spot, stated rather than hidden: keying on (file, code) counts is
+// what keeps the baseline stable while files are edited, because line numbers
+// shift. A single change that removes one diagnostic and introduces another of
+// the same code in the same file therefore passes. The total check catches that
+// whenever the counts differ at all.
+//
+// Usage:
+//   node scripts/check-types.mjs            fail on any new diagnostic
+//   node scripts/check-types.mjs --update   rewrite the baseline and exit 0
+
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const baselinePath = join(packageRoot, "scripts", "types-baseline.json");
+const configPath = join(packageRoot, "tsconfig.json");
+const DIAGNOSTIC = /^(.*?)\((\d+),(\d+)\): error (TS\d+): (.*)$/;
+const REPORT_LIMIT = 20;
+
+function relativeToPackage(file) {
+	return relative(packageRoot, file).split("\\").join("/");
+}
+
+function compile() {
+	let tsc;
+	try {
+		tsc = createRequire(import.meta.url).resolve("typescript/bin/tsc");
+	} catch {
+		console.error("types: cannot resolve the TypeScript compiler. Run `pnpm install` first.");
+		process.exit(1);
+	}
+	try {
+		execFileSync(process.execPath, [tsc, "-p", configPath], {
+			cwd: packageRoot,
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		return "";
+	} catch (error) {
+		// tsc exits non-zero when it reports diagnostics and writes them to stdout.
+		return `${error.stdout ?? ""}${error.stderr ?? ""}`;
+	}
+}
+
+function summarize(output) {
+	const counts = new Map();
+	const samples = new Map();
+	let total = 0;
+	for (const line of output.split(/\r?\n/)) {
+		const match = DIAGNOSTIC.exec(line);
+		if (!match) continue;
+		const key = `${relativeToPackage(match[1])} ${match[4]}`;
+		counts.set(key, (counts.get(key) ?? 0) + 1);
+		if (!samples.has(key)) samples.set(key, match[5].trim());
+		total += 1;
+	}
+	return { counts, samples, total };
+}
+
+function writeBaseline(summary) {
+	const byFileAndCode = Object.fromEntries([...summary.counts].sort(([left], [right]) => left.localeCompare(right)));
+	const payload = {
+		note: "Recorded TypeScript diagnostics. Regenerate with `node scripts/check-types.mjs --update` after fixing or deliberately accepting diagnostics. This file may only shrink without a review decision.",
+		total: summary.total,
+		byFileAndCode,
+	};
+	writeFileSync(baselinePath, `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+const summary = summarize(compile());
+
+if (process.argv.includes("--update")) {
+	writeBaseline(summary);
+	console.log(`types: baseline recorded ${summary.total} diagnostic(s) across ${summary.counts.size} file/code pair(s)`);
+	process.exit(0);
+}
+
+let baseline;
+try {
+	baseline = JSON.parse(readFileSync(baselinePath, "utf8"));
+} catch (error) {
+	console.error(`types: cannot read ${relativeToPackage(baselinePath)}: ${error instanceof Error ? error.message : String(error)}`);
+	process.exit(1);
+}
+
+const regressions = [];
+for (const [key, count] of summary.counts) {
+	const recorded = baseline.byFileAndCode[key] ?? 0;
+	if (count > recorded) regressions.push({ key, added: count - recorded, message: summary.samples.get(key) ?? "" });
+}
+
+const totalGrew = summary.total > baseline.total;
+
+if (regressions.length > 0 || totalGrew) {
+	if (regressions.length > 0) {
+		console.error(`types: ${regressions.length} file/code pair(s) report more diagnostics than recorded:`);
+		for (const regression of regressions.slice(0, REPORT_LIMIT)) {
+			console.error(`  +${regression.added}  ${regression.key}  ${regression.message.slice(0, 100)}`);
+		}
+		if (regressions.length > REPORT_LIMIT) console.error(`  ... and ${regressions.length - REPORT_LIMIT} more`);
+	}
+	if (totalGrew) {
+		console.error(`types: total ${summary.total} exceeds the recorded ${baseline.total}`);
+	}
+	console.error("Fix the new diagnostics, or run `node scripts/check-types.mjs --update` when they are deliberately accepted.");
+	process.exit(1);
+}
+
+const improved = [...Object.entries(baseline.byFileAndCode)].filter(([key, count]) => (summary.counts.get(key) ?? 0) < count).length;
+console.log(
+	`types: ${summary.total} recorded diagnostic(s), no regressions` +
+		(improved > 0 ? `; ${improved} file/code pair(s) improved, run --update to shrink the baseline` : ""),
+);