@cldmv/gh-broker 0.8.0 → 0.9.0

package/src/verbs/release-analysis.ts

@@ -1,212 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/release-analysis.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-31T23:26:36-07:00 (1793514396)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-/**
- * Release-readiness analysis for report_release_prs `analyze: true`.
- *
- * This is the decision logic the release-docs skill used to walk by hand: what is still open against
- * the release's integration branch, whether an existing changelog actually covers what merged, and
- * the resulting verdict. The pure helpers (parsing, classification, coverage, verdict) are exported
- * for tests; `analyzeRelease` does the reads.
- */
-
-import type { Octokit } from "@octokit/core";
-import { CallBudget, CallBudgetExhausted, RateLimited, paginate, reqOne } from "./rest-client.ts";
-
-export type OpenPrKind = "doc" | "dependency" | "feature" | "draft";
-
-export interface OpenPr {
-	number: number;
-	title: string;
-	url: string;
-	kind: OpenPrKind;
-	/** Version named in a doc PR's title (`v1.2.3`), when it has one. */
-	version?: string;
-}
-
-export type FreshnessStatus = "current" | "minor-gap" | "stale" | "version-drift" | "thin";
-
-export interface CoverageGap {
-	number: number;
-	title: string;
-}
-
-export interface Freshness {
-	status: FreshnessStatus;
-	/** Non-doc PRs that shipped in this release (the expected coverage). */
-	expectedPrs: number;
-	/** User-facing PRs the changelog never mentions — these make it stale. */
-	missingUserFacing: CoverageGap[];
-	/** CI / chore / style / test PRs it never mentions — reported, but not stale on their own. */
-	missingInternal: CoverageGap[];
-	/** The changelog's own heading carries the release PR's current version. */
-	headingMatchesVersion: boolean;
-	/** The README What's New block names this version. */
-	readmeMentionsVersion: boolean;
-}
-
-export type ReleaseVerdict = "done" | "in-flight" | "wait" | "gray" | "write" | "update" | "inspect";
-
-export interface ReleaseAnalysis {
-	openPrs: OpenPr[];
-	/** Set only when a changelog file exists. */
-	freshness?: Freshness;
-	/** A doc PR's version differs from the release PR's current version. */
-	docVersionMismatch?: boolean;
-	verdict: ReleaseVerdict;
-	/** One line explaining the verdict. */
-	reason: string;
-}
-
-const INTERNAL_TYPES = new Set(["ci", "chore", "style", "test"]);
-
-/** `feat(scope)!: x` -> `feat`. Returns "" when the subject is not conventional. */
-export function commitType(subject: string): string {
-	const m = /^([a-z]+)(?:\([^)]*\))?!?:/i.exec(subject.trim());
-	return m ? m[1]!.toLowerCase() : "";
-}
-
-export interface ReleaseCommitPr {
-	number: number;
-	title: string;
-	type: string;
-}
-
-/**
- * PR numbers shipped by a release, from the commits of its release PR. Only the first line of each
- * commit is read: squash bodies list other PR numbers and would fake coverage. Docs PRs (they describe
- * the release rather than being part of it) and the version bump are dropped.
- */
-export function releaseCommitPrs(messages: string[]): ReleaseCommitPr[] {
-	const seen = new Map<number, ReleaseCommitPr>();
-	for (const message of messages) {
-		const subject = message.split("\n", 1)[0]!.trim();
-		let number: number | undefined;
-		let title = subject;
-		const squash = /\(#(\d+)\)\s*$/.exec(subject);
-		const merge = /^Merge pull request #(\d+)\b/.exec(subject);
-		if (squash) {
-			number = Number(squash[1]);
-			title = subject.slice(0, squash.index).trim();
-		} else if (merge) {
-			number = Number(merge[1]);
-		}
-		if (number === undefined) continue;
-		const type = commitType(title);
-		if (type === "docs" || /^chore: bump version/i.test(title)) continue;
-		if (!seen.has(number)) seen.set(number, { number, title, type });
-	}
-	return [...seen.values()];
-}
-
-/** Every PR number a changelog mentions, by `#N` or `/pull/N`. */
-export function mentionedPrs(changelog: string): Set<number> {
-	const out = new Set<number>();
-	for (const m of changelog.matchAll(/(?:#|\/pull\/)(\d+)\b/g)) out.add(Number(m[1]));
-	return out;
-}
-
-export function classifyOpenPr(pr: { number: number; title: string; html_url: string; draft?: boolean; head?: { ref?: string }; user?: { login?: string }; labels?: Array<{ name?: string }> }): OpenPr {
-	const title = pr.title;
-	const labels = (pr.labels ?? []).map((l) => l.name ?? "");
-	let kind: OpenPrKind;
-	if (pr.draft) kind = "draft";
-	else if (/^docs?(\([^)]*\))?!?:/i.test(title) || (pr.head?.ref ?? "").startsWith("docs/")) kind = "doc";
-	else if (labels.includes("type: dependencies") || /^deps?(\([^)]*\))?!?:/i.test(title) || (pr.user?.login ?? "").toLowerCase().startsWith("dependabot")) kind = "dependency";
-	else kind = "feature";
-	const v = kind === "doc" ? /\bv?(\d+\.\d+\.\d+)\b/.exec(title) : null;
-	return { number: pr.number, title, url: pr.html_url, kind, ...(v ? { version: v[1]! } : {}) };
-}
-
-export function assessFreshness(version: string, changelog: string, commits: ReleaseCommitPr[], readme: string | undefined): Freshness {
-	const mentioned = mentionedPrs(changelog);
-	const missing = commits.filter((c) => !mentioned.has(c.number));
-	const missingUserFacing = missing.filter((c) => !INTERNAL_TYPES.has(c.type)).map(({ number, title }) => ({ number, title }));
-	const missingInternal = missing.filter((c) => INTERNAL_TYPES.has(c.type)).map(({ number, title }) => ({ number, title }));
-	// String.prototype.split always returns at least one element, so the "" fallback is unreachable; it only satisfies noUncheckedIndexedAccess.
-	/* v8 ignore next */
-	const firstLine = changelog.split("\n", 1)[0] ?? "";
-	const headingMatchesVersion = new RegExp(`v?${version.replace(/\./g, "\\.")}\\b`).test(firstLine);
-	const readmeMentionsVersion = readme !== undefined && new RegExp(`Latest:\\s*v?${version.replace(/\./g, "\\.")}\\b`).test(readme);
-	const thin = changelog.length < 400 || !/^##\s+Overview/m.test(changelog);
-	let status: FreshnessStatus = "current";
-	if (!headingMatchesVersion) status = "version-drift";
-	else if (missingUserFacing.length > 0) status = "stale";
-	else if (thin) status = "thin";
-	else if (missingInternal.length > 0) status = "minor-gap";
-	return { status, expectedPrs: commits.length, missingUserFacing, missingInternal, headingMatchesVersion, readmeMentionsVersion };
-}
-
-/** The release-docs decision table. */
-export function decideVerdict(args: { hasChangelog: boolean; unknownVersion: boolean; freshness?: Freshness; openPrs: OpenPr[]; version: string | null }): { verdict: ReleaseVerdict; reason: string; docVersionMismatch?: boolean } {
-	if (args.unknownVersion) return { verdict: "inspect", reason: "the release PR title has no `release: vX.Y.Z` version" };
-	const f = args.freshness;
-	if (args.hasChangelog && f && (f.status === "current" || f.status === "minor-gap")) {
-		return { verdict: "done", reason: f.status === "minor-gap" ? `changelog covers every user-facing change; ${f.missingInternal.length} internal PR(s) not mentioned` : "changelog is current" };
-	}
-	const docs = args.openPrs.filter((p) => p.kind === "doc");
-	const features = args.openPrs.filter((p) => p.kind === "feature");
-	const others = args.openPrs.filter((p) => p.kind === "dependency" || p.kind === "draft");
-	const need = args.hasChangelog ? `changelog is ${f?.status ?? "out of date"}` : "no changelog file";
-	if (docs.length > 0) {
-		const mismatch = args.version !== null && docs.some((d) => d.version !== undefined && d.version !== args.version);
-		return { verdict: "in-flight", reason: `${need}; doc PR #${docs[0]!.number} is open`, ...(mismatch ? { docVersionMismatch: true } : {}) };
-	}
-	if (features.length > 0) return { verdict: "wait", reason: `${need}; ${features.length} feature/fix PR(s) still open against the release branch` };
-	if (others.length > 0) return { verdict: "gray", reason: `${need}; only dependency PR(s) or drafts are open (${others.length})` };
-	return { verdict: args.hasChangelog ? "update" : "write", reason: `${need}; nothing is open against the release branch` };
-}
-
-function decodeContent(data: unknown): string | undefined {
-	const d = data as { content?: string; encoding?: string } | undefined;
-	if (!d || typeof d.content !== "string") return undefined;
-	return d.encoding === "base64" ? Buffer.from(d.content, "base64").toString("utf8") : d.content;
-}
-
-async function getText(octokit: Octokit, budget: CallBudget, owner: string, repo: string, path: string, ref: string): Promise<string | undefined> {
-	try {
-		return decodeContent(await reqOne(octokit, budget, "GET /repos/{owner}/{repo}/contents/{path}", { owner, repo, path, ref }));
-	} 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 analyzeRelease(
-	octokit: Octokit,
-	budget: CallBudget,
-	args: { owner: string; repo: string; pull: number; head: string; version: string | null; changelogPath?: string }
-): Promise<ReleaseAnalysis> {
-	const { owner, repo } = args;
-	const open = await paginate<Parameters<typeof classifyOpenPr>[0]>(octokit, budget, "GET /repos/{owner}/{repo}/pulls", { owner, repo, state: "open", base: args.head }, 200);
-	const openPrs = open.map(classifyOpenPr);
-
-	let freshness: Freshness | undefined;
-	if (args.changelogPath && args.version) {
-		const commits = await paginate<{ commit?: { message?: string } }>(octokit, budget, "GET /repos/{owner}/{repo}/pulls/{pull_number}/commits", { owner, repo, pull_number: args.pull }, 300);
-		const changelog = (await getText(octokit, budget, owner, repo, args.changelogPath, args.head)) ?? "";
-		const readme = await getText(octokit, budget, owner, repo, "README.md", args.head);
-		freshness = assessFreshness(args.version, changelog, releaseCommitPrs(commits.map((c) => c.commit?.message ?? "")), readme);
-	}
-	const decision = decideVerdict({ hasChangelog: Boolean(args.changelogPath), unknownVersion: args.version === null, freshness, openPrs, version: args.version });
-	return {
-		openPrs,
-		...(freshness ? { freshness } : {}),
-		...(decision.docVersionMismatch ? { docVersionMismatch: true } : {}),
-		verdict: decision.verdict,
-		reason: decision.reason
-	};
-}

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})` }
-	}
-};