@senad-d/branchme 0.2.2 → 0.3.1

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,
@@ -741,7 +936,7 @@ export function validateWorktreePathInput(worktreePath: unknown): string {
   return normalizedPath;
 }
 
-async function canonicalizePathAllowMissing(path: string): Promise<string | null> {
+export async function canonicalizePathAllowMissing(path: string): Promise<string | null> {
   let candidate = normalize(path);
   const suffix: string[] = [];
 
@@ -759,7 +954,7 @@ async function canonicalizePathAllowMissing(path: string): Promise<string | null
   }
 }
 
-async function collectWorktreeInventory(
+export async function collectWorktreeInventory(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
   signal?: AbortSignal,
@@ -783,7 +978,7 @@ async function collectWorktreeInventory(
   return { repoRoot, canonicalCurrentPath, entries };
 }
 
-function pathIsInsideOrEqual(candidatePath: string, boundaryPath: string): boolean {
+export function pathIsInsideOrEqual(candidatePath: string, boundaryPath: string): boolean {
   const relation = relative(boundaryPath, candidatePath);
   return relation === "" || (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation));
 }
@@ -1000,6 +1195,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,
@@ -1399,7 +1673,11 @@ async function requirePresentWorktreeDirectory(canonicalPath: string): Promise<v
 
 interface WorktreeRemovalStatus {
   workingTree: WorkingTreeDetails;
-  hasIgnoredEntries: boolean;
+  ignoredPaths: string[];
+}
+
+function compareIgnoredPaths(left: string, right: string): number {
+  return left.localeCompare(right);
 }
 
 function parseWorktreeRemovalStatus(output: string): WorktreeRemovalStatus {
@@ -1408,7 +1686,7 @@ function parseWorktreeRemovalStatus(output: string): WorktreeRemovalStatus {
   }
 
   const records = output.split(NUL_SEPARATOR);
-  let hasIgnoredEntries = false;
+  const ignoredPaths = new Set<string>();
   let skipNextRecord = false;
   for (const [index, record] of records.entries()) {
     if (skipNextRecord) {
@@ -1419,12 +1697,12 @@ function parseWorktreeRemovalStatus(output: string): WorktreeRemovalStatus {
 
     const parsed = parsePorcelainChange(records, index);
     skipNextRecord = parsed.nextIndex > index;
-    if (parsed.status === "!!") hasIgnoredEntries = true;
+    if (parsed.status === "!!") ignoredPaths.add(parsed.path.split("/")[0]);
   }
 
   return {
     workingTree: parseWorkingTreeStatus(output).workingTree,
-    hasIgnoredEntries,
+    ignoredPaths: [...ignoredPaths].sort(compareIgnoredPaths),
   };
 }
 
@@ -1432,7 +1710,8 @@ async function inspectRemovableWorktree(
   pi: Pick<ExtensionAPI, "exec">,
   canonicalPath: string,
   signal?: AbortSignal,
-): Promise<WorkingTreeDetails> {
+  allowIgnored = false,
+): Promise<WorktreeRemovalStatus> {
   const workingTree = await inspectWorktreeState(pi, canonicalPath, signal);
   if (workingTree.state !== "clean") {
     throw new Error("The target worktree has staged, unstaged, untracked, or unmerged changes; clean it before removal.");
@@ -1446,12 +1725,12 @@ async function inspectRemovableWorktree(
   if (removalStatus.workingTree.state !== "clean") {
     throw new Error("The target worktree has staged, unstaged, untracked, or unmerged changes; clean it before removal.");
   }
-  if (removalStatus.hasIgnoredEntries) {
+  if (!allowIgnored && removalStatus.ignoredPaths.length > 0) {
     throw new Error(
       "The target worktree contains ignored files or directories; remove or preserve them outside the checkout before removal.",
     );
   }
-  return workingTree;
+  return removalStatus;
 }
 
 function assertWorktreeRemoved(
@@ -1482,12 +1761,28 @@ 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);
   const rootCtx = { cwd: repoRoot };
 
-  return withRepositoryMutationQueue(repoRoot, async () => {
+  return withRepositoryMutationQueue(
+    repoRoot,
+    removeWorktreeWithinQueue.bind(undefined, pi, rootCtx, requestedWorktreePath, signal, deleteIgnored),
+  );
+}
+
+// Caller must hold the repository mutation queue. Ignored residue requires explicit authorization.
+export async function removeWorktreeWithinQueue(
+  pi: Pick<ExtensionAPI, "exec">,
+  rootCtx: GitCommandContext,
+  requestedWorktreePath: string,
+  signal?: AbortSignal,
+  allowIgnored = false,
+  expectedIdentity?: { branch: string; head: string },
+): Promise<RemoveWorktreeDetails & { deletedIgnoredPaths: string[] }> {
+    const repoRoot = rootCtx.cwd;
     const resolved = await resolveWorktreeRemovalTarget(
       pi,
       rootCtx,
@@ -1499,6 +1794,9 @@ export async function removeWorktree(
     }
 
     const worktree = requireRemovableWorktreeEntry(resolved);
+    if (expectedIdentity && (worktree.branch !== expectedIdentity.branch || worktree.head !== expectedIdentity.head)) {
+      throw new Error("The selected worktree branch or HEAD moved after the landing ancestry proof.");
+    }
     const branchName = resolved.entry.record.branch;
     const head = resolved.entry.record.head;
     if (branchName === null || head === null) {
@@ -1507,7 +1805,7 @@ export async function removeWorktree(
     const verifiedCanonicalPath = requireLosslessWorktreeIdentity(resolved.canonicalPath, "cwd");
     const retainedBranch = requireLosslessWorktreeIdentity(branchName, "branch");
     await requirePresentWorktreeDirectory(verifiedCanonicalPath);
-    const workingTree = await inspectRemovableWorktree(pi, verifiedCanonicalPath, signal);
+    const { workingTree, ignoredPaths } = await inspectRemovableWorktree(pi, verifiedCanonicalPath, signal, allowIgnored);
     const branchHeadBefore = await getLocalBranchCommit(pi, rootCtx, retainedBranch, signal);
     if (branchHeadBefore.toLowerCase() !== head.toLowerCase()) {
       throw new Error("The target local branch did not match the worktree HEAD before removal.");
@@ -1540,9 +1838,11 @@ export async function removeWorktree(
       );
       return {
         action: "remove_worktree",
+        deletedIgnoredPaths: ignoredPaths.map((path) => redactSecrets(path)),
         repoRoot: safeWorktreeValue(repoRoot, GIT_WORKTREE_PATH_LIMIT_CHARS),
         request: {
           worktreePath: safeWorktreeValue(requestedWorktreePath, GIT_WORKTREE_PATH_LIMIT_CHARS),
+          ...(allowIgnored ? { deleteIgnored: true } : {}),
         },
         verified: {
           before: {
@@ -1567,7 +1867,6 @@ export async function removeWorktree(
     } catch (error) {
       throw worktreeRemovalFailure(error, resolved.canonicalPath, branchName);
     }
-  });
 }
 
 function isRenameOrCopyStatus(status: string): boolean {
@@ -1880,8 +2179,9 @@ export async function getAheadBehindCount(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
   signal?: AbortSignal,
+  comparison = "HEAD...@{u}",
 ): Promise<AheadBehindCount> {
-  const result = await runGit(pi, ctx, ["rev-list", "--left-right", "--count", "HEAD...@{u}"], {
+  const result = await runGit(pi, ctx, ["rev-list", "--left-right", "--count", comparison], {
     signal,
     timeout: GIT_STATUS_TIMEOUT_MS,
   });
@@ -1934,9 +2234,9 @@ export async function localBranchExists(
   return result.code === 0;
 }
 
-function requireLosslessLocalRef(branchName: string): string {
+function requireLosslessLocalRef(branchName: string, prefix = "refs/heads/"): string {
   requireLosslessWorktreeIdentity(branchName, "branch");
-  const fullRef = `refs/heads/${branchName}`;
+  const fullRef = `${prefix}${branchName}`;
   if (!isLosslessGitMetadata(fullRef, GIT_CONTEXT_VALUE_LIMIT_CHARS)) {
     throw new Error(
       "The full local branch ref cannot be returned safely and losslessly. " +
@@ -2014,9 +2314,28 @@ export async function inspectDirectLocalBranchRef(
   ctx: GitCommandContext,
   branchName: string,
   signal?: AbortSignal,
+): Promise<DirectLocalBranchRefInspection> {
+  return inspectDirectBranchRef(pi, ctx, branchName, "refs/heads/", signal);
+}
+
+export async function inspectDirectRemoteTrackingRef(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  refName: string,
+  signal?: AbortSignal,
+): Promise<DirectLocalBranchRefInspection> {
+  return inspectDirectBranchRef(pi, ctx, refName, "refs/remotes/", signal);
+}
+
+async function inspectDirectBranchRef(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  branchName: string,
+  prefix: string,
+  signal?: AbortSignal,
 ): Promise<DirectLocalBranchRefInspection> {
   validateBranchNameInput(branchName);
-  const fullRef = requireLosslessLocalRef(branchName);
+  const fullRef = requireLosslessLocalRef(branchName, prefix);
   const listArgs = [
     "for-each-ref",
     "--count=1",
@@ -2317,7 +2636,22 @@ export async function fetchRemoteBranch(
   const repoRoot = await getGitRoot(pi, ctx, signal);
   const rootCtx = { cwd: repoRoot };
 
-  return withRepositoryMutationQueue(repoRoot, async () => {
+  return withRepositoryMutationQueue(
+    repoRoot,
+    fetchRemoteBranchWithinQueue.bind(undefined, pi, rootCtx, remote, branch, signal),
+  );
+}
+
+// Caller must hold the repository mutation queue.
+export async function fetchRemoteBranchWithinQueue(
+  pi: Pick<ExtensionAPI, "exec">,
+  rootCtx: GitCommandContext,
+  remote: string,
+  branch: string,
+  signal?: AbortSignal,
+): Promise<FetchRemoteBranchDetails> {
+    const repoRoot = rootCtx.cwd;
+    validateRequestedRemoteName(remote);
     await validateBranchName(pi, rootCtx, branch, signal);
     await requireConfiguredRemote(pi, rootCtx, remote, signal);
 
@@ -2343,7 +2677,6 @@ export async function fetchRemoteBranch(
       refspec: safeDetail(refspec),
       output: safeOutput(result.stdout || result.stderr),
     };
-  });
 }
 
 export async function pullCurrentBranch(

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,