@senad-d/branchme 0.3.0 → 0.3.2

package/src/git.ts

@@ -1,7 +1,9 @@
 import { lstat, realpath, stat } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, normalize, relative, sep } from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { withFileMutationQueue, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
+  GIT_BRANCH_ENTRY_LIMIT,
+  GIT_BRANCH_RAW_OUTPUT_LIMIT_BYTES,
   GIT_CONTEXT_CHANGE_LIMIT,
   GIT_CONTEXT_RECENT_COMMIT_LIMIT,
   GIT_CONTEXT_VALUE_LIMIT_CHARS,
@@ -24,6 +26,7 @@ import {
 import { redactSecrets } from "./redaction.ts";
 import type {
   AheadBehindCount,
+  BranchEntry,
   BranchAncestryDetails,
   BranchStatusAncestryQuery,
   BranchStatusDetails,
@@ -37,6 +40,8 @@ import type {
   GitExecResult,
   GitFileChange,
   GitFileChangeSummary,
+  InitRepositoryDetails,
+  ListBranchesDetails,
   ListWorktreesDetails,
   PullBranchDetails,
   PushBranchDetails,
@@ -144,6 +149,196 @@ export async function runGit(
   return result;
 }
 
+function requireSafeInitializationEnvironment(): void {
+  for (const key of [
+    "GIT_DIR", "GIT_COMMON_DIR", "GIT_WORK_TREE", "GIT_OBJECT_DIRECTORY",
+    "GIT_INDEX_FILE", "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_IMPLICIT_WORK_TREE",
+    "GIT_CEILING_DIRECTORIES", "GIT_DISCOVERY_ACROSS_FILESYSTEM",
+  ]) {
+    if (process.env[key] !== undefined) {
+      throw new Error(`Git environment override ${key} must be unset before repository initialization.`);
+    }
+  }
+}
+
+function requireLosslessRepositoryPath(value: string, label: string): string {
+  if (isLosslessGitMetadata(value, GIT_WORKTREE_PATH_LIMIT_CHARS)) return value;
+  throw new Error(
+    `The canonical ${label} cannot be returned safely and losslessly. ` +
+    `Use a path of at most ${GIT_WORKTREE_PATH_LIMIT_CHARS} characters without credential-like token text or control/format characters.`,
+  );
+}
+
+async function resolveRepositoryInitializationDirectory(ctx: GitCommandContext): Promise<string> {
+  let canonicalPath: string;
+  try {
+    canonicalPath = await realpath(ctx.cwd);
+  } catch {
+    throw new Error("The current working directory does not exist or cannot be resolved.");
+  }
+
+  let directoryStats;
+  try {
+    directoryStats = await stat(canonicalPath);
+  } catch {
+    throw new Error("The current working directory cannot be inspected.");
+  }
+  if (!directoryStats.isDirectory()) throw new Error("The current working directory is not a directory.");
+  if (dirname(canonicalPath) === canonicalPath) throw new Error("The filesystem root cannot be initialized as a repository.");
+  return requireLosslessRepositoryPath(canonicalPath, "repository path");
+}
+
+async function gitMetadataEntryExists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw new Error("The target directory's .git entry cannot be inspected.");
+  }
+}
+
+async function requireUninitializedRepositoryDirectory(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  canonicalPath: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  requireSafeInitializationEnvironment();
+  const currentPath = await resolveRepositoryInitializationDirectory(ctx);
+  if (currentPath !== canonicalPath) throw new Error("The current working directory changed while preparing git init.");
+  if (await gitMetadataEntryExists(join(canonicalPath, ".git"))) {
+    throw new Error("The current working directory already contains a .git entry; reinitialization is not allowed.");
+  }
+
+  // Do not let failed discovery (including invalid metadata or filesystem
+  // boundaries) hide an enclosing checkout.
+  for (let parent = dirname(canonicalPath); ; parent = dirname(parent)) {
+    if (await gitMetadataEntryExists(join(parent, ".git"))) {
+      throw new Error("The current working directory is already inside a Git repository; nested initialization is not allowed.");
+    }
+    if (dirname(parent) === parent) break;
+  }
+
+  const probe = await runGit(pi, { cwd: canonicalPath }, ["rev-parse", "--git-dir"], {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+    allowFailure: true,
+  });
+  if (probe.code === 0) {
+    throw new Error("The current working directory is already inside a Git repository; nested initialization is not allowed.");
+  }
+  // Only Git's explicit absence diagnostic permits initialization. Ownership,
+  // permission, configuration and unrecognized/localized failures stay closed.
+  if (probe.code !== 128 || probe.stdout ||
+      !/^fatal: not a git repository \(or any (?:of the parent directories\): \.git|parent up to mount point [^\r\n]+\))/u.test(probe.stderr)) {
+    throw new Error("Git repository discovery failed; inspect the current directory and Git configuration before initialization.");
+  }
+}
+
+async function verifyInitializedRepository(
+  pi: Pick<ExtensionAPI, "exec">,
+  canonicalPath: string,
+  initialBranch: string,
+): Promise<InitRepositoryDetails> {
+  const verificationCtx = { cwd: canonicalPath };
+  const repoRoot = await getCanonicalGitWorktreeRoot(pi, verificationCtx);
+  if (repoRoot !== canonicalPath) throw new Error("git init produced an unexpected repository root.");
+
+  const current = await getCurrentBranch(pi, verificationCtx);
+  if (current.detached || current.currentBranch !== initialBranch) {
+    throw new Error("git init did not create the requested unborn initial branch.");
+  }
+
+  const gitDirectoryResult = await runGit(
+    pi,
+    verificationCtx,
+    ["rev-parse", "--path-format=absolute", "--git-dir"],
+  );
+  const gitDirectoryOutput = trimOutput(gitDirectoryResult.stdout);
+  let gitDirectory: string;
+  try {
+    gitDirectory = await realpath(gitDirectoryOutput);
+  } catch {
+    throw new Error("The initialized Git directory could not be resolved.");
+  }
+  if (gitDirectory !== join(canonicalPath, ".git")) {
+    throw new Error("git init produced an unexpected or separate Git directory.");
+  }
+
+  const bareResult = await runGit(pi, verificationCtx, ["rev-parse", "--is-bare-repository"]);
+  if (trimOutput(bareResult.stdout) !== "false") throw new Error("git init produced an unexpected bare repository.");
+
+  const headResult = await runGit(pi, verificationCtx, ["rev-parse", "--verify", "HEAD"], {
+    allowFailure: true,
+  });
+  if (headResult.code === 0) throw new Error("The initialized repository unexpectedly contains a commit.");
+
+  return {
+    action: "init_repository",
+    request: { initialBranch },
+    repoRoot,
+    gitDirectory: requireLosslessRepositoryPath(gitDirectory, "Git directory path"),
+    initialBranch,
+    bare: false,
+    unborn: true,
+  };
+}
+
+async function initializeRepositoryWithinQueue(
+  pi: Pick<ExtensionAPI, "exec">,
+  targetCtx: GitCommandContext,
+  canonicalPath: string,
+  initialBranch: string,
+  signal?: AbortSignal,
+): Promise<InitRepositoryDetails> {
+  await requireUninitializedRepositoryDirectory(pi, targetCtx, canonicalPath, signal);
+  await validateBranchName(pi, targetCtx, initialBranch, signal);
+  try {
+    await runGit(pi, targetCtx, ["init", "--no-template", "--initial-branch", initialBranch], {
+      signal,
+      timeout: GIT_MUTATION_TIMEOUT_MS,
+    });
+    return await verifyInitializedRepository(pi, canonicalPath, initialBranch);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Repository initialization did not complete with verified postconditions. ${safeOutput(reason)} ` +
+      "Inspect the current directory before retrying; no automatic cleanup was attempted.",
+    );
+  }
+}
+
+async function queueRepositoryInitialization(
+  canonicalPath: string,
+  initialize: () => Promise<InitRepositoryDetails>,
+): Promise<InitRepositoryDetails> {
+  return withRepositoryMutationQueue(canonicalPath, initialize);
+}
+
+export async function initializeRepository(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  initialBranch: unknown = "main",
+  signal?: AbortSignal,
+): Promise<InitRepositoryDetails> {
+  requireSafeInitializationEnvironment();
+  validateBranchNameInput(initialBranch, "Initial branch name");
+  requireLosslessWorktreeIdentity(initialBranch, "branch");
+  const canonicalPath = await resolveRepositoryInitializationDirectory(ctx);
+  const targetCtx = { cwd: canonicalPath };
+  const initialize: () => Promise<InitRepositoryDetails> = initializeRepositoryWithinQueue.bind(
+    undefined,
+    pi,
+    targetCtx,
+    canonicalPath,
+    initialBranch,
+    signal,
+  );
+  const queueRepositoryMutation = queueRepositoryInitialization.bind(undefined, canonicalPath, initialize);
+  return withFileMutationQueue<InitRepositoryDetails>(join(canonicalPath, ".git"), queueRepositoryMutation);
+}
+
 export async function getGitRoot(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -759,6 +954,14 @@ export async function canonicalizePathAllowMissing(path: string): Promise<string
   }
 }
 
+async function resolveWorktreeInventoryEntry(
+  record: ParsedWorktreeRecord,
+  index: number,
+): Promise<WorktreeInventoryEntry> {
+  const canonicalPath = await canonicalizePathAllowMissing(record.rawPath);
+  return { record, index, canonicalPath };
+}
+
 export async function collectWorktreeInventory(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -776,10 +979,11 @@ export async function collectWorktreeInventory(
     throw new Error("Unable to inspect worktrees: current repository path could not be resolved.");
   }
 
-  const entries: WorktreeInventoryEntry[] = [];
+  const entryPromises: Promise<WorktreeInventoryEntry>[] = [];
   for (const [index, record] of records.entries()) {
-    entries.push({ record, index, canonicalPath: await canonicalizePathAllowMissing(record.rawPath) });
+    entryPromises.push(resolveWorktreeInventoryEntry(record, index));
   }
+  const entries = await Promise.all(entryPromises);
   return { repoRoot, canonicalCurrentPath, entries };
 }
 
@@ -788,16 +992,20 @@ export function pathIsInsideOrEqual(candidatePath: string, boundaryPath: string)
   return relation === "" || (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation));
 }
 
-async function requireCanonicalCreationPath(worktreePath: string): Promise<string> {
-  const parentPath = dirname(worktreePath);
-  let parentStats;
+async function requireCanonicalCreationParent(parentPath: string): Promise<string> {
   try {
-    parentStats = await stat(parentPath);
-  } catch {
-    throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} must exist as a directory.`);
-  }
-  if (!parentStats.isDirectory()) {
-    throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} must be a directory.`);
+    // lstat distinguishes a missing directory from a dangling symlink.
+    await lstat(parentPath);
+  } catch (error) {
+    if (filesystemErrorCode(error) === "ENOTDIR") {
+      throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} must be a directory.`);
+    }
+    const ancestorPath = dirname(parentPath);
+    if (filesystemErrorCode(error) !== "ENOENT" || ancestorPath === parentPath) {
+      throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} could not be inspected.`);
+    }
+    // Resolve missing ancestors without writing; Git creates them after preflight.
+    return join(await requireCanonicalCreationParent(ancestorPath), basename(parentPath));
   }
 
   let canonicalParent: string;
@@ -806,12 +1014,25 @@ async function requireCanonicalCreationPath(worktreePath: string): Promise<strin
   } catch {
     throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} could not be resolved.`);
   }
+  let parentStats;
+  try {
+    parentStats = await stat(canonicalParent);
+  } catch {
+    throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} could not be inspected.`);
+  }
+  if (!parentStats.isDirectory()) {
+    throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} must be a directory.`);
+  }
+  return canonicalParent;
+}
 
+async function requireCanonicalCreationPath(worktreePath: string): Promise<string> {
+  const canonicalParent = await requireCanonicalCreationParent(dirname(worktreePath));
   const canonicalPath = join(canonicalParent, basename(worktreePath));
   try {
     await lstat(canonicalPath);
   } catch (error) {
-    if (isMissingFilesystemPath(error)) return canonicalPath;
+    if (filesystemErrorCode(error) === "ENOENT") return canonicalPath;
     throw new Error(`worktreePath destination ${safeWorktreePathLabel(canonicalPath)} could not be inspected.`);
   }
   throw new Error(`worktreePath destination ${safeWorktreePathLabel(canonicalPath)} already exists.`);
@@ -897,10 +1118,8 @@ export async function getGitOperationState(
   }
 
   const active: GitOperationKind[] = [];
-  const presentMarkers: boolean[] = [];
-  for (const [index, path] of paths.entries()) {
-    const present = await gitOperationMarkerExists(path);
-    presentMarkers.push(present);
+  const presentMarkers = await Promise.all(paths.map(gitOperationMarkerExists));
+  for (const [index, present] of presentMarkers.entries()) {
     if (!present) continue;
     const operation = GIT_OPERATION_MARKERS[index][1];
     if (!active.includes(operation)) active.push(operation);
@@ -1000,6 +1219,85 @@ export async function validateWorktreeRemovalPath(
   };
 }
 
+const GIT_BRANCH_FORMAT = "%(refname)%00%(objectname)%00%(HEAD)%00%(upstream)%00%(symref)%00%(upstream:track)";
+
+function branchTrackingCounts(upstream: string, track: string): AheadBehindCount {
+  if (!upstream || track === "[gone]") return { ahead: null, behind: null };
+  if (track !== "" && !/^\[(?:ahead \d+(?:, behind \d+)?|behind \d+)\]$/u.test(track)) {
+    throw new TypeError("Unable to parse branches: malformed upstream counts.");
+  }
+  const ahead = Number(/ahead (\d+)/u.exec(track)?.[1] ?? 0);
+  const behind = Number(/behind (\d+)/u.exec(track)?.[1] ?? 0);
+  if (!Number.isSafeInteger(ahead) || !Number.isSafeInteger(behind)) throw new TypeError("Unable to parse branches: invalid upstream counts.");
+  return { ahead, behind };
+}
+
+function parseBranchRecord(record: string): BranchEntry {
+  const fields = record.split(NUL_SEPARATOR);
+  if (fields.length !== 6) throw new TypeError("Unable to parse branches: malformed ref output.");
+  const [fullRef, head, current, upstream, symbolicTarget, track] = fields;
+  const kind = fullRef.startsWith("refs/heads/") ? "local" : "remote-tracking";
+  const prefix = kind === "local" ? "refs/heads/" : "refs/remotes/";
+  if (!fullRef.startsWith(prefix) || fullRef.length === prefix.length ||
+      !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu.test(head) || !["*", " "].includes(current)) {
+    throw new TypeError("Unable to parse branches: malformed ref output.");
+  }
+  return {
+    name: safeGitContextValue(fullRef.slice(prefix.length)),
+    fullRef: safeGitContextValue(fullRef),
+    kind,
+    head,
+    current: current === "*",
+    upstream: upstream ? safeGitContextValue(upstream) : null,
+    ...branchTrackingCounts(upstream, track),
+    symbolicTarget: symbolicTarget ? safeGitContextValue(symbolicTarget) : null,
+    worktreePaths: [],
+  };
+}
+
+export function parseBranchRefs(output: string): Pick<ListBranchesDetails, "branches" | "omitted"> {
+  if (Buffer.byteLength(output, "utf8") > GIT_BRANCH_RAW_OUTPUT_LIMIT_BYTES) {
+    throw new TypeError("Unable to parse branches: ref output exceeded the safety limit.");
+  }
+  const records = output.endsWith("\n") ? output.slice(0, -1).split("\n") : output.split("\n");
+  if (records.length === 1 && records[0] === "") return { branches: [], omitted: 0 };
+  const branches: BranchEntry[] = [];
+  const seen = new Set<string>();
+  for (const record of records) {
+    const branch = parseBranchRecord(record);
+    const rawRef = record.split(NUL_SEPARATOR, 1)[0];
+    if (seen.has(rawRef)) throw new TypeError("Unable to parse branches: duplicate ref output.");
+    seen.add(rawRef);
+    if (branches.length < GIT_BRANCH_ENTRY_LIMIT) branches.push(branch);
+  }
+  return { branches, omitted: records.length - branches.length };
+}
+
+export async function listBranches(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  signal?: AbortSignal,
+): Promise<ListBranchesDetails> {
+  const repoRoot = await getGitRoot(pi, ctx, signal);
+  const rootCtx = { cwd: repoRoot };
+  const result = await runGit(pi, rootCtx, [
+    "for-each-ref", "--sort=refname", `--format=${GIT_BRANCH_FORMAT}`, "refs/heads/", "refs/remotes/",
+  ], { signal });
+  const parsed = parseBranchRefs(result.stdout);
+  const inventory = await collectWorktreeInventory(pi, rootCtx, signal);
+  const rawRecords = result.stdout.split("\n");
+  for (const [index, branch] of parsed.branches.entries()) {
+    if (branch.kind !== "local") continue;
+    const rawName = rawRecords[index].split(NUL_SEPARATOR, 1)[0].slice("refs/heads/".length);
+    for (const entry of inventory.entries) {
+      if (entry.record.branch === rawName) {
+        branch.worktreePaths.push(safeWorktreeValue(entry.record.rawPath, GIT_WORKTREE_PATH_LIMIT_CHARS));
+      }
+    }
+  }
+  return { action: "list_branches", repoRoot: safeGitContextValue(repoRoot), ...parsed };
+}
+
 export async function listWorktrees(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -1487,6 +1785,7 @@ export async function removeWorktree(
   ctx: GitCommandContext,
   worktreePath: unknown,
   signal?: AbortSignal,
+  deleteIgnored = false,
 ): Promise<RemoveWorktreeDetails> {
   const requestedWorktreePath = validateWorktreePathInput(worktreePath);
   const repoRoot = await getGitRoot(pi, ctx, signal);
@@ -1494,11 +1793,11 @@ export async function removeWorktree(
 
   return withRepositoryMutationQueue(
     repoRoot,
-    removeWorktreeWithinQueue.bind(undefined, pi, rootCtx, requestedWorktreePath, signal),
+    removeWorktreeWithinQueue.bind(undefined, pi, rootCtx, requestedWorktreePath, signal, deleteIgnored),
   );
 }
 
-// Caller must hold the repository mutation queue. Standalone removal still refuses ignored residue.
+// Caller must hold the repository mutation queue. Ignored residue requires explicit authorization.
 export async function removeWorktreeWithinQueue(
   pi: Pick<ExtensionAPI, "exec">,
   rootCtx: GitCommandContext,
@@ -1567,6 +1866,7 @@ export async function removeWorktreeWithinQueue(
         repoRoot: safeWorktreeValue(repoRoot, GIT_WORKTREE_PATH_LIMIT_CHARS),
         request: {
           worktreePath: safeWorktreeValue(requestedWorktreePath, GIT_WORKTREE_PATH_LIMIT_CHARS),
+          ...(allowIgnored ? { deleteIgnored: true } : {}),
         },
         verified: {
           before: {

package/src/github.ts

@@ -16,6 +16,7 @@ import {
   getCurrentBranch,
   getGitRoot,
   getOriginUrl,
+  requireLosslessWorktreeIdentity,
   validateBranchNameInput,
   type GitCommandContext,
 } from "./git.ts";
@@ -23,6 +24,8 @@ import type {
   GitHubRepository,
   PullRequestDetails,
   PullRequestInput,
+  PullRequestStatusDetails,
+  PullRequestToolDetails,
   RelatedPullRequest,
   RelatedPullRequestDetails,
 } from "./types.ts";
@@ -984,6 +987,118 @@ export async function ensureGitHubBranchExists(
   return readGitHubBranchDetails(response, options.signal, token, branchName, field, branchLabel);
 }
 
+function requirePullRequestCommit(value: unknown): string {
+  if (typeof value !== "string" || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu.test(value)) {
+    throw new Error("GitHub pull request has an invalid commit identity.");
+  }
+  return value.toLowerCase();
+}
+
+function parsePullRequestStatus(repository: GitHubRepository, number: number, payload: Record<string, unknown>, token: string): PullRequestStatusDetails {
+  if (pullRequestNumberField(payload.number) !== number) throw new Error("GitHub returned a different pull request number.");
+  if (!["open", "closed"].includes(String(payload.state)) || typeof payload.merged !== "boolean" || typeof payload.draft !== "boolean") {
+    throw new Error("GitHub pull request state is malformed.");
+  }
+  const head = requireGitHubResponseObject(payload.head, "head");
+  const base = requireGitHubResponseObject(payload.base, "base");
+  requireRelatedPullRequestRepository(head.repo, repository);
+  requireRelatedPullRequestRepository(base.repo, repository);
+  const headRef = stringField(head.ref, "head.ref");
+  const baseRef = stringField(base.ref, "base.ref");
+  validatePullRequestBranchRef(headRef, "headBranch");
+  validatePullRequestBranchRef(baseRef, "baseBranch");
+  requireLosslessWorktreeIdentity(headRef, "branch");
+  requireLosslessWorktreeIdentity(baseRef, "branch");
+  if (redactSecrets(headRef, [token]) !== headRef || redactSecrets(baseRef, [token]) !== baseRef) {
+    throw new Error("GitHub branch identities cannot be returned safely.");
+  }
+  const mergedAt = payload.merged_at;
+  if (mergedAt !== null && (typeof mergedAt !== "string" || mergedAt.length > 40 || !Number.isFinite(Date.parse(mergedAt)))) {
+    throw new Error("GitHub pull request merge timestamp is malformed.");
+  }
+  const mergeCommitSha = payload.merge_commit_sha === null ? null : requirePullRequestCommit(payload.merge_commit_sha);
+  if (payload.merged && (payload.state !== "closed" || mergedAt === null || mergeCommitSha === null)) {
+    throw new Error("GitHub merged pull request evidence is incomplete.");
+  }
+  if (!payload.merged && mergedAt !== null) throw new Error("GitHub merge state is contradictory.");
+  return {
+    repository, number, url: requireRelatedPullRequestUrl(payload.html_url, repository, number),
+    title: boundedRelatedPullRequestValue(redactSecrets(stringField(payload.title, "title"), [token])),
+    state: payload.state as "open" | "closed", draft: payload.draft, merged: payload.merged,
+    mergedAt: mergedAt as string | null, head: headRef, base: baseRef,
+    headSha: requirePullRequestCommit(head.sha), baseSha: requirePullRequestCommit(base.sha), mergeCommitSha,
+  };
+}
+
+async function requestPullRequestJson(repository: GitHubRepository, suffix: string, token: string, options: PullRequestFetchOptions): Promise<unknown> {
+  // Bound both transport and body consumption; the same signal covers the complete request.
+  const controller = new AbortController();
+  const timer = setTimeout(controller.abort.bind(controller), 10_000);
+  const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+  try {
+    signal.throwIfAborted();
+    const response = await fetchGitHubResponse(requireFetchImplementation(options.fetchImpl ?? globalThis.fetch),
+      `${GITHUB_API_BASE_URL}/repos/${encodePathSegment(repository.owner)}/${encodePathSegment(repository.repo)}/pulls${suffix}`,
+      { method: "GET", headers: gitHubJsonHeaders(token), signal }, "GitHub pull request lookup failed", token);
+    if (!response.ok) throw new Error(`GitHub pull request lookup returned HTTP ${response.status}.`);
+    const body = await readGitHubResponseBody(response, signal, "GitHub pull request lookup response failed", token);
+    if (body.truncated) throw new Error("GitHub pull request lookup exceeded the response byte limit.");
+    return parseGitHubJson(body.text, "GitHub pull request lookup response", token);
+  } catch (error) {
+    throw new Error(truncate(redactSecrets(error instanceof Error ? error.message : String(error), [token])).replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, " "));
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function getGitHubPullRequest(repository: GitHubRepository, number: number, token: string, options: PullRequestFetchOptions = {}): Promise<PullRequestStatusDetails> {
+  validateGitHubRepository(repository);
+  pullRequestNumberField(number);
+  const payload = await requestPullRequestJson(repository, `/${number}`, token, options);
+  return parsePullRequestStatus(repository, number, requireGitHubResponseObject(payload, "Pull request"), token);
+}
+
+export async function findGitHubPullRequest(repository: GitHubRepository, headBranch: string, token: string, options: PullRequestFetchOptions = {}, state: "open" | "all" = "all"): Promise<PullRequestStatusDetails | null> {
+  validateGitHubRepository(repository);
+  validatePullRequestBranchRef(headBranch, "headBranch");
+  requireLosslessWorktreeIdentity(headBranch, "branch");
+  const query = new URLSearchParams({ state, head: `${repository.owner}:${headBranch}`, sort: "updated", direction: "desc", per_page: state === "open" ? "2" : "1" });
+  const payload = requireGitHubResponseArray(await requestPullRequestJson(repository, `?${query}`, token, options), "Pull request lookup");
+  if (payload.length === 0) return null;
+  if (payload.length > 1) throw new Error("Multiple open pull requests use this head; select a pull request by number.");
+  const row = requireGitHubResponseObject(payload[0], "Pull request lookup item");
+  const result = await getGitHubPullRequest(repository, pullRequestNumberField(row.number), token, options);
+  if (result.head !== headBranch || (state === "open" && result.state !== "open")) {
+    throw new Error("Pull request lookup no longer matches the requested head/state; retry after inspection.");
+  }
+  return result;
+}
+
+function existingPullRequestDetails(existing: PullRequestStatusDetails, input: PullRequestInput, expectedHead: string): PullRequestToolDetails {
+  if (existing.base !== input.baseBranch || existing.headSha !== expectedHead.toLowerCase()) {
+    throw new Error("Existing pull request base or head commit does not match the requested branches; inspect it before retrying.");
+  }
+  const { repository, number, url, state, head, base, draft } = existing;
+  return { repository, number, url, state, head, base, draft, outcome: "existing" };
+}
+
+export async function createOrReuseGitHubPullRequest(repository: GitHubRepository, input: PullRequestInput, expectedHead: string, token: string, options: PullRequestFetchOptions = {}): Promise<PullRequestToolDetails> {
+  validatePullRequestInput(input);
+  requirePullRequestCommit(expectedHead);
+  const existing = await findGitHubPullRequest(repository, input.headBranch, token, options, "open");
+  if (existing) return existingPullRequestDetails(existing, input, expectedHead);
+  try {
+    return { ...await createGitHubPullRequest(repository, input, token, options), outcome: "created" };
+  } catch (error) {
+    // A concurrent creator may win after our lookup. Recheck only a validation conflict,
+    // never hide network/authentication/cancellation errors or retry the POST.
+    if (!(error instanceof Error) || !error.message.startsWith("GitHub pull request request failed with HTTP 422:")) throw error;
+    const raced = await findGitHubPullRequest(repository, input.headBranch, token, options, "open");
+    if (raced) return existingPullRequestDetails(raced, input, expectedHead);
+    throw error;
+  }
+}
+
 export async function createGitHubPullRequest(
   repository: GitHubRepository,
   input: PullRequestInput,