@f5xc-salesdemos/xcsh 2.2.0 → 14.0.2

package/src/tools/gh.ts

@@ -0,0 +1,2546 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type {
+	AgentTool,
+	AgentToolContext,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+} from "@f5xc-salesdemos/pi-agent-core";
+import { abortableSleep, isEnoent, prompt, untilAborted } from "@f5xc-salesdemos/pi-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import ghIssueViewDescription from "../prompts/tools/gh-issue-view.md" with { type: "text" };
+import ghPrCheckoutDescription from "../prompts/tools/gh-pr-checkout.md" with { type: "text" };
+import ghPrDiffDescription from "../prompts/tools/gh-pr-diff.md" with { type: "text" };
+import ghPrPushDescription from "../prompts/tools/gh-pr-push.md" with { type: "text" };
+import ghPrViewDescription from "../prompts/tools/gh-pr-view.md" with { type: "text" };
+import ghRepoViewDescription from "../prompts/tools/gh-repo-view.md" with { type: "text" };
+import ghRunWatchDescription from "../prompts/tools/gh-run-watch.md" with { type: "text" };
+import ghSearchIssuesDescription from "../prompts/tools/gh-search-issues.md" with { type: "text" };
+import ghSearchPrsDescription from "../prompts/tools/gh-search-prs.md" with { type: "text" };
+import * as git from "../utils/git";
+import type { ToolSession } from ".";
+import type { OutputMeta } from "./output-meta";
+import { ToolError, throwIfAborted } from "./tool-errors";
+import { toolResult } from "./tool-result";
+
+const GH_REPO_FIELDS = [
+	"nameWithOwner",
+	"description",
+	"url",
+	"defaultBranchRef",
+	"homepageUrl",
+	"forkCount",
+	"isArchived",
+	"isFork",
+	"primaryLanguage",
+	"repositoryTopics",
+	"stargazerCount",
+	"updatedAt",
+	"viewerPermission",
+	"visibility",
+];
+const GH_ISSUE_FIELDS = [
+	"author",
+	"body",
+	"comments",
+	"createdAt",
+	"labels",
+	"number",
+	"state",
+	"stateReason",
+	"title",
+	"updatedAt",
+	"url",
+];
+const GH_ISSUE_FIELDS_NO_COMMENTS = [
+	"author",
+	"body",
+	"createdAt",
+	"labels",
+	"number",
+	"state",
+	"stateReason",
+	"title",
+	"updatedAt",
+	"url",
+];
+const GH_PR_FIELDS = [
+	"author",
+	"baseRefName",
+	"body",
+	"comments",
+	"createdAt",
+	"files",
+	"headRefName",
+	"isDraft",
+	"labels",
+	"mergeStateStatus",
+	"number",
+	"reviewDecision",
+	"state",
+	"title",
+	"updatedAt",
+	"url",
+];
+const GH_PR_FIELDS_NO_COMMENTS = [
+	"author",
+	"baseRefName",
+	"body",
+	"createdAt",
+	"files",
+	"headRefName",
+	"isDraft",
+	"labels",
+	"mergeStateStatus",
+	"number",
+	"reviews",
+	"reviewDecision",
+	"state",
+	"title",
+	"updatedAt",
+	"url",
+];
+const GH_REPO_CLONE_FIELDS = ["nameWithOwner", "sshUrl", "url"];
+const GH_PR_CHECKOUT_FIELDS = [
+	"baseRefName",
+	"headRefName",
+	"headRefOid",
+	"headRepository",
+	"headRepositoryOwner",
+	"isCrossRepository",
+	"maintainerCanModify",
+	"number",
+	"title",
+	"url",
+];
+const GH_SEARCH_FIELDS = [
+	"author",
+	"createdAt",
+	"labels",
+	"number",
+	"repository",
+	"state",
+	"title",
+	"updatedAt",
+	"url",
+];
+const SEARCH_LIMIT_DEFAULT = 10;
+const SEARCH_LIMIT_MAX = 50;
+const FILE_PREVIEW_LIMIT = 50;
+const RUN_WATCH_INTERVAL_DEFAULT = 3;
+const RUN_WATCH_GRACE_DEFAULT = 5;
+const RUN_WATCH_TAIL_DEFAULT = 15;
+const RUN_WATCH_TAIL_MAX = 200;
+const REVIEW_COMMENTS_PAGE_SIZE = 100;
+const RUN_JOBS_PAGE_SIZE = 100;
+const PR_URL_PATTERN = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)(?:\/.*)?$/;
+const RUN_URL_PATTERN = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/actions\/runs\/(\d+)(?:\/.*)?$/;
+const RUN_SUCCESS_CONCLUSIONS = new Set(["success", "neutral", "skipped"]);
+const RUN_FAILURE_CONCLUSIONS = new Set(["failure", "timed_out", "cancelled", "action_required", "startup_failure"]);
+const JOB_FAILURE_CONCLUSIONS = new Set(["failure", "timed_out", "cancelled", "action_required"]);
+
+const ghRepoViewSchema = Type.Object({
+	repo: Type.Optional(
+		Type.String({
+			description: "Repository in OWNER/REPO format. Defaults to the current GitHub repository context.",
+		}),
+	),
+	branch: Type.Optional(Type.String({ description: "Branch name to inspect instead of the default branch." })),
+});
+
+const ghIssueViewSchema = Type.Object({
+	issue: Type.String({ description: "Issue number or full GitHub issue URL." }),
+	repo: Type.Optional(
+		Type.String({ description: "Repository in OWNER/REPO format. Omit when passing a full issue URL." }),
+	),
+	comments: Type.Optional(Type.Boolean({ description: "Include issue comments (default: true)." })),
+});
+
+const ghPrViewSchema = Type.Object({
+	pr: Type.Optional(
+		Type.String({
+			description:
+				"Pull request number, full GitHub pull request URL, or branch name. Defaults to the current branch PR.",
+		}),
+	),
+	repo: Type.Optional(
+		Type.String({ description: "Repository in OWNER/REPO format. Omit when passing a full pull request URL." }),
+	),
+	comments: Type.Optional(Type.Boolean({ description: "Include pull request comments (default: true)." })),
+});
+
+const ghPrDiffSchema = Type.Object({
+	pr: Type.Optional(
+		Type.String({
+			description:
+				"Pull request number, full GitHub pull request URL, or branch name. Defaults to the current branch PR.",
+		}),
+	),
+	repo: Type.Optional(
+		Type.String({ description: "Repository in OWNER/REPO format. Omit when passing a full pull request URL." }),
+	),
+	nameOnly: Type.Optional(
+		Type.Boolean({ description: "Return only changed file names instead of unified diff output." }),
+	),
+	exclude: Type.Optional(
+		Type.Array(Type.String({ description: "Glob pattern for files to exclude from the diff." }), {
+			description: "File globs to exclude from the diff output.",
+		}),
+	),
+});
+
+const ghPrCheckoutSchema = Type.Object({
+	pr: Type.Optional(
+		Type.String({
+			description:
+				"Pull request number, full GitHub pull request URL, or branch name. Defaults to the current branch PR.",
+		}),
+	),
+	repo: Type.Optional(
+		Type.String({ description: "Repository in OWNER/REPO format. Omit when passing a full pull request URL." }),
+	),
+	branch: Type.Optional(Type.String({ description: "Local branch name to create or reuse (default: pr-<number>)." })),
+	worktree: Type.Optional(
+		Type.String({ description: "Worktree path to create. Defaults to <repo>/.worktrees/<branch>." }),
+	),
+	force: Type.Optional(
+		Type.Boolean({
+			description: "Reset an existing local branch to the PR head when it is not already checked out elsewhere.",
+		}),
+	),
+});
+
+const ghPrPushSchema = Type.Object({
+	branch: Type.Optional(
+		Type.String({
+			description: "Local branch name to push. Defaults to the current checked-out git branch.",
+		}),
+	),
+	forceWithLease: Type.Optional(Type.Boolean({ description: "Use --force-with-lease when pushing the PR branch." })),
+});
+
+const ghSearchIssuesSchema = Type.Object({
+	query: Type.String({ description: "GitHub issue search query. Supports GitHub search syntax." }),
+	repo: Type.Optional(Type.String({ description: "Repository in OWNER/REPO format to scope the search." })),
+	limit: Type.Optional(Type.Number({ description: "Maximum results to return (default: 10, max: 50)." })),
+});
+
+const ghSearchPrsSchema = Type.Object({
+	query: Type.String({ description: "GitHub pull request search query. Supports GitHub search syntax." }),
+	repo: Type.Optional(Type.String({ description: "Repository in OWNER/REPO format to scope the search." })),
+	limit: Type.Optional(Type.Number({ description: "Maximum results to return (default: 10, max: 50)." })),
+});
+
+const ghRunWatchSchema = Type.Object({
+	run: Type.Optional(
+		Type.String({
+			description:
+				"GitHub Actions run ID or full run URL. Omitting this watches the workflow runs for the current HEAD commit on the selected branch.",
+		}),
+	),
+	branch: Type.Optional(
+		Type.String({
+			description: "Branch to inspect when omitting `run`. Defaults to the current checked-out git branch.",
+		}),
+	),
+	tail: Type.Optional(
+		Type.Number({ description: "Number of log lines to include per failed job (default: 15, max: 200)." }),
+	),
+});
+
+type GhRepoViewInput = Static<typeof ghRepoViewSchema>;
+type GhIssueViewInput = Static<typeof ghIssueViewSchema>;
+type GhPrViewInput = Static<typeof ghPrViewSchema>;
+type GhPrDiffInput = Static<typeof ghPrDiffSchema>;
+type GhPrCheckoutInput = Static<typeof ghPrCheckoutSchema>;
+type GhPrPushInput = Static<typeof ghPrPushSchema>;
+type GhSearchIssuesInput = Static<typeof ghSearchIssuesSchema>;
+type GhSearchPrsInput = Static<typeof ghSearchPrsSchema>;
+type GhRunWatchInput = Static<typeof ghRunWatchSchema>;
+
+export interface GhToolDetails {
+	meta?: OutputMeta;
+	artifactId?: string;
+	repo?: string;
+	branch?: string;
+	worktreePath?: string;
+	remote?: string;
+	remoteBranch?: string;
+	headSha?: string;
+	runId?: number;
+	runIds?: number[];
+	status?: string;
+	conclusion?: string;
+	failedJobs?: string[];
+	watch?: GhRunWatchViewDetails;
+}
+
+export interface GhRunWatchJobDetails {
+	id: number;
+	name: string;
+	status?: string;
+	conclusion?: string;
+	durationSeconds?: number;
+	url?: string;
+}
+
+export interface GhRunWatchRunDetails {
+	id: number;
+	workflowName?: string;
+	displayTitle?: string;
+	status?: string;
+	conclusion?: string;
+	branch?: string;
+	headSha?: string;
+	url?: string;
+	jobs: GhRunWatchJobDetails[];
+}
+
+export interface GhRunWatchFailedLogDetails {
+	runId: number;
+	workflowName?: string;
+	jobName: string;
+	conclusion?: string;
+	tail?: string;
+	available: boolean;
+}
+
+export interface GhRunWatchViewDetails {
+	mode: "run" | "commit";
+	state: "watching" | "completed";
+	repo: string;
+	branch?: string;
+	headSha?: string;
+	pollCount?: number;
+	note?: string;
+	run?: GhRunWatchRunDetails;
+	runs?: GhRunWatchRunDetails[];
+	failedLogs?: GhRunWatchFailedLogDetails[];
+}
+
+interface GhUser {
+	login?: string;
+	name?: string | null;
+}
+
+interface GhLabel {
+	name?: string;
+}
+
+interface GhComment {
+	author?: GhUser | null;
+	body?: string;
+	createdAt?: string;
+	url?: string;
+	isMinimized?: boolean;
+	minimizedReason?: string | null;
+}
+
+interface GhRepoTopic {
+	name?: string;
+	topic?: { name?: string };
+}
+
+interface GhRepoLanguage {
+	name?: string;
+}
+
+interface GhRepoBranch {
+	name?: string;
+}
+
+interface GhRepoViewData {
+	nameWithOwner?: string;
+	description?: string | null;
+	url?: string;
+	sshUrl?: string;
+	defaultBranchRef?: GhRepoBranch | null;
+	homepageUrl?: string | null;
+	forkCount?: number;
+	isArchived?: boolean;
+	isFork?: boolean;
+	primaryLanguage?: GhRepoLanguage | null;
+	repositoryTopics?: GhRepoTopic[];
+	stargazerCount?: number;
+	updatedAt?: string;
+	viewerPermission?: string | null;
+	visibility?: string | null;
+}
+
+interface GhIssueViewData {
+	author?: GhUser | null;
+	body?: string | null;
+	comments?: GhComment[];
+	createdAt?: string;
+	labels?: GhLabel[];
+	number?: number;
+	state?: string;
+	stateReason?: string | null;
+	title?: string;
+	updatedAt?: string;
+	url?: string;
+}
+
+interface GhPrFile {
+	path?: string;
+	additions?: number;
+	deletions?: number;
+	changeType?: string;
+}
+
+interface GhPrViewData extends GhIssueViewData {
+	baseRefName?: string;
+	files?: GhPrFile[];
+	headRefName?: string;
+	headRefOid?: string;
+	headRepository?: GhRepoViewData | null;
+	headRepositoryOwner?: GhUser | null;
+	isCrossRepository?: boolean;
+	isDraft?: boolean;
+	maintainerCanModify?: boolean;
+	mergeStateStatus?: string;
+	reviewComments?: GhPrReviewComment[];
+	reviews?: GhPrReview[];
+	reviewDecision?: string;
+}
+
+interface GhPrReviewCommit {
+	oid?: string | null;
+}
+
+interface GhPrReview {
+	author?: GhUser | null;
+	body?: string | null;
+	commit?: GhPrReviewCommit | null;
+	state?: string | null;
+	submittedAt?: string | null;
+}
+
+interface GhPrReviewCommentApi {
+	body?: string | null;
+	created_at?: string | null;
+	html_url?: string | null;
+	id?: number;
+	in_reply_to_id?: number | null;
+	line?: number | null;
+	original_line?: number | null;
+	path?: string | null;
+	side?: string | null;
+	user?: GhUser | null;
+}
+
+interface GhPrReviewComment {
+	author?: GhUser | null;
+	body?: string | null;
+	createdAt?: string;
+	id: number;
+	inReplyToId?: number;
+	line?: number;
+	originalLine?: number;
+	path?: string;
+	side?: string;
+	url?: string;
+}
+
+interface GhBranchApiResponse {
+	commit?: {
+		sha?: string | null;
+	} | null;
+}
+
+interface GhSearchRepository {
+	nameWithOwner?: string;
+}
+
+interface GhSearchResult {
+	author?: GhUser | null;
+	createdAt?: string;
+	labels?: GhLabel[];
+	number?: number;
+	repository?: GhSearchRepository | null;
+	state?: string;
+	title?: string;
+	updatedAt?: string;
+	url?: string;
+}
+
+interface GhRunReference {
+	repo?: string;
+	runId?: number;
+}
+
+interface GhActionsRunListResponse {
+	workflow_runs?: GhActionsRunApi[];
+}
+
+interface GhActionsRunApi {
+	id?: number;
+	name?: string | null;
+	display_title?: string | null;
+	status?: string | null;
+	conclusion?: string | null;
+	head_branch?: string | null;
+	head_sha?: string | null;
+	created_at?: string | null;
+	updated_at?: string | null;
+	html_url?: string | null;
+}
+
+interface GhActionsJobsResponse {
+	total_count?: number;
+	jobs?: GhActionsJobApi[];
+}
+
+interface GhActionsJobApi {
+	id?: number;
+	name?: string | null;
+	status?: string | null;
+	conclusion?: string | null;
+	started_at?: string | null;
+	completed_at?: string | null;
+	html_url?: string | null;
+}
+
+interface GhRunJobSnapshot {
+	id: number;
+	name: string;
+	status?: string;
+	conclusion?: string;
+	startedAt?: string;
+	completedAt?: string;
+	url?: string;
+}
+
+interface GhRunSnapshot {
+	id: number;
+	workflowName?: string;
+	displayTitle?: string;
+	status?: string;
+	conclusion?: string;
+	branch?: string;
+	headSha?: string;
+	createdAt?: string;
+	updatedAt?: string;
+	url?: string;
+	jobs: GhRunJobSnapshot[];
+}
+
+interface GhFailedJobLog {
+	run: GhRunSnapshot;
+	job: GhRunJobSnapshot;
+	full?: string;
+	tail?: string;
+	available: boolean;
+}
+
+function normalizeText(value: string | null | undefined): string {
+	return (value ?? "").replaceAll("\r\n", "\n").replaceAll("\r", "\n").replaceAll("\t", "    ").trim();
+}
+
+function normalizeBlock(value: string | null | undefined): string {
+	return (value ?? "").replaceAll("\r\n", "\n").replaceAll("\r", "\n").replaceAll("\t", "    ").trimEnd();
+}
+
+function looksLikeGitHubUrl(value: string | undefined): boolean {
+	return value?.startsWith("https://github.com/") ?? false;
+}
+
+function normalizeOptionalString(value: string | null | undefined): string | undefined {
+	const normalized = value?.trim();
+	return normalized ? normalized : undefined;
+}
+
+function formatShortSha(value: string | undefined): string | undefined {
+	if (!value) {
+		return undefined;
+	}
+
+	return value.slice(0, 12);
+}
+
+function requireNonEmpty(value: string | null | undefined, label: string): string {
+	const normalized = normalizeOptionalString(value);
+	if (!normalized) {
+		throw new ToolError(`${label} must not be empty`);
+	}
+	return normalized;
+}
+
+function resolveSearchLimit(value: number | undefined): number {
+	if (value === undefined) {
+		return SEARCH_LIMIT_DEFAULT;
+	}
+
+	if (!Number.isFinite(value) || value <= 0) {
+		throw new ToolError("limit must be a positive number");
+	}
+
+	return Math.min(Math.floor(value), SEARCH_LIMIT_MAX);
+}
+
+function resolveTailLimit(value: number | undefined): number {
+	if (value === undefined) {
+		return RUN_WATCH_TAIL_DEFAULT;
+	}
+
+	if (!Number.isFinite(value) || value <= 0) {
+		throw new ToolError("tail must be a positive number");
+	}
+
+	return Math.min(Math.floor(value), RUN_WATCH_TAIL_MAX);
+}
+
+function appendRepoFlag(args: string[], repo: string | undefined, identifier?: string): void {
+	if (!repo || looksLikeGitHubUrl(identifier)) {
+		return;
+	}
+
+	args.push("--repo", repo);
+}
+
+function buildGhSearchArgs(
+	command: "issues" | "prs",
+	query: string,
+	limit: number,
+	repo: string | undefined,
+): string[] {
+	const args = ["search", command, "--limit", String(limit), "--json", GH_SEARCH_FIELDS.join(",")];
+	appendRepoFlag(args, repo);
+	args.push("--", query);
+	return args;
+}
+
+function sanitizeRemoteName(value: string): string {
+	const sanitized = value
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+/g, "")
+		.replace(/-+$/g, "");
+	return sanitized.length > 0 ? `fork-${sanitized}` : "fork";
+}
+
+function toLocalBranchRef(value: string): string {
+	return `refs/heads/${value}`;
+}
+
+function stripHeadsRef(value: string | undefined): string | undefined {
+	if (!value) {
+		return undefined;
+	}
+
+	return value.startsWith("refs/heads/") ? value.slice("refs/heads/".length) : value;
+}
+
+async function requireGitRepoRoot(cwd: string, signal?: AbortSignal): Promise<string> {
+	const repoRoot = await git.repo.root(cwd, signal);
+	if (!repoRoot) {
+		throw new ToolError("Current git repository is unavailable.");
+	}
+
+	return repoRoot;
+}
+
+async function requirePrimaryGitRepoRoot(cwd: string, signal?: AbortSignal): Promise<string> {
+	const primaryRepoRoot = await git.repo.primaryRoot(cwd, signal);
+	if (!primaryRepoRoot) {
+		throw new ToolError("Current git repository is unavailable.");
+	}
+
+	return primaryRepoRoot;
+}
+
+async function requireCurrentGitBranch(cwd: string, signal?: AbortSignal): Promise<string> {
+	const branch = await git.branch.current(cwd, signal);
+	if (!branch) {
+		throw new ToolError("Current git branch is unavailable. Pass `branch` or `run` explicitly.");
+	}
+
+	return branch;
+}
+
+async function requireCurrentGitHead(cwd: string, signal?: AbortSignal): Promise<string> {
+	const headSha = await git.head.sha(cwd, signal);
+	if (!headSha) {
+		throw new ToolError("Current git HEAD is unavailable. Pass `run` explicitly.");
+	}
+
+	return headSha;
+}
+
+async function ensureGitWorktreePathAvailable(
+	worktreePath: string,
+	existingWorktrees: git.GitWorktreeEntry[],
+): Promise<void> {
+	const normalizedTarget = path.resolve(worktreePath);
+	const conflictingWorktree = existingWorktrees.find(entry => path.resolve(entry.path) === normalizedTarget);
+	if (conflictingWorktree) {
+		throw new ToolError(`worktree path is already registered: ${conflictingWorktree.path}`);
+	}
+
+	try {
+		await fs.stat(normalizedTarget);
+		throw new ToolError(`worktree path already exists: ${normalizedTarget}`);
+	} catch (error) {
+		if (isEnoent(error)) {
+			return;
+		}
+		throw error;
+	}
+}
+
+function selectPrCloneUrl(originUrl: string | undefined, repo: Pick<GhRepoViewData, "url" | "sshUrl">): string {
+	if (originUrl?.startsWith("http://") || originUrl?.startsWith("https://")) {
+		return normalizeOptionalString(repo.url) ?? normalizeOptionalString(repo.sshUrl) ?? "";
+	}
+
+	return normalizeOptionalString(repo.sshUrl) ?? normalizeOptionalString(repo.url) ?? "";
+}
+
+async function getRemoteUrls(repoRoot: string, signal?: AbortSignal): Promise<Map<string, string>> {
+	const remotes = await git.remote.list(repoRoot, signal);
+	const urls = new Map<string, string>();
+	for (const remoteName of remotes) {
+		const remoteUrl = await git.remote.url(repoRoot, remoteName, signal);
+		if (remoteUrl) {
+			urls.set(remoteName, remoteUrl);
+		}
+	}
+	return urls;
+}
+
+async function ensurePrRemote(
+	repoRoot: string,
+	data: GhPrViewData,
+	signal?: AbortSignal,
+): Promise<{ name: string; url: string }> {
+	if (!data.isCrossRepository) {
+		const originUrl = await git.remote.url(repoRoot, "origin", signal);
+		if (!originUrl) {
+			throw new ToolError("origin remote is unavailable for this repository.");
+		}
+
+		return {
+			name: "origin",
+			url: originUrl,
+		};
+	}
+
+	const headRepository = requireNonEmpty(data.headRepository?.nameWithOwner, "head repository");
+	const repoSummary = await git.github.json<GhRepoViewData>(
+		repoRoot,
+		["repo", "view", headRepository, "--json", GH_REPO_CLONE_FIELDS.join(",")],
+		signal,
+		{ repoProvided: true },
+	);
+	const originUrl = await git.remote.url(repoRoot, "origin", signal);
+	const remoteUrl = selectPrCloneUrl(originUrl, repoSummary);
+	if (!remoteUrl) {
+		throw new ToolError(`Could not determine a clone URL for ${headRepository}.`);
+	}
+
+	const remotes = await getRemoteUrls(repoRoot, signal);
+	for (const [remoteName, url] of remotes) {
+		if (url === remoteUrl) {
+			return { name: remoteName, url };
+		}
+	}
+
+	const preferredRemoteName = sanitizeRemoteName(
+		data.headRepositoryOwner?.login ?? headRepository.split("/")[0] ?? "fork",
+	);
+	let remoteName = preferredRemoteName;
+	let suffix = 2;
+	while (remotes.has(remoteName)) {
+		remoteName = `${preferredRemoteName}-${suffix}`;
+		suffix += 1;
+	}
+
+	await git.remote.add(repoRoot, remoteName, remoteUrl, signal);
+
+	return {
+		name: remoteName,
+		url: remoteUrl,
+	};
+}
+
+async function resolvePrBranchPushTarget(
+	repoRoot: string,
+	localBranch: string,
+	signal?: AbortSignal,
+): Promise<{
+	remoteName: string;
+	remoteBranch: string;
+	remoteUrl?: string;
+	prUrl?: string;
+	maintainerCanModify?: boolean;
+	isCrossRepository: boolean;
+}> {
+	const pushRemote = await git.config.getBranch(repoRoot, localBranch, "pushRemote", signal);
+	const remote = await git.config.getBranch(repoRoot, localBranch, "remote", signal);
+	const mergeRef = await git.config.getBranch(repoRoot, localBranch, "merge", signal);
+	const headRef = await git.config.getBranch(repoRoot, localBranch, "ompPrHeadRef", signal);
+	const prUrl = await git.config.getBranch(repoRoot, localBranch, "ompPrUrl", signal);
+	const maintainerCanModifyValue = await git.config.getBranch(
+		repoRoot,
+		localBranch,
+		"ompPrMaintainerCanModify",
+		signal,
+	);
+	const isCrossRepositoryValue = await git.config.getBranch(repoRoot, localBranch, "ompPrIsCrossRepository", signal);
+
+	const remoteName = pushRemote ?? remote;
+	if (!remoteName) {
+		throw new ToolError(`branch ${localBranch} has no configured push remote`);
+	}
+
+	const remoteBranch = headRef ?? stripHeadsRef(mergeRef);
+	if (!remoteBranch) {
+		throw new ToolError(`branch ${localBranch} has no tracked PR head ref`);
+	}
+
+	return {
+		remoteName,
+		remoteBranch,
+		remoteUrl: await git.remote.url(repoRoot, remoteName, signal),
+		prUrl,
+		maintainerCanModify:
+			maintainerCanModifyValue === undefined
+				? undefined
+				: ["1", "true", "yes", "on"].includes(maintainerCanModifyValue.toLowerCase()),
+		isCrossRepository: ["1", "true", "yes", "on"].includes((isCrossRepositoryValue ?? "").toLowerCase()),
+	};
+}
+
+function formatAuthor(author: GhUser | null | undefined): string | undefined {
+	if (!author) return undefined;
+	if (author.login) return `@${author.login}`;
+	if (author.name) return author.name;
+	return undefined;
+}
+
+function formatLabels(labels: GhLabel[] | undefined): string | undefined {
+	const names = labels?.map(label => label.name).filter((value): value is string => Boolean(value)) ?? [];
+	if (names.length === 0) return undefined;
+	return names.join(", ");
+}
+
+function pushLine(lines: string[], label: string, value: string | number | boolean | undefined): void {
+	if (value === undefined || value === "") return;
+	lines.push(`${label}: ${value}`);
+}
+
+function parseRunReference(value: string | undefined): GhRunReference {
+	const run = normalizeOptionalString(value);
+	if (!run) {
+		return {};
+	}
+
+	if (/^\d+$/.test(run)) {
+		return { runId: Number(run) };
+	}
+
+	const match = run.match(RUN_URL_PATTERN);
+	if (!match) {
+		throw new ToolError("run must be a numeric workflow run ID or a full GitHub Actions run URL");
+	}
+
+	return {
+		repo: match[1],
+		runId: Number(match[2]),
+	};
+}
+
+function parsePullRequestUrl(value: string | undefined): { repo?: string; prNumber?: number } {
+	const normalized = normalizeOptionalString(value);
+	if (!normalized) {
+		return {};
+	}
+
+	const match = normalized.match(PR_URL_PATTERN);
+	if (!match) {
+		return {};
+	}
+
+	return {
+		repo: match[1],
+		prNumber: Number(match[2]),
+	};
+}
+
+function normalizePrReviewComment(comment: GhPrReviewCommentApi): GhPrReviewComment | null {
+	if (typeof comment.id !== "number") {
+		return null;
+	}
+
+	return {
+		author: comment.user ?? null,
+		body: comment.body,
+		createdAt: normalizeOptionalString(comment.created_at),
+		id: comment.id,
+		inReplyToId: typeof comment.in_reply_to_id === "number" ? comment.in_reply_to_id : undefined,
+		line: typeof comment.line === "number" ? comment.line : undefined,
+		originalLine: typeof comment.original_line === "number" ? comment.original_line : undefined,
+		path: normalizeOptionalString(comment.path),
+		side: normalizeOptionalString(comment.side),
+		url: normalizeOptionalString(comment.html_url),
+	};
+}
+
+function normalizeRunJob(job: GhActionsJobApi): GhRunJobSnapshot | null {
+	if (typeof job.id !== "number") {
+		return null;
+	}
+
+	return {
+		id: job.id,
+		name: normalizeOptionalString(job.name) ?? `job-${job.id}`,
+		status: normalizeOptionalString(job.status),
+		conclusion: normalizeOptionalString(job.conclusion),
+		startedAt: normalizeOptionalString(job.started_at),
+		completedAt: normalizeOptionalString(job.completed_at),
+		url: normalizeOptionalString(job.html_url),
+	};
+}
+
+function normalizeRunSnapshot(run: GhActionsRunApi, jobs: GhRunJobSnapshot[]): GhRunSnapshot {
+	if (typeof run.id !== "number") {
+		throw new ToolError("GitHub Actions run response did not include a run ID.");
+	}
+
+	return {
+		id: run.id,
+		workflowName: normalizeOptionalString(run.name),
+		displayTitle: normalizeOptionalString(run.display_title),
+		status: normalizeOptionalString(run.status),
+		conclusion: normalizeOptionalString(run.conclusion),
+		branch: normalizeOptionalString(run.head_branch),
+		headSha: normalizeOptionalString(run.head_sha),
+		createdAt: normalizeOptionalString(run.created_at),
+		updatedAt: normalizeOptionalString(run.updated_at),
+		url: normalizeOptionalString(run.html_url),
+		jobs,
+	};
+}
+
+function getRunOutcome(value: string | undefined): "success" | "failure" | "pending" {
+	if (!value) {
+		return "pending";
+	}
+
+	if (RUN_SUCCESS_CONCLUSIONS.has(value)) {
+		return "success";
+	}
+
+	if (RUN_FAILURE_CONCLUSIONS.has(value)) {
+		return "failure";
+	}
+
+	return "pending";
+}
+
+function getRunSnapshotOutcome(run: GhRunSnapshot): "success" | "failure" | "pending" {
+	if (run.status !== "completed") {
+		return "pending";
+	}
+
+	return getRunOutcome(run.conclusion);
+}
+
+function getRunCollectionOutcome(runs: GhRunSnapshot[]): "success" | "failure" | "pending" {
+	if (runs.length === 0) {
+		return "pending";
+	}
+
+	let pending = false;
+	for (const run of runs) {
+		if (run.jobs.some(isFailedJob)) {
+			return "failure";
+		}
+
+		const outcome = getRunSnapshotOutcome(run);
+		if (outcome === "failure") {
+			return "failure";
+		}
+		if (outcome === "pending") {
+			pending = true;
+		}
+	}
+
+	return pending ? "pending" : "success";
+}
+
+function getRunCollectionSignature(runs: GhRunSnapshot[]): string {
+	return runs
+		.map(run => run.id)
+		.sort((left, right) => left - right)
+		.join(",");
+}
+
+function isFailedJob(job: GhRunJobSnapshot): boolean {
+	return job.conclusion !== undefined && JOB_FAILURE_CONCLUSIONS.has(job.conclusion);
+}
+
+function formatJobState(job: GhRunJobSnapshot): string {
+	return job.conclusion ?? job.status ?? "unknown";
+}
+
+function parseTimestampMs(value: string | undefined): number | undefined {
+	if (!value) {
+		return undefined;
+	}
+
+	const timestamp = Date.parse(value);
+	return Number.isNaN(timestamp) ? undefined : timestamp;
+}
+
+function getJobDurationSeconds(job: GhRunJobSnapshot, observedAtMs: number): number | undefined {
+	const startedAtMs = parseTimestampMs(job.startedAt);
+	if (startedAtMs === undefined) {
+		return undefined;
+	}
+
+	const completedAtMs = parseTimestampMs(job.completedAt) ?? observedAtMs;
+	return Math.max(0, Math.floor((completedAtMs - startedAtMs) / 1000));
+}
+
+function buildRunWatchJobDetails(job: GhRunJobSnapshot, observedAtMs: number): GhRunWatchJobDetails {
+	return {
+		id: job.id,
+		name: job.name,
+		status: job.status,
+		conclusion: job.conclusion,
+		durationSeconds: getJobDurationSeconds(job, observedAtMs),
+		url: job.url,
+	};
+}
+
+function buildRunWatchRunDetails(run: GhRunSnapshot, observedAtMs: number): GhRunWatchRunDetails {
+	return {
+		id: run.id,
+		workflowName: run.workflowName,
+		displayTitle: run.displayTitle,
+		status: run.status,
+		conclusion: run.conclusion,
+		branch: run.branch,
+		headSha: run.headSha,
+		url: run.url,
+		jobs: run.jobs.map(job => buildRunWatchJobDetails(job, observedAtMs)),
+	};
+}
+
+function buildFailedLogDetails(failedJobLogs: GhFailedJobLog[]): GhRunWatchFailedLogDetails[] {
+	return failedJobLogs.map(entry => ({
+		runId: entry.run.id,
+		workflowName: entry.run.workflowName,
+		jobName: entry.job.name,
+		conclusion: entry.job.conclusion,
+		tail: entry.tail,
+		available: entry.available,
+	}));
+}
+
+function renderJobsSection(jobs: GhRunJobSnapshot[]): string[] {
+	if (jobs.length === 0) {
+		return ["## Jobs", "", "No jobs reported yet."];
+	}
+
+	const lines: string[] = [`## Jobs (${jobs.length})`, ""];
+	for (const job of jobs) {
+		lines.push(`- [${formatJobState(job)}] ${job.name}`);
+		if (job.startedAt) {
+			pushLine(lines, "  Started", job.startedAt);
+		}
+		if (job.completedAt) {
+			pushLine(lines, "  Completed", job.completedAt);
+		}
+		if (job.url) {
+			pushLine(lines, "  URL", job.url);
+		}
+	}
+
+	return lines;
+}
+
+function renderFailedJobLogs(
+	failedJobLogs: GhFailedJobLog[],
+	options: { mode: "tail"; tail: number } | { mode: "full" },
+): string[] {
+	if (failedJobLogs.length === 0) {
+		return [];
+	}
+
+	const lines: string[] = ["## Failed Jobs", ""];
+	for (const entry of failedJobLogs) {
+		lines.push(`### ${entry.job.name} [${entry.job.conclusion ?? "failed"}]`);
+		pushLine(lines, "Run", `#${entry.run.id}`);
+		pushLine(lines, "Workflow", entry.run.workflowName ?? undefined);
+		if (entry.job.startedAt) {
+			pushLine(lines, "Started", entry.job.startedAt);
+		}
+		if (entry.job.completedAt) {
+			pushLine(lines, "Completed", entry.job.completedAt);
+		}
+		if (entry.job.url) {
+			pushLine(lines, "URL", entry.job.url);
+		}
+		lines.push("");
+		const logText = options.mode === "full" ? entry.full : entry.tail;
+		if (entry.available && logText) {
+			lines.push(options.mode === "full" ? "Full log:" : `Last ${options.tail} log lines:`);
+			lines.push("```text");
+			lines.push(logText);
+			lines.push("```");
+		} else {
+			lines.push(options.mode === "full" ? "Full log unavailable." : "Log tail unavailable.");
+		}
+		lines.push("");
+	}
+
+	return lines;
+}
+
+function renderRunSection(run: GhRunSnapshot): string[] {
+	const label = run.workflowName ? `### Run #${run.id} - ${run.workflowName}` : `### Run #${run.id}`;
+	const lines: string[] = [label, ""];
+	pushLine(lines, "Title", run.displayTitle ?? undefined);
+	pushLine(lines, "Branch", run.branch ?? undefined);
+	pushLine(lines, "Commit", formatShortSha(run.headSha));
+	pushLine(lines, "Status", run.status);
+	pushLine(lines, "Conclusion", run.conclusion ?? undefined);
+	pushLine(lines, "Created", run.createdAt);
+	pushLine(lines, "Updated", run.updatedAt);
+	pushLine(lines, "URL", run.url);
+	lines.push("");
+	lines.push(...renderJobsSection(run.jobs));
+	return lines;
+}
+
+function formatRunWatchSnapshot(
+	repo: string,
+	run: GhRunSnapshot,
+	pollCount: number,
+	note?: string,
+	includeOutcome: boolean = false,
+): string {
+	const failedJobs = run.jobs.filter(isFailedJob);
+	const lines: string[] = [`# Watching GitHub Actions Run #${run.id}`, ""];
+	pushLine(lines, "Repository", repo);
+	pushLine(lines, "Workflow", run.workflowName ?? undefined);
+	pushLine(lines, "Title", run.displayTitle ?? undefined);
+	pushLine(lines, "Branch", run.branch ?? undefined);
+	pushLine(lines, "Status", run.status);
+	pushLine(lines, "Conclusion", run.conclusion ?? undefined);
+	pushLine(lines, "Created", run.createdAt);
+	pushLine(lines, "Updated", run.updatedAt);
+	pushLine(lines, "URL", run.url);
+	pushLine(lines, "Poll", pollCount);
+	pushLine(lines, "Failed jobs", failedJobs.length || undefined);
+
+	if (note) {
+		lines.push("");
+		lines.push(`Note: ${note}`);
+	}
+
+	lines.push("");
+	lines.push(...renderJobsSection(run.jobs));
+
+	if (includeOutcome) {
+		lines.push("");
+		lines.push(failedJobs.length > 0 ? "Failures detected." : "All jobs passed.");
+	}
+
+	return lines.join("\n").trim();
+}
+
+function formatRunWatchResult(
+	repo: string,
+	run: GhRunSnapshot,
+	failedJobLogs: GhFailedJobLog[],
+	tail: number,
+	options?: { mode?: "tail" | "full" },
+): string {
+	const failedJobs = run.jobs.filter(isFailedJob);
+	const lines: string[] = [`# GitHub Actions Run #${run.id}`, ""];
+	pushLine(lines, "Repository", repo);
+	pushLine(lines, "Workflow", run.workflowName ?? undefined);
+	pushLine(lines, "Title", run.displayTitle ?? undefined);
+	pushLine(lines, "Branch", run.branch ?? undefined);
+	pushLine(lines, "Status", run.status);
+	pushLine(lines, "Conclusion", run.conclusion ?? undefined);
+	pushLine(lines, "Created", run.createdAt);
+	pushLine(lines, "Updated", run.updatedAt);
+	pushLine(lines, "URL", run.url);
+	lines.push("");
+	lines.push(...renderJobsSection(run.jobs));
+
+	if (failedJobs.length > 0) {
+		lines.push("");
+		lines.push(
+			...renderFailedJobLogs(failedJobLogs, options?.mode === "full" ? { mode: "full" } : { mode: "tail", tail }),
+		);
+		lines.push("Run failed.");
+	} else if (getRunOutcome(run.conclusion) === "success") {
+		lines.push("");
+		lines.push("All jobs passed.");
+	} else {
+		lines.push("");
+		lines.push("Run completed without successful jobs, but no failed job logs were available.");
+	}
+
+	return lines.join("\n").trim();
+}
+
+function formatCommitRunWatchSnapshot(
+	repo: string,
+	headSha: string,
+	branch: string | undefined,
+	runs: GhRunSnapshot[],
+	pollCount: number,
+	note?: string,
+): string {
+	const failedJobs = runs.flatMap(run => run.jobs.filter(isFailedJob));
+	const completedRuns = runs.filter(run => run.status === "completed").length;
+	const lines: string[] = [`# Watching GitHub Actions for ${formatShortSha(headSha) ?? headSha}`, ""];
+	pushLine(lines, "Repository", repo);
+	pushLine(lines, "Branch", branch);
+	pushLine(lines, "Commit", headSha);
+	pushLine(lines, "Poll", pollCount);
+	pushLine(lines, "Runs", runs.length);
+	pushLine(lines, "Completed runs", `${completedRuns}/${runs.length}`);
+	pushLine(lines, "Failed jobs", failedJobs.length || undefined);
+
+	if (note) {
+		lines.push("");
+		lines.push(`Note: ${note}`);
+	}
+
+	if (runs.length === 0) {
+		lines.push("");
+		lines.push("Waiting for workflow runs for this commit.");
+		return lines.join("\n").trim();
+	}
+
+	for (const run of runs) {
+		lines.push("");
+		lines.push(...renderRunSection(run));
+	}
+
+	return lines.join("\n").trim();
+}
+
+function formatCommitRunWatchResult(
+	repo: string,
+	headSha: string,
+	branch: string | undefined,
+	runs: GhRunSnapshot[],
+	failedJobLogs: GhFailedJobLog[],
+	tail: number,
+	options?: { mode?: "tail" | "full" },
+): string {
+	const outcome = getRunCollectionOutcome(runs);
+	const lines: string[] = [`# GitHub Actions for ${formatShortSha(headSha) ?? headSha}`, ""];
+	pushLine(lines, "Repository", repo);
+	pushLine(lines, "Branch", branch);
+	pushLine(lines, "Commit", headSha);
+	pushLine(lines, "Runs", runs.length);
+
+	for (const run of runs) {
+		lines.push("");
+		lines.push(...renderRunSection(run));
+	}
+
+	if (failedJobLogs.length > 0) {
+		lines.push("");
+		lines.push(
+			...renderFailedJobLogs(failedJobLogs, options?.mode === "full" ? { mode: "full" } : { mode: "tail", tail }),
+		);
+		lines.push("Workflow runs for this commit failed.");
+	} else if (outcome === "success") {
+		lines.push("");
+		lines.push("All workflow runs for this commit passed.");
+	} else {
+		lines.push("");
+		lines.push("Workflow runs for this commit did not complete successfully.");
+	}
+
+	return lines.join("\n").trim();
+}
+
+function buildGhDetails(repo: string, run: GhRunSnapshot): GhToolDetails {
+	return {
+		repo,
+		branch: run.branch,
+		headSha: run.headSha,
+		runId: run.id,
+		runIds: [run.id],
+		status: run.status,
+		conclusion: run.conclusion,
+		failedJobs: run.jobs.filter(isFailedJob).map(job => job.name),
+	};
+}
+
+function buildRunWatchDetails(
+	repo: string,
+	run: GhRunSnapshot,
+	options?: {
+		state?: GhRunWatchViewDetails["state"];
+		pollCount?: number;
+		note?: string;
+		failedJobLogs?: GhFailedJobLog[];
+	},
+): GhToolDetails {
+	const observedAtMs = Date.now();
+	return {
+		...buildGhDetails(repo, run),
+		watch: {
+			mode: "run",
+			state: options?.state ?? "completed",
+			repo,
+			branch: run.branch,
+			headSha: run.headSha,
+			pollCount: options?.pollCount,
+			note: options?.note,
+			run: buildRunWatchRunDetails(run, observedAtMs),
+			failedLogs: buildFailedLogDetails(options?.failedJobLogs ?? []),
+		},
+	};
+}
+
+function buildGhRunCollectionDetails(
+	repo: string,
+	headSha: string,
+	branch: string | undefined,
+	runs: GhRunSnapshot[],
+): GhToolDetails {
+	const outcome = getRunCollectionOutcome(runs);
+	return {
+		repo,
+		branch,
+		headSha,
+		runIds: runs.map(run => run.id),
+		status: runs.length > 0 && runs.every(run => run.status === "completed") ? "completed" : "in_progress",
+		conclusion: outcome,
+		failedJobs: runs.flatMap(run =>
+			run.jobs.filter(isFailedJob).map(job => `${run.workflowName ?? `run ${run.id}`}: ${job.name}`),
+		),
+	};
+}
+
+function buildCommitRunWatchDetails(
+	repo: string,
+	headSha: string,
+	branch: string | undefined,
+	runs: GhRunSnapshot[],
+	options?: {
+		state?: GhRunWatchViewDetails["state"];
+		pollCount?: number;
+		note?: string;
+		failedJobLogs?: GhFailedJobLog[];
+	},
+): GhToolDetails {
+	const observedAtMs = Date.now();
+	return {
+		...buildGhRunCollectionDetails(repo, headSha, branch, runs),
+		watch: {
+			mode: "commit",
+			state: options?.state ?? "completed",
+			repo,
+			branch,
+			headSha,
+			pollCount: options?.pollCount,
+			note: options?.note,
+			runs: runs.map(run => buildRunWatchRunDetails(run, observedAtMs)),
+			failedLogs: buildFailedLogDetails(options?.failedJobLogs ?? []),
+		},
+	};
+}
+
+async function resolveGitHubRepo(
+	cwd: string,
+	repo: string | undefined,
+	runRepo: string | undefined,
+	signal?: AbortSignal,
+): Promise<string> {
+	if (repo && runRepo && repo !== runRepo) {
+		throw new ToolError("run URL repository does not match the provided repo");
+	}
+
+	if (repo) {
+		return repo;
+	}
+
+	if (runRepo) {
+		return runRepo;
+	}
+
+	const resolved = await git.github.text(
+		cwd,
+		["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"],
+		signal,
+	);
+	return requireNonEmpty(resolved, "repo");
+}
+
+async function resolveGitHubBranchHead(
+	cwd: string,
+	repo: string,
+	branch: string,
+	signal?: AbortSignal,
+): Promise<string> {
+	const response = await git.github.json<GhBranchApiResponse>(
+		cwd,
+		["api", "--method", "GET", `/repos/${repo}/branches/${encodeURIComponent(branch)}`],
+		signal,
+		{ repoProvided: true },
+	);
+	return requireNonEmpty(response.commit?.sha, `head SHA for branch ${branch}`);
+}
+
+async function fetchRunsForCommit(
+	cwd: string,
+	repo: string,
+	headSha: string,
+	branch: string | undefined,
+	signal?: AbortSignal,
+): Promise<GhRunSnapshot[]> {
+	const response = await git.github.json<GhActionsRunListResponse>(
+		cwd,
+		[
+			"api",
+			"--method",
+			"GET",
+			`/repos/${repo}/actions/runs`,
+			"-F",
+			`head_sha=${headSha}`,
+			"-F",
+			`per_page=${RUN_JOBS_PAGE_SIZE}`,
+			...(branch ? ["-F", `branch=${branch}`] : []),
+		],
+		signal,
+		{ repoProvided: true },
+	);
+
+	return Promise.all(
+		(response.workflow_runs ?? [])
+			.filter((run): run is GhActionsRunApi & { id: number } => typeof run.id === "number")
+			.map(async run => {
+				const jobs = await fetchRunJobs(cwd, repo, run.id, signal);
+				return normalizeRunSnapshot(run, jobs);
+			}),
+	);
+}
+
+async function fetchRunJobs(
+	cwd: string,
+	repo: string,
+	runId: number,
+	signal?: AbortSignal,
+): Promise<GhRunJobSnapshot[]> {
+	const jobs: GhRunJobSnapshot[] = [];
+	let page = 1;
+
+	while (true) {
+		const response = await git.github.json<GhActionsJobsResponse>(
+			cwd,
+			[
+				"api",
+				"--method",
+				"GET",
+				`/repos/${repo}/actions/runs/${runId}/jobs`,
+				"-F",
+				`per_page=${RUN_JOBS_PAGE_SIZE}`,
+				"-F",
+				`page=${page}`,
+			],
+			signal,
+			{ repoProvided: true },
+		);
+		const pageJobs = (response.jobs ?? [])
+			.map(job => normalizeRunJob(job))
+			.filter((job): job is GhRunJobSnapshot => job !== null);
+		jobs.push(...pageJobs);
+
+		if (pageJobs.length < RUN_JOBS_PAGE_SIZE) {
+			break;
+		}
+
+		if ((response.total_count ?? 0) <= jobs.length) {
+			break;
+		}
+
+		page += 1;
+	}
+
+	return jobs;
+}
+
+async function fetchPrReviewComments(
+	cwd: string,
+	repo: string,
+	prNumber: number,
+	signal?: AbortSignal,
+): Promise<GhPrReviewComment[]> {
+	const reviewComments: GhPrReviewComment[] = [];
+	let page = 1;
+
+	while (true) {
+		const response = await git.github.json<GhPrReviewCommentApi[]>(
+			cwd,
+			[
+				"api",
+				"--method",
+				"GET",
+				`/repos/${repo}/pulls/${prNumber}/comments`,
+				"-F",
+				`per_page=${REVIEW_COMMENTS_PAGE_SIZE}`,
+				"-F",
+				`page=${page}`,
+			],
+			signal,
+			{ repoProvided: true },
+		);
+
+		const pageComments = response
+			.map(comment => normalizePrReviewComment(comment))
+			.filter((comment): comment is GhPrReviewComment => comment !== null);
+		reviewComments.push(...pageComments);
+
+		if (pageComments.length < REVIEW_COMMENTS_PAGE_SIZE) {
+			break;
+		}
+
+		page += 1;
+	}
+
+	return reviewComments;
+}
+
+async function fetchRunSnapshot(
+	cwd: string,
+	repo: string,
+	runId: number,
+	signal?: AbortSignal,
+): Promise<GhRunSnapshot> {
+	const [run, jobs] = await Promise.all([
+		git.github.json<GhActionsRunApi>(
+			cwd,
+			["api", "--method", "GET", `/repos/${repo}/actions/runs/${runId}`],
+			signal,
+			{
+				repoProvided: true,
+			},
+		),
+		fetchRunJobs(cwd, repo, runId, signal),
+	]);
+
+	return normalizeRunSnapshot(run, jobs);
+}
+
+function tailLogLines(log: string, tail: number): string | undefined {
+	const normalized = normalizeBlock(log);
+	if (!normalized) {
+		return undefined;
+	}
+
+	const lines = normalized.split("\n");
+	return lines.slice(-tail).join("\n").trimEnd();
+}
+
+async function fetchFailedJobLogs(
+	cwd: string,
+	repo: string,
+	failedJobs: Array<{ run: GhRunSnapshot; job: GhRunJobSnapshot }>,
+	tail: number,
+	signal?: AbortSignal,
+): Promise<GhFailedJobLog[]> {
+	return Promise.all(
+		failedJobs.map(async entry => {
+			const result = await git.github.run(cwd, ["api", `/repos/${repo}/actions/jobs/${entry.job.id}/logs`], signal);
+			const fullLog = result.exitCode === 0 ? normalizeBlock(result.stdout) : undefined;
+			const logTail = fullLog ? tailLogLines(fullLog, tail) : undefined;
+			return {
+				run: entry.run,
+				job: entry.job,
+				full: fullLog,
+				tail: logTail,
+				available: Boolean(fullLog),
+			};
+		}),
+	);
+}
+
+function formatCommentsSection(comments: GhComment[] | undefined): string[] {
+	if (!comments || comments.length === 0) {
+		return [];
+	}
+
+	const visible = comments.filter(comment => !comment.isMinimized);
+	const hiddenCount = comments.length - visible.length;
+	const lines: string[] = ["## Comments", ""];
+
+	if (visible.length === 0) {
+		lines.push(`No visible comments. Minimized comments omitted: ${hiddenCount}.`);
+		return lines;
+	}
+
+	lines[0] = `## Comments (${visible.length})`;
+
+	for (const comment of visible) {
+		const author = formatAuthor(comment.author) ?? "unknown";
+		const createdAt = comment.createdAt ? ` · ${comment.createdAt}` : "";
+		lines.push(`### ${author}${createdAt}`);
+		lines.push("");
+		lines.push(normalizeText(comment.body) || "No comment body.");
+		if (comment.url) {
+			lines.push("");
+			lines.push(`URL: ${comment.url}`);
+		}
+		lines.push("");
+	}
+
+	if (hiddenCount > 0) {
+		lines.push(`Minimized comments omitted: ${hiddenCount}.`);
+	}
+
+	return lines;
+}
+
+function formatReviewsSection(reviews: GhPrReview[] | undefined): string[] {
+	if (!reviews || reviews.length === 0) {
+		return [];
+	}
+
+	const lines: string[] = [`## Reviews (${reviews.length})`, ""];
+	for (const review of reviews) {
+		const author = formatAuthor(review.author) ?? "unknown";
+		const submittedAt = review.submittedAt ? ` - ${review.submittedAt}` : "";
+		const state = review.state ? ` [${review.state}]` : "";
+		lines.push(`### ${author}${submittedAt}${state}`);
+		if (review.commit?.oid) {
+			lines.push("");
+			lines.push(`Commit: ${formatShortSha(review.commit.oid)}`);
+		}
+		lines.push("");
+		lines.push(normalizeText(review.body) || "No review body.");
+		lines.push("");
+	}
+
+	return lines;
+}
+
+function formatReviewCommentLocation(comment: GhPrReviewComment): string | undefined {
+	if (!comment.path) {
+		return undefined;
+	}
+
+	const line = comment.line ?? comment.originalLine;
+	return line === undefined ? comment.path : `${comment.path}:${line}`;
+}
+
+function formatReviewCommentsSection(comments: GhPrReviewComment[] | undefined): string[] {
+	if (!comments || comments.length === 0) {
+		return [];
+	}
+
+	const lines: string[] = [`## Review Comments (${comments.length})`, ""];
+	for (const comment of comments) {
+		const author = formatAuthor(comment.author) ?? "unknown";
+		const createdAt = comment.createdAt ? ` · ${comment.createdAt}` : "";
+		lines.push(`### ${author}${createdAt}`);
+		lines.push("");
+		pushLine(lines, "Location", formatReviewCommentLocation(comment));
+		pushLine(lines, "Side", comment.side);
+		pushLine(lines, "Reply to", comment.inReplyToId);
+		pushLine(lines, "URL", comment.url);
+		lines.push("");
+		lines.push(normalizeText(comment.body) || "No review comment body.");
+		lines.push("");
+	}
+
+	return lines;
+}
+
+function formatRepoView(data: GhRepoViewData, input: GhRepoViewInput): string {
+	const lines: string[] = [];
+	const name = data.nameWithOwner ?? input.repo ?? "GitHub Repository";
+	lines.push(`# ${name}`);
+	lines.push("");
+	lines.push(normalizeText(data.description) || "No description provided.");
+	lines.push("");
+	pushLine(lines, "URL", data.url);
+	pushLine(lines, "Default branch", data.defaultBranchRef?.name);
+	pushLine(lines, "Branch", normalizeOptionalString(input.branch));
+	pushLine(lines, "Visibility", data.visibility ?? undefined);
+	pushLine(lines, "Viewer permission", data.viewerPermission ?? undefined);
+	pushLine(lines, "Primary language", data.primaryLanguage?.name);
+	pushLine(lines, "Stars", data.stargazerCount);
+	pushLine(lines, "Forks", data.forkCount);
+	pushLine(lines, "Archived", data.isArchived);
+	pushLine(lines, "Fork", data.isFork);
+	pushLine(lines, "Updated", data.updatedAt);
+	pushLine(lines, "Homepage", data.homepageUrl ?? undefined);
+	const topics = data.repositoryTopics
+		?.map(topic => topic.name ?? topic.topic?.name)
+		.filter((value): value is string => Boolean(value))
+		.join(", ");
+	pushLine(lines, "Topics", topics || undefined);
+	return lines.join("\n").trim();
+}
+
+function formatIssueView(data: GhIssueViewData, input: GhIssueViewInput): string {
+	const lines: string[] = [];
+	const issueNumber = data.number ?? input.issue;
+	lines.push(`# Issue #${issueNumber}: ${data.title ?? "Untitled"}`);
+	lines.push("");
+	pushLine(lines, "State", data.state);
+	pushLine(lines, "State reason", data.stateReason ?? undefined);
+	pushLine(lines, "Author", formatAuthor(data.author));
+	pushLine(lines, "Created", data.createdAt);
+	pushLine(lines, "Updated", data.updatedAt);
+	pushLine(lines, "Labels", formatLabels(data.labels));
+	pushLine(lines, "URL", data.url);
+	lines.push("");
+	lines.push("## Body");
+	lines.push("");
+	lines.push(normalizeText(data.body) || "No description provided.");
+
+	if ((input.comments ?? true) && data.comments) {
+		const commentSection = formatCommentsSection(data.comments);
+		if (commentSection.length > 0) {
+			lines.push("");
+			lines.push(...commentSection);
+		}
+	}
+
+	return lines.join("\n").trim();
+}
+
+function formatPrFiles(files: GhPrFile[] | undefined): string[] {
+	if (!files || files.length === 0) return [];
+
+	const lines: string[] = [`## Files (${files.length})`, ""];
+	for (const file of files.slice(0, FILE_PREVIEW_LIMIT)) {
+		const changeType = file.changeType ?? "CHANGED";
+		const additions = file.additions ?? 0;
+		const deletions = file.deletions ?? 0;
+		lines.push(`- ${file.path ?? "(unknown file)"} [${changeType}] (+${additions} -${deletions})`);
+	}
+
+	if (files.length > FILE_PREVIEW_LIMIT) {
+		lines.push(`- ... ${files.length - FILE_PREVIEW_LIMIT} more files`);
+	}
+
+	return lines;
+}
+
+function formatPrView(data: GhPrViewData, input: GhPrViewInput): string {
+	const lines: string[] = [];
+	const prIdentifier = data.number ?? input.pr ?? "current";
+	lines.push(`# Pull Request #${prIdentifier}: ${data.title ?? "Untitled"}`);
+	lines.push("");
+	pushLine(lines, "State", data.state);
+	pushLine(lines, "Draft", data.isDraft);
+	pushLine(lines, "Author", formatAuthor(data.author));
+	pushLine(lines, "Base", data.baseRefName);
+	pushLine(lines, "Head", data.headRefName);
+	pushLine(lines, "Review decision", data.reviewDecision ?? undefined);
+	pushLine(lines, "Merge state", data.mergeStateStatus);
+	pushLine(lines, "Created", data.createdAt);
+	pushLine(lines, "Updated", data.updatedAt);
+	pushLine(lines, "Labels", formatLabels(data.labels));
+	pushLine(lines, "URL", data.url);
+	lines.push("");
+	lines.push("## Body");
+	lines.push("");
+	lines.push(normalizeText(data.body) || "No description provided.");
+
+	const fileSection = formatPrFiles(data.files);
+	if (fileSection.length > 0) {
+		lines.push("");
+		lines.push(...fileSection);
+	}
+
+	if ((input.comments ?? true) && data.reviews) {
+		const reviewSection = formatReviewsSection(data.reviews);
+		if (reviewSection.length > 0) {
+			lines.push("");
+			lines.push(...reviewSection);
+		}
+	}
+
+	if ((input.comments ?? true) && data.reviewComments) {
+		const reviewCommentsSection = formatReviewCommentsSection(data.reviewComments);
+		if (reviewCommentsSection.length > 0) {
+			lines.push("");
+			lines.push(...reviewCommentsSection);
+		}
+	}
+
+	if ((input.comments ?? true) && data.comments) {
+		const commentSection = formatCommentsSection(data.comments);
+		if (commentSection.length > 0) {
+			lines.push("");
+			lines.push(...commentSection);
+		}
+	}
+
+	return lines.join("\n").trim();
+}
+
+function formatPrCheckoutResult(options: {
+	data: GhPrViewData;
+	localBranch: string;
+	worktreePath: string;
+	remoteName: string;
+	remoteUrl: string;
+	reused: boolean;
+}): string {
+	const { data, localBranch, worktreePath, remoteName, remoteUrl, reused } = options;
+	const lines: string[] = [
+		reused ? `# Pull Request #${data.number ?? "?"} Worktree` : `# Checked Out Pull Request #${data.number ?? "?"}`,
+		"",
+	];
+	pushLine(lines, "Title", data.title ?? undefined);
+	pushLine(lines, "URL", data.url);
+	pushLine(lines, "Base", data.baseRefName);
+	pushLine(lines, "Head", data.headRefName);
+	pushLine(lines, "Local branch", localBranch);
+	pushLine(lines, "Worktree", worktreePath);
+	pushLine(lines, "Remote", remoteName);
+	pushLine(lines, "Remote URL", remoteUrl);
+	pushLine(lines, "Cross repository", data.isCrossRepository);
+	pushLine(lines, "Maintainer can modify", data.maintainerCanModify);
+	lines.push("");
+	lines.push(
+		reused
+			? "Reused the existing PR worktree."
+			: "Created a dedicated worktree for this PR and configured the local branch to push back to the PR head branch.",
+	);
+	return lines.join("\n").trim();
+}
+
+function formatPrPushResult(options: {
+	localBranch: string;
+	remoteName: string;
+	remoteBranch: string;
+	remoteUrl?: string;
+	prUrl?: string;
+	forceWithLease: boolean;
+}): string {
+	const lines: string[] = ["# Pushed Pull Request Branch", ""];
+	pushLine(lines, "Local branch", options.localBranch);
+	pushLine(lines, "Remote", options.remoteName);
+	pushLine(lines, "Remote branch", options.remoteBranch);
+	pushLine(lines, "Remote URL", options.remoteUrl);
+	pushLine(lines, "PR", options.prUrl);
+	pushLine(lines, "Force with lease", options.forceWithLease);
+	lines.push("");
+	lines.push(`Pushed ${options.localBranch} to ${options.remoteName}:${options.remoteBranch}.`);
+	return lines.join("\n").trim();
+}
+
+function formatSearchResults(
+	kind: "issues" | "pull requests",
+	query: string,
+	repo: string | undefined,
+	items: GhSearchResult[],
+): string {
+	const lines: string[] = [`# GitHub ${kind} search`, "", `Query: ${query}`];
+	pushLine(lines, "Repository", repo);
+	pushLine(lines, "Results", items.length);
+
+	if (items.length === 0) {
+		lines.push("");
+		lines.push(`No ${kind} found.`);
+		return lines.join("\n").trim();
+	}
+
+	for (const item of items) {
+		lines.push("");
+		lines.push(`- #${item.number ?? "?"} ${item.title ?? "Untitled"}`);
+		pushLine(lines, "  Repo", item.repository?.nameWithOwner);
+		pushLine(lines, "  State", item.state);
+		pushLine(lines, "  Author", formatAuthor(item.author));
+		pushLine(lines, "  Labels", formatLabels(item.labels));
+		pushLine(lines, "  Created", item.createdAt);
+		pushLine(lines, "  Updated", item.updatedAt);
+		pushLine(lines, "  URL", item.url);
+	}
+
+	return lines.join("\n").trim();
+}
+
+async function saveArtifactText(session: ToolSession, toolType: string, text: string): Promise<string | undefined> {
+	const { path: artifactPath, id: artifactId } = (await session.allocateOutputArtifact?.(toolType)) ?? {};
+	if (!artifactPath || !artifactId) {
+		return undefined;
+	}
+
+	await Bun.write(artifactPath, text);
+	return artifactId;
+}
+
+function appendArtifactReference(text: string, artifactId: string | undefined, label: string): string {
+	if (!artifactId) {
+		return text;
+	}
+
+	return `${text}\n\n${label}: artifact://${artifactId}`;
+}
+
+function buildTextResult(
+	text: string,
+	sourceUrl?: string,
+	details?: GhToolDetails,
+	options?: { artifactId?: string; artifactLabel?: string },
+): AgentToolResult<GhToolDetails> {
+	const builder = toolResult<GhToolDetails>(details).text(
+		appendArtifactReference(text, options?.artifactId, options?.artifactLabel ?? "Saved artifact"),
+	);
+	if (sourceUrl) {
+		builder.sourceUrl(sourceUrl);
+	}
+	return builder.done();
+}
+
+export class GhRepoViewTool implements AgentTool<typeof ghRepoViewSchema, GhToolDetails> {
+	readonly name = "gh_repo_view";
+	readonly label = "GitHub Repo";
+	readonly description = prompt.render(ghRepoViewDescription);
+	readonly parameters = ghRepoViewSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): GhRepoViewTool | null {
+		if (!git.github.available()) return null;
+		return new GhRepoViewTool(session);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: GhRepoViewInput,
+		signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<GhToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<GhToolDetails>> {
+		return untilAborted(signal, async () => {
+			const repo = normalizeOptionalString(params.repo);
+			const branch = normalizeOptionalString(params.branch);
+			const args = ["repo", "view"];
+			if (repo) {
+				args.push(repo);
+			}
+			if (branch) {
+				args.push("--branch", branch);
+			}
+			args.push("--json", GH_REPO_FIELDS.join(","));
+
+			const data = await git.github.json<GhRepoViewData>(this.session.cwd, args, signal, {
+				repoProvided: Boolean(repo),
+			});
+			return buildTextResult(formatRepoView(data, { repo, branch }), data.url);
+		});
+	}
+}
+
+export class GhIssueViewTool implements AgentTool<typeof ghIssueViewSchema, GhToolDetails> {
+	readonly name = "gh_issue_view";
+	readonly label = "GitHub Issue";
+	readonly description = prompt.render(ghIssueViewDescription);
+	readonly parameters = ghIssueViewSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): GhIssueViewTool | null {
+		if (!git.github.available()) return null;
+		return new GhIssueViewTool(session);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: GhIssueViewInput,
+		signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<GhToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<GhToolDetails>> {
+		return untilAborted(signal, async () => {
+			const issue = requireNonEmpty(params.issue, "issue");
+			const repo = normalizeOptionalString(params.repo);
+			const includeComments = params.comments ?? true;
+			const args = ["issue", "view", issue];
+			appendRepoFlag(args, repo, issue);
+			args.push("--json", (includeComments ? GH_ISSUE_FIELDS : GH_ISSUE_FIELDS_NO_COMMENTS).join(","));
+
+			const data = await git.github.json<GhIssueViewData>(this.session.cwd, args, signal, {
+				repoProvided: Boolean(repo),
+			});
+			return buildTextResult(formatIssueView(data, { issue, repo, comments: includeComments }), data.url);
+		});
+	}
+}
+
+export class GhPrViewTool implements AgentTool<typeof ghPrViewSchema, GhToolDetails> {
+	readonly name = "gh_pr_view";
+	readonly label = "GitHub PR";
+	readonly description = prompt.render(ghPrViewDescription);
+	readonly parameters = ghPrViewSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): GhPrViewTool | null {
+		if (!git.github.available()) return null;
+		return new GhPrViewTool(session);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: GhPrViewInput,
+		signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<GhToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<GhToolDetails>> {
+		return untilAborted(signal, async () => {
+			const pr = normalizeOptionalString(params.pr);
+			const repo = normalizeOptionalString(params.repo);
+			const includeComments = params.comments ?? true;
+			const args = ["pr", "view"];
+			if (pr) {
+				args.push(pr);
+			}
+			appendRepoFlag(args, repo, pr);
+			args.push("--json", (includeComments ? GH_PR_FIELDS : GH_PR_FIELDS_NO_COMMENTS).join(","));
+
+			const data = await git.github.json<GhPrViewData>(this.session.cwd, args, signal, {
+				repoProvided: Boolean(repo),
+			});
+			const resolvedRepo = repo ?? parsePullRequestUrl(data.url).repo;
+			if (includeComments && resolvedRepo && typeof data.number === "number") {
+				data.reviewComments = await fetchPrReviewComments(this.session.cwd, resolvedRepo, data.number, signal);
+			}
+			return buildTextResult(formatPrView(data, { pr, repo, comments: includeComments }), data.url);
+		});
+	}
+}
+
+export class GhPrDiffTool implements AgentTool<typeof ghPrDiffSchema, GhToolDetails> {
+	readonly name = "gh_pr_diff";
+	readonly label = "GitHub PR Diff";
+	readonly description = prompt.render(ghPrDiffDescription);
+	readonly parameters = ghPrDiffSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): GhPrDiffTool | null {
+		if (!git.github.available()) return null;
+		return new GhPrDiffTool(session);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: GhPrDiffInput,
+		signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<GhToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<GhToolDetails>> {
+		return untilAborted(signal, async () => {
+			const pr = normalizeOptionalString(params.pr);
+			const repo = normalizeOptionalString(params.repo);
+			const args = ["pr", "diff"];
+			if (pr) {
+				args.push(pr);
+			}
+			appendRepoFlag(args, repo, pr);
+			args.push("--color", "never");
+			if (params.nameOnly) {
+				args.push("--name-only");
+			}
+			for (const pattern of params.exclude ?? []) {
+				const normalizedPattern = requireNonEmpty(pattern, "exclude pattern");
+				args.push("--exclude", normalizedPattern);
+			}
+
+			const output = await git.github.text(this.session.cwd, args, signal, {
+				repoProvided: Boolean(repo),
+				trimOutput: false,
+			});
+			const title = params.nameOnly ? "# Pull Request Files" : "# Pull Request Diff";
+			const body = output.length > 0 ? output : params.nameOnly ? "No changed files." : "No diff output.";
+			return buildTextResult(`${title}\n\n${body}`);
+		});
+	}
+}
+
+export class GhPrCheckoutTool implements AgentTool<typeof ghPrCheckoutSchema, GhToolDetails> {
+	readonly name = "gh_pr_checkout";
+	readonly label = "GitHub PR Checkout";
+	readonly description = prompt.render(ghPrCheckoutDescription);
+	readonly parameters = ghPrCheckoutSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): GhPrCheckoutTool | null {
+		if (!git.github.available()) return null;
+		return new GhPrCheckoutTool(session);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: GhPrCheckoutInput,
+		signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<GhToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<GhToolDetails>> {
+		return untilAborted(signal, async () => {
+			const pr = normalizeOptionalString(params.pr);
+			const repo = normalizeOptionalString(params.repo);
+			const requestedBranch = normalizeOptionalString(params.branch);
+			const requestedWorktree = normalizeOptionalString(params.worktree);
+			const force = params.force ?? false;
+			const args = ["pr", "view"];
+			if (pr) {
+				args.push(pr);
+			}
+			appendRepoFlag(args, repo, pr);
+			args.push("--json", GH_PR_CHECKOUT_FIELDS.join(","));
+
+			const data = await git.github.json<GhPrViewData>(this.session.cwd, args, signal, {
+				repoProvided: Boolean(repo),
+			});
+			const prNumber = data.number;
+			if (typeof prNumber !== "number") {
+				throw new ToolError("GitHub CLI did not return a pull request number.");
+			}
+
+			const headRefName = requireNonEmpty(data.headRefName, "head branch");
+			const headRefOid = requireNonEmpty(data.headRefOid, "head commit");
+			const repoRoot = await requireGitRepoRoot(this.session.cwd, signal);
+			const primaryRepoRoot = await requirePrimaryGitRepoRoot(repoRoot, signal);
+			const localBranch = requestedBranch ?? `pr-${prNumber}`;
+			const worktreePath = requestedWorktree
+				? path.resolve(this.session.cwd, requestedWorktree)
+				: path.join(primaryRepoRoot, ".worktrees", localBranch);
+			const existingWorktrees = await git.worktree.list(repoRoot, signal);
+			const existingWorktree = existingWorktrees.find(entry => entry.branch === toLocalBranchRef(localBranch));
+
+			const remote = await ensurePrRemote(repoRoot, data, signal);
+			await git.fetch(
+				repoRoot,
+				remote.name,
+				`refs/heads/${headRefName}`,
+				`refs/remotes/${remote.name}/${headRefName}`,
+				signal,
+			);
+
+			if (!existingWorktree) {
+				const localBranchRef = toLocalBranchRef(localBranch);
+				const localBranchExists = await git.ref.exists(repoRoot, localBranchRef, signal);
+				if (localBranchExists) {
+					const existingOid = await git.ref.resolve(repoRoot, localBranchRef, signal);
+					if (existingOid !== headRefOid) {
+						if (!force) {
+							throw new ToolError(
+								`local branch ${localBranch} already exists at ${formatShortSha(existingOid ?? undefined) ?? existingOid ?? "unknown commit"}; pass force=true to reset it`,
+							);
+						}
+
+						await git.branch.force(repoRoot, localBranch, `refs/remotes/${remote.name}/${headRefName}`, signal);
+					}
+				} else {
+					await git.branch.create(repoRoot, localBranch, `refs/remotes/${remote.name}/${headRefName}`, signal);
+				}
+			}
+
+			await git.config.setBranch(repoRoot, localBranch, "remote", remote.name, signal);
+			await git.config.setBranch(repoRoot, localBranch, "merge", `refs/heads/${headRefName}`, signal);
+			await git.config.setBranch(repoRoot, localBranch, "pushRemote", remote.name, signal);
+			await git.config.setBranch(repoRoot, localBranch, "ompPrHeadRef", headRefName, signal);
+			await git.config.setBranch(repoRoot, localBranch, "ompPrUrl", data.url ?? "", signal);
+			await git.config.setBranch(
+				repoRoot,
+				localBranch,
+				"ompPrIsCrossRepository",
+				String(Boolean(data.isCrossRepository)),
+				signal,
+			);
+			await git.config.setBranch(
+				repoRoot,
+				localBranch,
+				"ompPrMaintainerCanModify",
+				String(Boolean(data.maintainerCanModify)),
+				signal,
+			);
+
+			const finalWorktreePath = existingWorktree?.path ?? worktreePath;
+			if (!existingWorktree) {
+				await ensureGitWorktreePathAvailable(finalWorktreePath, existingWorktrees);
+				await fs.mkdir(path.dirname(finalWorktreePath), { recursive: true });
+				await git.worktree.add(repoRoot, finalWorktreePath, localBranch, { signal });
+			}
+			const resolvedWorktreePath = await fs.realpath(finalWorktreePath);
+
+			return buildTextResult(
+				formatPrCheckoutResult({
+					data,
+					localBranch,
+					worktreePath: resolvedWorktreePath,
+					remoteName: remote.name,
+					remoteUrl: remote.url,
+					reused: Boolean(existingWorktree),
+				}),
+				data.url,
+				{
+					repo: repo ?? data.headRepository?.nameWithOwner,
+					branch: localBranch,
+					worktreePath: resolvedWorktreePath,
+					remote: remote.name,
+					remoteBranch: headRefName,
+				},
+			);
+		});
+	}
+}
+
+export class GhPrPushTool implements AgentTool<typeof ghPrPushSchema, GhToolDetails> {
+	readonly name = "gh_pr_push";
+	readonly label = "GitHub PR Push";
+	readonly description = prompt.render(ghPrPushDescription);
+	readonly parameters = ghPrPushSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): GhPrPushTool | null {
+		if (!git.github.available()) return null;
+		return new GhPrPushTool(session);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: GhPrPushInput,
+		signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<GhToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<GhToolDetails>> {
+		return untilAborted(signal, async () => {
+			const repoRoot = await requireGitRepoRoot(this.session.cwd, signal);
+			const localBranch =
+				normalizeOptionalString(params.branch) ?? (await requireCurrentGitBranch(repoRoot, signal));
+			const refExists = await git.ref.exists(repoRoot, toLocalBranchRef(localBranch), signal);
+			if (!refExists) {
+				throw new ToolError(`local branch ${localBranch} does not exist`);
+			}
+
+			const target = await resolvePrBranchPushTarget(repoRoot, localBranch, signal);
+			const currentBranch = await git.branch.current(repoRoot, signal);
+			const sourceRef = currentBranch === localBranch ? "HEAD" : toLocalBranchRef(localBranch);
+			const refspec = `${sourceRef}:refs/heads/${target.remoteBranch}`;
+			await git.push(repoRoot, {
+				forceWithLease: params.forceWithLease,
+				refspec,
+				remote: target.remoteName,
+				signal,
+			});
+
+			return buildTextResult(
+				formatPrPushResult({
+					localBranch,
+					remoteName: target.remoteName,
+					remoteBranch: target.remoteBranch,
+					remoteUrl: target.remoteUrl,
+					prUrl: target.prUrl,
+					forceWithLease: params.forceWithLease ?? false,
+				}),
+				target.prUrl,
+				{
+					branch: localBranch,
+					remote: target.remoteName,
+					remoteBranch: target.remoteBranch,
+				},
+			);
+		});
+	}
+}
+
+export class GhSearchIssuesTool implements AgentTool<typeof ghSearchIssuesSchema, GhToolDetails> {
+	readonly name = "gh_search_issues";
+	readonly label = "GitHub Issue Search";
+	readonly description = prompt.render(ghSearchIssuesDescription);
+	readonly parameters = ghSearchIssuesSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): GhSearchIssuesTool | null {
+		if (!git.github.available()) return null;
+		return new GhSearchIssuesTool(session);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: GhSearchIssuesInput,
+		signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<GhToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<GhToolDetails>> {
+		return untilAborted(signal, async () => {
+			const query = requireNonEmpty(params.query, "query");
+			const repo = normalizeOptionalString(params.repo);
+			const limit = resolveSearchLimit(params.limit);
+			const args = buildGhSearchArgs("issues", query, limit, repo);
+
+			const items = await git.github.json<GhSearchResult[]>(this.session.cwd, args, signal, {
+				repoProvided: Boolean(repo),
+			});
+			return buildTextResult(formatSearchResults("issues", query, repo, items));
+		});
+	}
+}
+
+export class GhSearchPrsTool implements AgentTool<typeof ghSearchPrsSchema, GhToolDetails> {
+	readonly name = "gh_search_prs";
+	readonly label = "GitHub PR Search";
+	readonly description = prompt.render(ghSearchPrsDescription);
+	readonly parameters = ghSearchPrsSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): GhSearchPrsTool | null {
+		if (!git.github.available()) return null;
+		return new GhSearchPrsTool(session);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: GhSearchPrsInput,
+		signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<GhToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<GhToolDetails>> {
+		return untilAborted(signal, async () => {
+			const query = requireNonEmpty(params.query, "query");
+			const repo = normalizeOptionalString(params.repo);
+			const limit = resolveSearchLimit(params.limit);
+			const args = buildGhSearchArgs("prs", query, limit, repo);
+
+			const items = await git.github.json<GhSearchResult[]>(this.session.cwd, args, signal, {
+				repoProvided: Boolean(repo),
+			});
+			return buildTextResult(formatSearchResults("pull requests", query, repo, items));
+		});
+	}
+}
+
+export class GhRunWatchTool implements AgentTool<typeof ghRunWatchSchema, GhToolDetails> {
+	readonly name = "gh_run_watch";
+	readonly label = "GitHub Run Watch";
+	readonly description = prompt.render(ghRunWatchDescription);
+	readonly parameters = ghRunWatchSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): GhRunWatchTool | null {
+		if (!git.github.available()) return null;
+		return new GhRunWatchTool(session);
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: GhRunWatchInput,
+		signal?: AbortSignal,
+		onUpdate?: AgentToolUpdateCallback<GhToolDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<GhToolDetails>> {
+		return untilAborted(signal, async () => {
+			const branchInput = normalizeOptionalString(params.branch);
+			const runReference = parseRunReference(params.run);
+			const repo = await resolveGitHubRepo(this.session.cwd, undefined, runReference.repo, signal);
+			const intervalSeconds = RUN_WATCH_INTERVAL_DEFAULT;
+			const graceSeconds = RUN_WATCH_GRACE_DEFAULT;
+			const tail = resolveTailLimit(params.tail);
+			if (runReference.runId !== undefined) {
+				const runId = runReference.runId;
+				let pollCount = 0;
+
+				while (true) {
+					throwIfAborted(signal);
+					pollCount += 1;
+
+					let run = await fetchRunSnapshot(this.session.cwd, repo, runId, signal);
+					const details = buildRunWatchDetails(repo, run, {
+						state: "watching",
+						pollCount,
+					});
+					onUpdate?.({
+						content: [{ type: "text", text: formatRunWatchSnapshot(repo, run, pollCount) }],
+						details,
+					});
+
+					const failedJobs = run.jobs.filter(isFailedJob);
+					const runCompleted = run.status === "completed";
+
+					if (failedJobs.length > 0) {
+						if (!runCompleted && graceSeconds > 0) {
+							const note = `Failure detected. Waiting ${graceSeconds}s to capture concurrent failures before fetching logs.`;
+							onUpdate?.({
+								content: [
+									{
+										type: "text",
+										text: formatRunWatchSnapshot(repo, run, pollCount, note),
+									},
+								],
+								details: buildRunWatchDetails(repo, run, {
+									state: "watching",
+									pollCount,
+									note,
+								}),
+							});
+							await abortableSleep(graceSeconds * 1000, signal);
+							run = await fetchRunSnapshot(this.session.cwd, repo, runId, signal);
+						}
+
+						const failedJobLogs = await fetchFailedJobLogs(
+							this.session.cwd,
+							repo,
+							run.jobs.filter(isFailedJob).map(job => ({ run, job })),
+							tail,
+							signal,
+						);
+						const finalDetails = buildRunWatchDetails(repo, run, {
+							state: "completed",
+							failedJobLogs,
+						});
+						const artifactId = await saveArtifactText(
+							this.session,
+							this.name,
+							formatRunWatchResult(repo, run, failedJobLogs, tail, { mode: "full" }),
+						);
+						return buildTextResult(
+							formatRunWatchResult(repo, run, failedJobLogs, tail),
+							run.url,
+							{ ...finalDetails, artifactId },
+							{ artifactId, artifactLabel: "Full failed-job logs" },
+						);
+					}
+
+					if (runCompleted) {
+						const finalDetails = buildRunWatchDetails(repo, run, {
+							state: "completed",
+						});
+						return buildTextResult(formatRunWatchResult(repo, run, [], tail), run.url, finalDetails);
+					}
+
+					await abortableSleep(intervalSeconds * 1000, signal);
+				}
+			}
+
+			const branch = branchInput ?? (await requireCurrentGitBranch(this.session.cwd, signal));
+			const headSha = branchInput
+				? await resolveGitHubBranchHead(this.session.cwd, repo, branch, signal)
+				: await requireCurrentGitHead(this.session.cwd, signal);
+			let pollCount = 0;
+			let settledSuccessSignature: string | undefined;
+
+			while (true) {
+				throwIfAborted(signal);
+				pollCount += 1;
+
+				let runs = await fetchRunsForCommit(this.session.cwd, repo, headSha, branch, signal);
+				const details = buildCommitRunWatchDetails(repo, headSha, branch, runs, {
+					state: "watching",
+					pollCount,
+				});
+				onUpdate?.({
+					content: [{ type: "text", text: formatCommitRunWatchSnapshot(repo, headSha, branch, runs, pollCount) }],
+					details,
+				});
+
+				const outcome = getRunCollectionOutcome(runs);
+				if (outcome === "failure") {
+					if (graceSeconds > 0) {
+						const note = `Failure detected. Waiting ${graceSeconds}s to capture concurrent failures before fetching logs.`;
+						onUpdate?.({
+							content: [
+								{
+									type: "text",
+									text: formatCommitRunWatchSnapshot(repo, headSha, branch, runs, pollCount, note),
+								},
+							],
+							details: buildCommitRunWatchDetails(repo, headSha, branch, runs, {
+								state: "watching",
+								pollCount,
+								note,
+							}),
+						});
+						await abortableSleep(graceSeconds * 1000, signal);
+						runs = await fetchRunsForCommit(this.session.cwd, repo, headSha, branch, signal);
+					}
+
+					const failedJobLogs = await fetchFailedJobLogs(
+						this.session.cwd,
+						repo,
+						runs.flatMap(run => run.jobs.filter(isFailedJob).map(job => ({ run, job }))),
+						tail,
+						signal,
+					);
+					const finalDetails = buildCommitRunWatchDetails(repo, headSha, branch, runs, {
+						state: "completed",
+						failedJobLogs,
+					});
+					const artifactId = await saveArtifactText(
+						this.session,
+						this.name,
+						formatCommitRunWatchResult(repo, headSha, branch, runs, failedJobLogs, tail, { mode: "full" }),
+					);
+					return buildTextResult(
+						formatCommitRunWatchResult(repo, headSha, branch, runs, failedJobLogs, tail),
+						undefined,
+						{ ...finalDetails, artifactId },
+						{ artifactId, artifactLabel: "Full failed-job logs" },
+					);
+				}
+
+				if (outcome === "success") {
+					const signature = getRunCollectionSignature(runs);
+					if (signature === settledSuccessSignature) {
+						const finalDetails = buildCommitRunWatchDetails(repo, headSha, branch, runs, {
+							state: "completed",
+						});
+						return buildTextResult(
+							formatCommitRunWatchResult(repo, headSha, branch, runs, [], tail),
+							undefined,
+							finalDetails,
+						);
+					}
+
+					settledSuccessSignature = signature;
+					const note = `All known workflow runs completed successfully. Waiting ${intervalSeconds}s to ensure no additional runs appear for this commit.`;
+					onUpdate?.({
+						content: [
+							{
+								type: "text",
+								text: formatCommitRunWatchSnapshot(repo, headSha, branch, runs, pollCount, note),
+							},
+						],
+						details: buildCommitRunWatchDetails(repo, headSha, branch, runs, {
+							state: "watching",
+							pollCount,
+							note,
+						}),
+					});
+					await abortableSleep(intervalSeconds * 1000, signal);
+					continue;
+				}
+
+				settledSuccessSignature = undefined;
+				await abortableSleep(intervalSeconds * 1000, signal);
+			}
+		});
+	}
+}