@cldmv/gh-broker 0.7.0 → 0.9.0

package/src/verbs/repo-tier.ts

@@ -1,90 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/repo-tier.ts
- *	@Date: 2026-10-04T15:40:09-07:00 (1791153609)
- *	@Author: Nate Corcoran <CLDMV>
- *	@Email: <Shinrai@users.noreply.github.com>
- *	-----
- *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-04T16:41:24-07:00 (1791157284)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-/**
- * Classifies a repo into the CLDMV flow tiers the maintenance skills care about.
- *
- *  - `v4`        — carries the v4 release workflow and is a normal next → master staging-flow repo.
- *  - `dev-trunk` — a v4 repo whose real code lives on a persistent `dev` branch while the default
- *                  branch / `next` hold only the scaffold.
- *  - `non-v4`    — no v4 release workflow on the default branch (even if `next`/`hotfixes` exist).
- *
- * Detection is structural, from three cheap reads, so a skill doesn't have to walk branches and
- * workflow folders itself. It is a signal, not a verdict: a stale `dev` branch on a repo whose
- * `next` happens to equal `master` right after a release looks like a dev-trunk repo, so the
- * raw `signals` are returned for the caller to cross-check.
- */
-
-import type { Octokit } from "@octokit/core";
-import { CallBudget, CallBudgetExhausted, RateLimited, reqOne } from "./rest-client.ts";
-
-export type RepoTierName = "v4" | "dev-trunk" | "non-v4";
-
-export interface RepoTier {
-	tier: RepoTierName;
-	signals: {
-		/** `.github/workflows/next-release.yml` exists on the default branch. */
-		v4Workflow: boolean;
-		defaultBranch?: string;
-		/** `next` branch exists. */
-		next?: boolean;
-		/** `dev` branch exists. */
-		dev?: boolean;
-		/** `next` is at the same commit as the default branch (nothing queued; scaffold-only when dev exists). */
-		nextEqualsDefault?: boolean;
-		/** `dev` is at a different commit than the default branch. */
-		devDiffersFromDefault?: boolean;
-	};
-}
-
-async function getOrUndefined<T>(octokit: Octokit, budget: CallBudget, route: string, params: Record<string, unknown>): Promise<T | undefined> {
-	try {
-		return await reqOne<T>(octokit, budget, route, params);
-	} catch (err) {
-		if (err instanceof RateLimited || err instanceof CallBudgetExhausted) throw err;
-		if ((err as { status?: number }).status === 404) return undefined;
-		throw err;
-	}
-}
-
-export async function classifyRepo(octokit: Octokit, budget: CallBudget, owner: string, repo: string): Promise<RepoTier> {
-	const info = await getOrUndefined<{ default_branch?: string }>(octokit, budget, "GET /repos/{owner}/{repo}", { owner, repo });
-	const defaultBranch = info?.default_branch;
-	const workflow = await getOrUndefined<unknown>(octokit, budget, "GET /repos/{owner}/{repo}/contents/{path}", {
-		owner,
-		repo,
-		path: ".github/workflows/next-release.yml",
-		...(defaultBranch ? { ref: defaultBranch } : {})
-	});
-	const v4Workflow = workflow !== undefined;
-	if (!v4Workflow) return { tier: "non-v4", signals: { v4Workflow, ...(defaultBranch ? { defaultBranch } : {}) } };
-
-	const sha = async (branch: string): Promise<string | undefined> => {
-		const b = await getOrUndefined<{ commit?: { sha?: string } }>(octokit, budget, "GET /repos/{owner}/{repo}/branches/{branch}", { owner, repo, branch });
-		return b?.commit?.sha;
-	};
-	const [defaultSha, nextSha, devSha] = await Promise.all([defaultBranch ? sha(defaultBranch) : undefined, sha("next"), sha("dev")]);
-	const signals: RepoTier["signals"] = {
-		v4Workflow,
-		...(defaultBranch ? { defaultBranch } : {}),
-		next: nextSha !== undefined,
-		dev: devSha !== undefined,
-		...(nextSha && defaultSha ? { nextEqualsDefault: nextSha === defaultSha } : {}),
-		...(devSha && defaultSha ? { devDiffersFromDefault: devSha !== defaultSha } : {})
-	};
-	const scaffoldOnly = nextSha === undefined || nextSha === defaultSha;
-	const tier: RepoTierName = devSha !== undefined && signals.devDiffersFromDefault && scaffoldOnly ? "dev-trunk" : "v4";
-	return { tier, signals };
-}

package/src/verbs/report_ci_status.ts

@@ -1,358 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/report_ci_status.ts
- *	@Date: 2026-09-29T02:39:40+00:00 (1790649580)
- *	@Author: Nate Corcoran <CLDMV>
- *	@Email: <Shinrai@users.noreply.github.com>
- *	-----
- *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-02T11:30:58-07:00 (1790965858)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-import type { Octokit } from "@octokit/core";
-import { CallBudget, CallBudgetExhausted, RateLimited, paginate, reqOne } from "./rest-client.ts";
-
-/**
- * Custom verb: report_ci_status — CI health for a PR (or every open PR in a repo),
- * at a verbosity the caller chooses: counts only by default, escalating to
- * run/job detail, failing-step detail, and finally a tail of the failing job's log.
- *
- * Run/job/step classification is built on the GitHub Actions REST API
- * (`/actions/runs`, `/actions/runs/{id}/jobs`), NOT the Checks API
- * (`get_check_runs`, already proxied via `pull_request_read`) — verified live that
- * the configured read PAT has Actions access but not Checks access (fine-grained
- * PAT permissions are separate scopes). Building on Actions avoids needing a PAT
- * permission change to ship this.
- *
- * Tier 3's log fetch instead goes through the hosted MCP's own `get_job_logs` tool
- * (`fetchFailedJobLogs`, injected by the caller — router.ts has the upstream/token
- * this verb doesn't) rather than a hand-rolled REST call: `get_job_logs` already
- * does exactly this (`run_id` + `failed_only: true` fetches every failing job in a
- * run in one call, with its own `tail_lines`), so there's no reason to duplicate
- * it. One call per failing RUN, not per failing job. This means tier-3 log fetches
- * are NOT counted by the CallBudget below (that only tracks direct `octokit.request`
- * calls and their rate-limit headers) — an accepted gap, not an oversight: an
- * upstream-forwarded MCP call exposes no rate-limit headers to inspect, and the
- * fan-out is already bounded (one call per ACTUALLY-failing run, not per PR).
- *
- * Classification (run/job/step all share this): `status !== "completed"` is
- * "pending"; a completed run/job/step is "failed" unless its conclusion is
- * success/neutral/skipped (those three are non-blocking outcomes, not failures).
- *
- * Fan-out: verbosity >= 1 detail (job/step calls, and >= 3's log fetch) is only
- * ever spent on runs/jobs that are ACTUALLY failing — a healthy PR costs exactly
- * one call regardless of verbosity. When `pull` is omitted, only PRs with at least
- * one failure are included in the result (see rest-client.ts for the shared
- * call-budget + rate-limit-floor mechanics, identical to report_unlabeled's).
- */
-
-export type Verbosity = 0 | 1 | 2 | 3;
-
-/**
- * Fetches every failing job's log (already tailed to `tailLines`) for one workflow
- * run, keyed by job id — the shape `get_job_logs` returns with `failed_only: true`.
- * Injected by the caller (router.ts), which holds the upstream/token this verb
- * doesn't. Absent (or a lookup miss for a given job) just means no `logTail` on
- * that failure — best-effort, never a hard failure of the whole report.
- */
-export type FailedJobLogsFetcher = (runId: number, tailLines: number) => Promise<Map<number, string>>;
-
-export interface ReportCiStatusInput {
-	owner: string;
-	repo: string;
-	/** PR number; omit to scan every open PR in the repo. */
-	pull?: number;
-	verbosity?: Verbosity;
-	/** Tier-3 only: tail lines of the failing job's log. Default 200, hard cap 2000. */
-	logLines?: number;
-	/** Safety cap on open PRs scanned when `pull` is omitted. Default 50, hard cap 200. */
-	maxPulls?: number;
-	/** Hard ceiling on total REST calls for this invocation. Default 250, hard cap 1000. */
-	maxApiCalls?: number;
-}
-
-export interface CiSummary {
-	passed: number;
-	failed: number;
-	pending: number;
-}
-
-export interface CiStepFailure {
-	name: string;
-	number: number;
-	conclusion: string;
-	durationMs: number;
-}
-
-export interface CiFailure {
-	workflow: string;
-	job: string;
-	runId: number;
-	runUrl: string;
-	conclusion: string;
-	/** Tier >= 2: the job's failing steps. */
-	steps?: CiStepFailure[];
-	/**
-	 * Tier 3: tail of the JOB's combined log (not per-step — GitHub's job log is one
-	 * concatenated stream across all steps; reliably slicing it per-step would need
-	 * parsing timestamp/group markers, which is fragile. The job-level tail almost
-	 * always contains the actual failure output anyway.
-	 */
-	logTail?: string;
-}
-
-export type TruncatedReason = "max-pulls" | "max-api-calls" | "rate-limited";
-
-interface Truncation {
-	truncated: true;
-	truncatedReason: TruncatedReason;
-	retryAfterSeconds?: number;
-}
-
-export interface CiStatusResult extends Partial<Truncation> {
-	pull: number;
-	summary: CiSummary;
-	failures?: CiFailure[];
-}
-
-export interface ReportCiStatusResult extends Partial<Truncation> {
-	scanned: { pulls: number };
-	results: CiStatusResult[];
-}
-
-const DEFAULT_LOG_LINES = 200;
-const HARD_LOG_LINES = 2000;
-const DEFAULT_MAX_PULLS = 50;
-const HARD_MAX_PULLS = 200;
-const DEFAULT_MAX_API_CALLS = 250;
-const HARD_MAX_API_CALLS = 1000;
-
-interface RawRun {
-	id: number;
-	name: string;
-	status: string;
-	conclusion: string | null;
-	html_url: string;
-}
-
-interface RawStep {
-	name: string;
-	status: string;
-	conclusion: string | null;
-	number: number;
-	started_at: string | null;
-	completed_at: string | null;
-}
-
-interface RawJob {
-	id: number;
-	name: string;
-	status: string;
-	conclusion: string | null;
-	html_url: string;
-	steps?: RawStep[];
-}
-
-type Outcome = "passed" | "failed" | "pending";
-
-/** Non-blocking completed conclusions — everything else completed counts as failed. */
-const NON_FAILING_CONCLUSIONS = new Set(["success", "neutral", "skipped"]);
-
-function classify(status: string, conclusion: string | null): Outcome {
-	if (status !== "completed") return "pending";
-	return conclusion !== null && NON_FAILING_CONCLUSIONS.has(conclusion) ? "passed" : "failed";
-}
-
-function stepDurationMs(step: RawStep): number {
-	if (!step.started_at || !step.completed_at) return 0;
-	return new Date(step.completed_at).getTime() - new Date(step.started_at).getTime();
-}
-
-function truncationFrom(err: unknown): Truncation | undefined {
-	if (err instanceof RateLimited) {
-		return { truncated: true, truncatedReason: "rate-limited", ...(err.retryAfterSeconds !== undefined ? { retryAfterSeconds: err.retryAfterSeconds } : {}) };
-	}
-	if (err instanceof CallBudgetExhausted) return { truncated: true, truncatedReason: "max-api-calls" };
-	return undefined;
-}
-
-async function computeForPull(
-	octokit: Octokit,
-	budget: CallBudget,
-	owner: string,
-	repo: string,
-	pullNumber: number,
-	headSha: string,
-	verbosity: Verbosity,
-	logLines: number,
-	fetchFailedJobLogs?: FailedJobLogsFetcher
-): Promise<CiStatusResult> {
-	const summary: CiSummary = { passed: 0, failed: 0, pending: 0 };
-	const failures: CiFailure[] = [];
-	try {
-		const runs = await paginate<RawRun>(
-			octokit,
-			budget,
-			"GET /repos/{owner}/{repo}/actions/runs",
-			{ owner, repo, head_sha: headSha },
-			100,
-			(d) => (d as { workflow_runs: RawRun[] }).workflow_runs
-		);
-
-		const failedRuns: RawRun[] = [];
-		for (const run of runs) {
-			const outcome = classify(run.status, run.conclusion);
-			summary[outcome]++;
-			if (outcome === "failed") failedRuns.push(run);
-		}
-
-		if (verbosity >= 1) {
-			for (const run of failedRuns) {
-				const jobs = await paginate<RawJob>(
-					octokit,
-					budget,
-					"GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs",
-					{ owner, repo, run_id: run.id },
-					100,
-					(d) => (d as { jobs: RawJob[] }).jobs
-				);
-				// One get_job_logs call per FAILING RUN (not per job) — failed_only:true
-				// already returns every failing job's log in that run at once.
-				const logsByJobId = verbosity >= 3 && fetchFailedJobLogs ? await fetchFailedJobLogs(run.id, logLines) : undefined;
-				for (const job of jobs) {
-					if (classify(job.status, job.conclusion) !== "failed") continue;
-					const failure: CiFailure = { workflow: run.name, job: job.name, runId: run.id, runUrl: run.html_url, conclusion: job.conclusion ?? "unknown" };
-					if (verbosity >= 2) {
-						failure.steps = (job.steps ?? [])
-							.filter((s) => classify(s.status, s.conclusion) === "failed")
-							.map((s) => ({ name: s.name, number: s.number, conclusion: s.conclusion ?? "unknown", durationMs: stepDurationMs(s) }));
-					}
-					const logTail = logsByJobId?.get(job.id);
-					if (logTail !== undefined) failure.logTail = logTail;
-					failures.push(failure);
-				}
-			}
-		}
-	} catch (err) {
-		const t = truncationFrom(err);
-		if (t) return { pull: pullNumber, summary, ...(failures.length ? { failures } : {}), ...t };
-		throw err;
-	}
-
-	const result: CiStatusResult = { pull: pullNumber, summary };
-	if (verbosity >= 1) result.failures = failures;
-	return result;
-}
-
-function clampVerbosity(v: number | undefined): Verbosity {
-	return Math.min(Math.max(v ?? 0, 0), 3) as Verbosity;
-}
-
-/**
- * CI status for a PR whose head sha is already known — skips the PR lookup
- * `reportCiStatus` would otherwise make. Used by router.ts's `pull_request_read`
- * augmentation, which already has the PR (and its head sha) from the forwarded
- * upstream response.
- */
-export async function ciStatusForHeadSha(
-	octokit: Octokit,
-	owner: string,
-	repo: string,
-	pullNumber: number,
-	headSha: string,
-	opts: { verbosity?: number; logLines?: number; maxApiCalls?: number; fetchFailedJobLogs?: FailedJobLogsFetcher } = {}
-): Promise<CiStatusResult> {
-	const budget = new CallBudget(Math.min(opts.maxApiCalls ?? DEFAULT_MAX_API_CALLS, HARD_MAX_API_CALLS));
-	return computeForPull(
-		octokit,
-		budget,
-		owner,
-		repo,
-		pullNumber,
-		headSha,
-		clampVerbosity(opts.verbosity),
-		Math.min(opts.logLines ?? DEFAULT_LOG_LINES, HARD_LOG_LINES),
-		opts.fetchFailedJobLogs
-	);
-}
-
-export async function reportCiStatus(
-	octokit: Octokit,
-	input: ReportCiStatusInput,
-	fetchFailedJobLogs?: FailedJobLogsFetcher
-): Promise<CiStatusResult | ReportCiStatusResult> {
-	const verbosity = clampVerbosity(input.verbosity);
-	const logLines = Math.min(input.logLines ?? DEFAULT_LOG_LINES, HARD_LOG_LINES);
-	const maxApiCalls = Math.min(input.maxApiCalls ?? DEFAULT_MAX_API_CALLS, HARD_MAX_API_CALLS);
-	const budget = new CallBudget(maxApiCalls);
-
-	if (input.pull !== undefined) {
-		const pullNumber = input.pull;
-		try {
-			const pr = await reqOne<{ head: { sha: string } }>(octokit, budget, "GET /repos/{owner}/{repo}/pulls/{pull_number}", {
-				owner: input.owner,
-				repo: input.repo,
-				pull_number: pullNumber
-			});
-			return await computeForPull(octokit, budget, input.owner, input.repo, pullNumber, pr.head.sha, verbosity, logLines, fetchFailedJobLogs);
-		} catch (err) {
-			const t = truncationFrom(err);
-			if (t) return { pull: pullNumber, summary: { passed: 0, failed: 0, pending: 0 }, ...t };
-			throw err;
-		}
-	}
-
-	const maxPulls = Math.min(input.maxPulls ?? DEFAULT_MAX_PULLS, HARD_MAX_PULLS);
-	let pulls: Array<{ number: number; head: { sha: string } }>;
-	try {
-		pulls = await paginate(octokit, budget, "GET /repos/{owner}/{repo}/pulls", { owner: input.owner, repo: input.repo, state: "open" }, maxPulls);
-	} catch (err) {
-		const t = truncationFrom(err);
-		if (t) return { scanned: { pulls: 0 }, results: [], ...t };
-		throw err;
-	}
-
-	const results: CiStatusResult[] = [];
-	let scanned = 0;
-	let aggregateTruncation: Truncation | undefined;
-	for (const p of pulls) {
-		const r = await computeForPull(octokit, budget, input.owner, input.repo, p.number, p.head.sha, verbosity, logLines, fetchFailedJobLogs);
-		if (r.truncated) {
-			// Didn't finish evaluating this PR — don't count it as scanned, but surface
-			// it (and stop entirely: the budget/rate limit is gone for the next PR too).
-			results.push(r);
-			aggregateTruncation = { truncated: true, truncatedReason: r.truncatedReason as TruncatedReason, ...(r.retryAfterSeconds !== undefined ? { retryAfterSeconds: r.retryAfterSeconds } : {}) };
-			break;
-		}
-		scanned++;
-		if (r.summary.failed > 0) results.push(r);
-	}
-	if (!aggregateTruncation && pulls.length === maxPulls) aggregateTruncation = { truncated: true, truncatedReason: "max-pulls" };
-
-	return { scanned: { pulls: scanned }, results, ...aggregateTruncation };
-}
-
-/** JSON Schema advertised to the agent for report_ci_status. */
-export const REPORT_CI_STATUS_SCHEMA = {
-	type: "object" as const,
-	required: ["owner", "repo"],
-	additionalProperties: false,
-	properties: {
-		owner: { type: "string", description: "repository owner (org/user login) — selects the read credential" },
-		repo: { type: "string", description: "repository name" },
-		pull: { type: "number", description: "PR number; omit to scan every open PR in the repo (only PRs with a failure are included in the result)" },
-		verbosity: {
-			type: "number",
-			enum: [0, 1, 2, 3],
-			default: 0,
-			description: "0: pass/fail/pending counts only. 1: + which run/job failed (workflow, job, runId, runUrl). 2: + which step in that job failed. 3: + a tail of the failing job's log."
-		},
-		logLines: { type: "number", description: `tier-3 only: tail lines of the failing job's log (default ${DEFAULT_LOG_LINES}, hard cap ${HARD_LOG_LINES})` },
-		maxPulls: { type: "number", description: `safety cap on open PRs scanned when pull is omitted (default ${DEFAULT_MAX_PULLS}, hard cap ${HARD_MAX_PULLS})` },
-		maxApiCalls: { type: "number", description: `hard ceiling on total REST calls this invocation makes (default ${DEFAULT_MAX_API_CALLS}, hard cap ${HARD_MAX_API_CALLS})` }
-	}
-};

package/src/verbs/report_release_prs.ts

@@ -1,238 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/report_release_prs.ts
- *	@Date: 2026-10-03T15:00:00+00:00 (1791039600)
- *	@Author: Nate Corcoran <CLDMV>
- *	@Email: <Shinrai@users.noreply.github.com>
- *	-----
- *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-03T15:00:00+00:00 (1791039600)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-import type { Octokit } from "@octokit/core";
-import { CallBudget, CallBudgetExhausted, RateLimited, reqOne } from "./rest-client.ts";
-import { analyzeRelease, type ReleaseAnalysis, type ReleaseVerdict } from "./release-analysis.ts";
-
-/**
- * Custom verb: report_release_prs — every open release PR for an owner (or one repo),
- * with whether its version's changelog file is already on the release branch.
- *
- * Built for mass updates: an agent sweeping a fleet needs to know which repos have a
- * release PR waiting and which of those still lack the curated per-version changelog
- * (`docs/changelog[s]/v<major>/vX.Y.Z.md`, the exact file the CLDMV release automation
- * injects as the release-PR body). Per-repo `list_pull_requests` over every repo would
- * be hundreds of calls; this uses ONE search call for the whole owner plus two cheap
- * calls per release PR actually found.
- *
- * A "release PR" is an open PR carrying the `release` label (applied by the v4 release
- * automation to both the `next → master` and `hotfixes → master` PRs). The version is
- * read from the `release: vX.Y.Z - …` title.
- *
- * The changelog is looked up at the PR's head commit, not the default branch — the file
- * lands on `next` before the release PR merges, so that is where it must exist.
- */
-
-export interface ReportReleasePrsInput {
-	owner: string;
-	/** Repo name; omit to search every repo this owner has. */
-	repo?: string;
-	/** Return only release PRs that are not ready (missing changelog or unreadable version). Default false. */
-	onlyMissing?: boolean;
-	/**
-	 * Also work out, per release PR, what is still open against its release branch, whether an existing
-	 * changelog is actually up to date, and a verdict (done / in-flight / wait / gray / write / update / inspect).
-	 * Costs about 5 more REST calls per release PR, so raise `maxApiCalls` for a whole org. Default false.
-	 */
-	analyze?: boolean;
-	/** Hard ceiling on total REST calls for this invocation. Default 300, hard-capped at 1000. */
-	maxApiCalls?: number;
-}
-
-export type ReleasePrStatus = "ready" | "needs-changelog" | "unknown-version";
-
-export interface ReleasePr {
-	repo: string;
-	pull: number;
-	url: string;
-	title: string;
-	/** Parsed from the `release: vX.Y.Z` title; null when the title has no version. */
-	version: string | null;
-	head: string;
-	base: string;
-	draft: boolean;
-	status: ReleasePrStatus;
-	/** The changelog path found, when `status` is "ready". */
-	changelogPath?: string;
-	/** The paths that were looked up, when `status` is "needs-changelog". */
-	checkedPaths?: string[];
-	/** Only with `analyze: true`. */
-	analysis?: ReleaseAnalysis;
-}
-
-export type ReleaseTruncatedReason = "max-results" | "incomplete-search" | "max-api-calls" | "rate-limited";
-
-export interface ReportReleasePrsResult {
-	scanned: { releasePrs: number };
-	summary: { ready: number; needsChangelog: number; unknownVersion: number };
-	/** Only with `analyze: true`: how many release PRs landed on each verdict. */
-	verdicts?: Partial<Record<ReleaseVerdict, number>>;
-	releasePrs: ReleasePr[];
-	truncated?: boolean;
-	truncatedReason?: ReleaseTruncatedReason;
-	/** Only set when truncatedReason is "rate-limited" and GitHub sent a Retry-After. */
-	retryAfterSeconds?: number;
-}
-
-const DEFAULT_MAX_API_CALLS = 300;
-const HARD_MAX_API_CALLS = 1000;
-const SEARCH_PAGE_SIZE = 100;
-
-interface SearchHit {
-	number: number;
-	title: string;
-	html_url: string;
-	draft?: boolean;
-	repository_url: string;
-}
-
-interface SearchResponse {
-	total_count: number;
-	incomplete_results: boolean;
-	items: SearchHit[];
-}
-
-interface RawPull {
-	head: { ref: string };
-	base: { ref: string };
-	draft?: boolean;
-}
-
-/** Pulls `1.2.3` (or a prerelease form) out of a `release: v1.2.3 - …` title. */
-export function parseReleaseVersion(title: string): string | null {
-	const m = /\brelease:\s*v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/i.exec(title);
-	return m ? m[1]! : null;
-}
-
-/** The places a version's changelog can live — `changelog` and `changelogs` are both in use. */
-export function changelogPaths(version: string): string[] {
-	const major = version.split(".")[0]!;
-	return [`docs/changelog/v${major}/v${version}.md`, `docs/changelogs/v${major}/v${version}.md`];
-}
-
-function repoFromUrl(repositoryUrl: string): { owner: string; repo: string } {
-	const parts = repositoryUrl.split("/");
-	return { owner: parts[parts.length - 2]!, repo: parts[parts.length - 1]! };
-}
-
-/** First of `paths` that exists at `ref`, or undefined. A 404 means "not there"; any other error propagates. */
-async function findChangelog(octokit: Octokit, budget: CallBudget, owner: string, repo: string, ref: string, paths: string[]): Promise<string | undefined> {
-	for (const path of paths) {
-		try {
-			await reqOne(octokit, budget, "GET /repos/{owner}/{repo}/contents/{path}", { owner, repo, path, ref });
-			return path;
-		} catch (err) {
-			if (err instanceof RateLimited || err instanceof CallBudgetExhausted) throw err;
-			if ((err as { status?: number }).status !== 404) throw err;
-		}
-	}
-	return undefined;
-}
-
-export async function reportReleasePrs(octokit: Octokit, input: ReportReleasePrsInput): Promise<ReportReleasePrsResult> {
-	const maxApiCalls = Math.min(input.maxApiCalls ?? DEFAULT_MAX_API_CALLS, HARD_MAX_API_CALLS);
-	const budget = new CallBudget(maxApiCalls);
-	const scope = input.repo ? `repo:${input.owner}/${input.repo}` : `org:${input.owner}`;
-
-	const releasePrs: ReleasePr[] = [];
-	let truncatedReason: ReleaseTruncatedReason | undefined;
-	let retryAfterSeconds: number | undefined;
-	let hits = 0;
-
-	try {
-		const search = await reqOne<SearchResponse>(octokit, budget, "GET /search/issues", {
-			q: `${scope} is:pr is:open label:release`,
-			per_page: SEARCH_PAGE_SIZE
-		});
-		hits = search.items.length;
-		if (search.total_count > search.items.length) truncatedReason = "max-results";
-		else if (search.incomplete_results) truncatedReason = "incomplete-search";
-
-		for (const hit of search.items) {
-			const { owner, repo } = repoFromUrl(hit.repository_url);
-			const pull = await reqOne<RawPull>(octokit, budget, "GET /repos/{owner}/{repo}/pulls/{pull_number}", { owner, repo, pull_number: hit.number });
-			const version = parseReleaseVersion(hit.title);
-			const base = {
-				repo: `${owner}/${repo}`,
-				pull: hit.number,
-				url: hit.html_url,
-				title: hit.title,
-				version,
-				head: pull.head.ref,
-				base: pull.base.ref,
-				draft: pull.draft ?? hit.draft ?? false
-			};
-			let entry: ReleasePr;
-			if (version === null) {
-				entry = { ...base, status: "unknown-version" };
-			} else {
-				const paths = changelogPaths(version);
-				const found = await findChangelog(octokit, budget, owner, repo, pull.head.ref, paths);
-				entry = found ? { ...base, status: "ready", changelogPath: found } : { ...base, status: "needs-changelog", checkedPaths: paths };
-			}
-			// Pushed before the analysis so a cap hit mid-analysis still reports this PR's status.
-			releasePrs.push(entry);
-			if (input.analyze) {
-				entry.analysis = await analyzeRelease(octokit, budget, { owner, repo, pull: hit.number, head: pull.head.ref, version, ...(entry.changelogPath ? { changelogPath: entry.changelogPath } : {}) });
-			}
-		}
-	} catch (err) {
-		if (err instanceof RateLimited) {
-			truncatedReason = "rate-limited";
-			retryAfterSeconds = err.retryAfterSeconds;
-		} else if (err instanceof CallBudgetExhausted) {
-			truncatedReason = "max-api-calls";
-		} else {
-			throw err;
-		}
-	}
-
-	const summary = {
-		ready: releasePrs.filter((p) => p.status === "ready").length,
-		needsChangelog: releasePrs.filter((p) => p.status === "needs-changelog").length,
-		unknownVersion: releasePrs.filter((p) => p.status === "unknown-version").length
-	};
-	let verdicts: Partial<Record<ReleaseVerdict, number>> | undefined;
-	if (input.analyze) {
-		verdicts = {};
-		for (const p of releasePrs) if (p.analysis) verdicts[p.analysis.verdict] = (verdicts[p.analysis.verdict] ?? 0) + 1;
-	}
-	// With analysis, "missing" means "not done": a ready-but-stale changelog still needs work.
-	const listed = input.onlyMissing ? releasePrs.filter((p) => (p.analysis ? p.analysis.verdict !== "done" : p.status !== "ready")) : releasePrs;
-
-	return {
-		scanned: { releasePrs: hits },
-		summary,
-		...(verdicts ? { verdicts } : {}),
-		releasePrs: listed,
-		...(truncatedReason ? { truncated: true, truncatedReason } : {}),
-		...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {})
-	};
-}
-
-/** JSON Schema advertised to the agent for report_release_prs. */
-export const REPORT_RELEASE_PRS_SCHEMA = {
-	type: "object" as const,
-	required: ["owner"],
-	additionalProperties: false,
-	properties: {
-		owner: { type: "string", description: "repository owner (org/user login) — selects the read credential" },
-		repo: { type: "string", description: "repository name; omit to search every repo this owner has" },
-		onlyMissing: { type: "boolean", description: "return only release PRs that still need work (no changelog, unreadable version, or — with analyze — a verdict other than done); summary counts still cover all", default: false },
-		analyze: { type: "boolean", description: "also compute, per release PR: open PRs against its release branch (doc / dependency / feature / draft), whether an existing changelog is up to date (missing PRs, version heading, README), and a verdict (done / in-flight / wait / gray / write / update / inspect). ~5 extra calls per release PR — raise maxApiCalls for a whole org", default: false },
-		maxApiCalls: { type: "number", description: `hard ceiling on total REST calls this invocation makes (default ${DEFAULT_MAX_API_CALLS}, hard cap ${HARD_MAX_API_CALLS})` }
-	}
-};