@senad-d/branchme 0.1.6 → 0.1.8

package/src/git.ts

@@ -1,3 +1,5 @@
+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 {
   GIT_CONTEXT_CHANGE_LIMIT,
@@ -9,7 +11,15 @@ import {
   GIT_PUSH_TIMEOUT_MS,
   GIT_REBASE_TIMEOUT_MS,
   GIT_STATUS_TIMEOUT_MS,
+  GIT_WORKTREE_ENTRY_LIMIT,
+  GIT_WORKTREE_MUTATION_TIMEOUT_MS,
+  GIT_WORKTREE_PATH_LIMIT_CHARS,
+  GIT_WORKTREE_RAW_OUTPUT_LIMIT_BYTES,
+  GIT_WORKTREE_REASON_LIMIT_CHARS,
+  GIT_WORKTREE_SUMMARY_LIMIT_CHARS,
   MAX_SUMMARY_OUTPUT_CHARS,
+  PULL_REQUEST_AUTOFILL_COMMIT_LIMIT,
+  PULL_REQUEST_AUTOFILL_SUBJECT_LIMIT_CHARS,
 } from "./constants.ts";
 import { redactSecrets } from "./redaction.ts";
 import type {
@@ -17,16 +27,22 @@ import type {
   BranchStatusDetails,
   ChangeBranchDetails,
   CreateBranchDetails,
+  CreateWorktreeDetails,
+  CreateWorktreeMode,
   CurrentBranchInfo,
   FetchBranchDetails,
   GitExecResult,
   GitFileChange,
   GitFileChangeSummary,
+  ListWorktreesDetails,
   PullBranchDetails,
   PushBranchDetails,
   RebaseBranchDetails,
+  RemoveWorktreeDetails,
   RecentCommit,
+  VerifiedLinkedWorktreeEntry,
   WorkingTreeDetails,
+  WorktreeEntry,
 } from "./types.ts";
 
 export interface GitCommandContext {
@@ -37,6 +53,7 @@ export interface GitRunOptions {
   signal?: AbortSignal;
   timeout?: number;
   allowFailure?: boolean;
+  tokens?: readonly string[];
 }
 
 const repositoryMutationQueues = new Map<string, Promise<void>>();
@@ -114,11 +131,11 @@ export async function runGit(
   });
 
   if (result.killed) {
-    throw new Error(formatGitFailure(args, result));
+    throw new Error(formatGitFailure(args, result, options.tokens));
   }
 
   if (!options.allowFailure && result.code !== 0) {
-    throw new Error(formatGitFailure(args, result));
+    throw new Error(formatGitFailure(args, result, options.tokens));
   }
 
   return result;
@@ -333,6 +350,13 @@ const GIT_STATUS_CODE_PATTERN = /^[ MADRCUT?!]{2}$/u;
 const GIT_LOG_FIELD_SEPARATOR = "\u001f";
 const NUL_SEPARATOR = "\u0000";
 const GIT_LOG_FORMAT = `%x00%H%x1f%h%x1f%ad%x1f%s`;
+const GIT_WORKTREE_REMOVAL_IGNORED_STATUS_ARGS = [
+  "status",
+  "--porcelain=v1",
+  "-z",
+  "--untracked-files=normal",
+  "--ignored=matching",
+];
 
 function truncateGitContextValue(value: string): string {
   if (value.length <= GIT_CONTEXT_VALUE_LIMIT_CHARS) return value;
@@ -354,6 +378,1010 @@ function safeGitContextValue(value: string): string {
   return truncateGitContextValue(escaped);
 }
 
+interface ParsedWorktreeRecord {
+  rawPath: string;
+  head: string | null;
+  branch: string | null;
+  detached: boolean;
+  bare: boolean;
+  locked: boolean;
+  lockReason: string | null;
+  prunable: boolean;
+  pruneReason: string | null;
+}
+
+interface WorktreeAttribute {
+  key: string;
+  value: string | null;
+}
+
+interface WorktreeRecordState extends ParsedWorktreeRecord {
+  seen: Set<string>;
+  headSeen: boolean;
+  branchSeen: boolean;
+}
+
+function worktreeParseError(): TypeError {
+  return new TypeError("Unable to parse worktrees: malformed git worktree output.");
+}
+
+function truncateWorktreeValue(value: string, limit: number): string {
+  if (value.length <= limit) return value;
+
+  let end = limit - 1;
+  const lastCodePoint = value.codePointAt(end - 1);
+  if (lastCodePoint !== undefined && lastCodePoint > 0xffff) end -= 1;
+  return `${value.slice(0, end)}…`;
+}
+
+function safeWorktreeValue(value: string, limit: number): string {
+  const redacted = redactSecrets(value);
+  const escaped = redacted.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, escapeGitContextControlCharacter);
+  return truncateWorktreeValue(escaped, limit);
+}
+
+function splitWorktreeAttribute(line: string): WorktreeAttribute {
+  const separator = line.indexOf(" ");
+  if (separator < 0) return { key: line, value: null };
+  return { key: line.slice(0, separator), value: line.slice(separator + 1) };
+}
+
+function assertUniqueWorktreeAttribute(seen: Set<string>, key: string): void {
+  if (seen.has(key)) throw worktreeParseError();
+  seen.add(key);
+}
+
+function createWorktreeRecordState(rawPath: string): WorktreeRecordState {
+  return {
+    rawPath,
+    head: null,
+    branch: null,
+    detached: false,
+    bare: false,
+    locked: false,
+    lockReason: null,
+    prunable: false,
+    pruneReason: null,
+    seen: new Set<string>(),
+    headSeen: false,
+    branchSeen: false,
+  };
+}
+
+function parseWorktreeHead(state: WorktreeRecordState, attribute: WorktreeAttribute): void {
+  assertUniqueWorktreeAttribute(state.seen, attribute.key);
+  if (attribute.value === null || !/^[0-9a-f]{40,64}$/iu.test(attribute.value)) {
+    throw worktreeParseError();
+  }
+  state.head = attribute.value;
+  state.headSeen = true;
+}
+
+function parseWorktreeBranch(state: WorktreeRecordState, attribute: WorktreeAttribute): void {
+  assertUniqueWorktreeAttribute(state.seen, attribute.key);
+  const prefix = "refs/heads/";
+  if (!attribute.value?.startsWith(prefix)) throw worktreeParseError();
+  const branchName = attribute.value.slice(prefix.length);
+  if (!branchName) throw worktreeParseError();
+  state.branch = branchName;
+  state.branchSeen = true;
+}
+
+function parseDetachedWorktree(state: WorktreeRecordState, attribute: WorktreeAttribute): void {
+  assertUniqueWorktreeAttribute(state.seen, attribute.key);
+  if (attribute.value !== null) throw worktreeParseError();
+  state.detached = true;
+}
+
+function parseBareWorktree(state: WorktreeRecordState, attribute: WorktreeAttribute): void {
+  assertUniqueWorktreeAttribute(state.seen, attribute.key);
+  if (attribute.value !== null) throw worktreeParseError();
+  state.bare = true;
+}
+
+function parseLockedWorktree(state: WorktreeRecordState, attribute: WorktreeAttribute): void {
+  assertUniqueWorktreeAttribute(state.seen, attribute.key);
+  state.locked = true;
+  state.lockReason = attribute.value
+    ? safeWorktreeValue(attribute.value, GIT_WORKTREE_REASON_LIMIT_CHARS)
+    : null;
+}
+
+function parsePrunableWorktree(state: WorktreeRecordState, attribute: WorktreeAttribute): void {
+  assertUniqueWorktreeAttribute(state.seen, attribute.key);
+  state.prunable = true;
+  state.pruneReason = attribute.value
+    ? safeWorktreeValue(attribute.value, GIT_WORKTREE_REASON_LIMIT_CHARS)
+    : null;
+}
+
+function applyWorktreeAttribute(state: WorktreeRecordState, attribute: WorktreeAttribute): void {
+  switch (attribute.key) {
+    case "HEAD":
+      parseWorktreeHead(state, attribute);
+      break;
+    case "branch":
+      parseWorktreeBranch(state, attribute);
+      break;
+    case "detached":
+      parseDetachedWorktree(state, attribute);
+      break;
+    case "bare":
+      parseBareWorktree(state, attribute);
+      break;
+    case "locked":
+      parseLockedWorktree(state, attribute);
+      break;
+    case "prunable":
+      parsePrunableWorktree(state, attribute);
+      break;
+    case "worktree":
+      throw worktreeParseError();
+    default:
+      break;
+  }
+}
+
+function completeWorktreeRecord(state: WorktreeRecordState): ParsedWorktreeRecord {
+  if (state.bare) {
+    if (state.branchSeen || state.detached) throw worktreeParseError();
+  } else if (!state.headSeen || state.branchSeen === state.detached) {
+    throw worktreeParseError();
+  }
+
+  return {
+    rawPath: state.rawPath,
+    head: state.head,
+    branch: state.branch,
+    detached: state.detached,
+    bare: state.bare,
+    locked: state.locked,
+    lockReason: state.lockReason,
+    prunable: state.prunable,
+    pruneReason: state.pruneReason,
+  };
+}
+
+function parseWorktreeRecord(lines: string[]): ParsedWorktreeRecord {
+  const worktreeLine = lines[0];
+  if (!worktreeLine?.startsWith("worktree ")) throw worktreeParseError();
+
+  const rawPath = worktreeLine.slice("worktree ".length);
+  if (!rawPath || !isAbsolute(rawPath)) throw worktreeParseError();
+
+  const state = createWorktreeRecordState(rawPath);
+  for (const line of lines.slice(1)) {
+    applyWorktreeAttribute(state, splitWorktreeAttribute(line));
+  }
+  return completeWorktreeRecord(state);
+}
+
+function splitWorktreeRecords(output: string): string[][] {
+  if (Buffer.byteLength(output, "utf8") > GIT_WORKTREE_RAW_OUTPUT_LIMIT_BYTES) {
+    throw new TypeError("Unable to parse worktrees: git worktree output exceeded the safety limit.");
+  }
+
+  const records: string[][] = [];
+  let current: string[] = [];
+  for (const field of output.split(NUL_SEPARATOR)) {
+    if (field.length > 0) {
+      current.push(field);
+      continue;
+    }
+    if (current.length > 0) {
+      records.push(current);
+      current = [];
+    }
+  }
+  if (current.length > 0) records.push(current);
+  if (records.length === 0) throw worktreeParseError();
+  return records;
+}
+
+function parseWorktreeRecords(output: string): ParsedWorktreeRecord[] {
+  const records: ParsedWorktreeRecord[] = [];
+  for (const lines of splitWorktreeRecords(output)) records.push(parseWorktreeRecord(lines));
+  return records;
+}
+
+function worktreeEntry(record: ParsedWorktreeRecord, index: number, current: boolean): WorktreeEntry {
+  return {
+    path: safeWorktreeValue(record.rawPath, GIT_WORKTREE_PATH_LIMIT_CHARS),
+    head: record.head,
+    branch: record.branch === null ? null : safeWorktreeValue(record.branch, GIT_CONTEXT_VALUE_LIMIT_CHARS),
+    detached: record.detached,
+    bare: record.bare,
+    locked: record.locked,
+    lockReason: record.lockReason,
+    prunable: record.prunable,
+    pruneReason: record.pruneReason,
+    main: index === 0,
+    current,
+  };
+}
+
+export function parseWorktreePorcelain(output: string): Pick<ListWorktreesDetails, "worktrees" | "omitted"> {
+  const records = parseWorktreeRecords(output);
+  const worktrees: WorktreeEntry[] = [];
+  const returnedCount = Math.min(records.length, GIT_WORKTREE_ENTRY_LIMIT);
+  for (let index = 0; index < returnedCount; index += 1) {
+    worktrees.push(worktreeEntry(records[index], index, false));
+  }
+  return { worktrees, omitted: records.length - returnedCount };
+}
+
+interface WorktreeInventoryEntry {
+  record: ParsedWorktreeRecord;
+  index: number;
+  canonicalPath: string | null;
+}
+
+interface WorktreeInventory {
+  repoRoot: string;
+  canonicalCurrentPath: string;
+  entries: WorktreeInventoryEntry[];
+}
+
+interface ResolvedWorktreeRemovalTarget {
+  repoRoot: string;
+  canonicalPath: string;
+  entry: WorktreeInventoryEntry;
+  current: boolean;
+  inventory: WorktreeInventory;
+}
+
+interface PreparedWorktreeCreation {
+  inventory: WorktreeInventory;
+  commonGitDir: string;
+  canonicalPath: string;
+}
+
+export interface WorktreeCreationPathValidation {
+  repoRoot: string;
+  commonGitDir: string;
+  canonicalPath: string;
+}
+
+export interface WorktreeRemovalPathValidation {
+  repoRoot: string;
+  canonicalPath: string;
+  worktree: WorktreeEntry;
+}
+
+function filesystemErrorCode(error: unknown): string | null {
+  if (typeof error !== "object" || error === null || !("code" in error)) return null;
+  const code = (error as { code?: unknown }).code;
+  return typeof code === "string" ? code : null;
+}
+
+function isMissingFilesystemPath(error: unknown): boolean {
+  const code = filesystemErrorCode(error);
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+
+function safeWorktreePathLabel(path: string): string {
+  return JSON.stringify(safeWorktreeValue(path, GIT_WORKTREE_PATH_LIMIT_CHARS));
+}
+
+function safeWorktreeBranchLabel(branchName: string): string {
+  return JSON.stringify(safeWorktreeValue(branchName, GIT_CONTEXT_VALUE_LIMIT_CHARS));
+}
+
+export function requireLosslessWorktreeIdentity(
+  value: string,
+  identity: "cwd" | "branch",
+): string {
+  const limit = identity === "cwd" ? GIT_WORKTREE_PATH_LIMIT_CHARS : GIT_CONTEXT_VALUE_LIMIT_CHARS;
+  if (safeWorktreeValue(value, limit) === value) return value;
+
+  const label = identity === "cwd" ? "canonical worktree path" : "local branch name";
+  throw new Error(
+    `The ${label} cannot be returned safely and losslessly. Use a value of at most ${limit} characters without credential-like token text or control/format characters.`,
+  );
+}
+
+export function validateWorktreePathInput(worktreePath: unknown): string {
+  if (typeof worktreePath !== "string") throw new TypeError("worktreePath must be a string.");
+  if (worktreePath.trim().length === 0) throw new Error("worktreePath is required and cannot be blank.");
+  if (/[\p{Cc}\p{Cf}\u2028\u2029]/u.test(worktreePath)) {
+    throw new Error("worktreePath cannot contain NUL, newline, or control characters.");
+  }
+  if (!isAbsolute(worktreePath)) throw new Error("worktreePath must be an absolute path.");
+
+  const normalizedPath = normalize(worktreePath);
+  if (!basename(normalizedPath)) throw new Error("worktreePath must identify a destination below a parent directory.");
+  return normalizedPath;
+}
+
+async function canonicalizePathAllowMissing(path: string): Promise<string | null> {
+  let candidate = normalize(path);
+  const suffix: string[] = [];
+
+  for (;;) {
+    try {
+      const canonicalAncestor = await realpath(candidate);
+      return suffix.length === 0 ? canonicalAncestor : join(canonicalAncestor, ...suffix);
+    } catch (error) {
+      if (!isMissingFilesystemPath(error)) return null;
+      const parent = dirname(candidate);
+      if (parent === candidate) return null;
+      suffix.unshift(basename(candidate));
+      candidate = parent;
+    }
+  }
+}
+
+async function collectWorktreeInventory(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  signal?: AbortSignal,
+): Promise<WorktreeInventory> {
+  const repoRoot = await getGitRoot(pi, ctx, signal);
+  const args = ["worktree", "list", "--porcelain", "-z"];
+  const result = await runGit(pi, { cwd: repoRoot }, args, {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+  });
+  const records = parseWorktreeRecords(result.stdout);
+  const canonicalCurrentPath = await canonicalizePathAllowMissing(repoRoot);
+  if (!canonicalCurrentPath) {
+    throw new Error("Unable to inspect worktrees: current repository path could not be resolved.");
+  }
+
+  const entries: WorktreeInventoryEntry[] = [];
+  for (const [index, record] of records.entries()) {
+    entries.push({ record, index, canonicalPath: await canonicalizePathAllowMissing(record.rawPath) });
+  }
+  return { repoRoot, canonicalCurrentPath, entries };
+}
+
+function pathIsInsideOrEqual(candidatePath: string, boundaryPath: string): boolean {
+  const relation = relative(boundaryPath, candidatePath);
+  return relation === "" || (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation));
+}
+
+async function requireCanonicalCreationPath(worktreePath: string): Promise<string> {
+  const parentPath = dirname(worktreePath);
+  let parentStats;
+  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.`);
+  }
+
+  let canonicalParent: string;
+  try {
+    canonicalParent = await realpath(parentPath);
+  } catch {
+    throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} could not be resolved.`);
+  }
+
+  const canonicalPath = join(canonicalParent, basename(worktreePath));
+  try {
+    await lstat(canonicalPath);
+  } catch (error) {
+    if (isMissingFilesystemPath(error)) return canonicalPath;
+    throw new Error(`worktreePath destination ${safeWorktreePathLabel(canonicalPath)} could not be inspected.`);
+  }
+  throw new Error(`worktreePath destination ${safeWorktreePathLabel(canonicalPath)} already exists.`);
+}
+
+function stripSingleLineTerminator(value: string): string {
+  if (value.endsWith("\r\n")) return value.slice(0, -2);
+  if (value.endsWith("\n")) return value.slice(0, -1);
+  return value;
+}
+
+async function getCommonGitDirectory(
+  pi: Pick<ExtensionAPI, "exec">,
+  repoRoot: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const args = ["rev-parse", "--path-format=absolute", "--git-common-dir"];
+  const result = await runGit(pi, { cwd: repoRoot }, args, {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+  });
+  const commonGitDir = stripSingleLineTerminator(result.stdout);
+  if (
+    !commonGitDir ||
+    !isAbsolute(commonGitDir) ||
+    /[\p{Cc}\p{Cf}\u2028\u2029]/u.test(commonGitDir)
+  ) {
+    throw new Error("Unable to validate worktree path: Git returned an invalid common directory.");
+  }
+
+  try {
+    return await realpath(commonGitDir);
+  } catch {
+    throw new Error("Unable to validate worktree path: Git common directory could not be resolved.");
+  }
+}
+
+async function prepareWorktreeCreation(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  worktreePath: unknown,
+  signal?: AbortSignal,
+): Promise<PreparedWorktreeCreation> {
+  const normalizedPath = validateWorktreePathInput(worktreePath);
+  const canonicalPath = await requireCanonicalCreationPath(normalizedPath);
+  const inventory = await collectWorktreeInventory(pi, ctx, signal);
+
+  for (const entry of inventory.entries) {
+    if (!entry.canonicalPath) {
+      throw new Error("Unable to validate worktree path: a registered worktree path could not be resolved.");
+    }
+    if (pathIsInsideOrEqual(canonicalPath, entry.canonicalPath)) {
+      throw new Error("worktreePath destination cannot be inside a registered worktree.");
+    }
+  }
+
+  const commonGitDir = await getCommonGitDirectory(pi, inventory.repoRoot, signal);
+  if (pathIsInsideOrEqual(canonicalPath, commonGitDir)) {
+    throw new Error("worktreePath destination cannot be inside the repository common Git directory.");
+  }
+
+  return { inventory, commonGitDir, canonicalPath };
+}
+
+export async function validateWorktreeCreationPath(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  worktreePath: unknown,
+  signal?: AbortSignal,
+): Promise<WorktreeCreationPathValidation> {
+  const prepared = await prepareWorktreeCreation(pi, ctx, worktreePath, signal);
+  return {
+    repoRoot: prepared.inventory.repoRoot,
+    commonGitDir: prepared.commonGitDir,
+    canonicalPath: prepared.canonicalPath,
+  };
+}
+
+async function resolveWorktreeRemovalTarget(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  worktreePath: unknown,
+  signal?: AbortSignal,
+): Promise<ResolvedWorktreeRemovalTarget> {
+  const normalizedPath = validateWorktreePathInput(worktreePath);
+  const canonicalPath = await canonicalizePathAllowMissing(normalizedPath);
+  if (!canonicalPath) throw new Error("worktreePath could not be resolved for removal.");
+
+  const inventory = await collectWorktreeInventory(pi, ctx, signal);
+  const matches: WorktreeInventoryEntry[] = [];
+  for (const entry of inventory.entries) {
+    if (entry.canonicalPath === canonicalPath) matches.push(entry);
+  }
+  if (matches.length !== 1) {
+    throw new Error("worktreePath must exactly match a registered worktree in the current repository.");
+  }
+
+  const entry = matches[0];
+  return {
+    repoRoot: inventory.repoRoot,
+    canonicalPath,
+    entry,
+    current: canonicalPath === inventory.canonicalCurrentPath,
+    inventory,
+  };
+}
+
+export async function validateWorktreeRemovalPath(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  worktreePath: unknown,
+  signal?: AbortSignal,
+): Promise<WorktreeRemovalPathValidation> {
+  const resolved = await resolveWorktreeRemovalTarget(pi, ctx, worktreePath, signal);
+  return {
+    repoRoot: resolved.repoRoot,
+    canonicalPath: resolved.canonicalPath,
+    worktree: worktreeEntry(resolved.entry.record, resolved.entry.index, resolved.current),
+  };
+}
+
+export async function listWorktrees(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  signal?: AbortSignal,
+): Promise<ListWorktreesDetails> {
+  const inventory = await collectWorktreeInventory(pi, ctx, signal);
+  const worktrees: WorktreeEntry[] = [];
+  const returnedCount = Math.min(inventory.entries.length, GIT_WORKTREE_ENTRY_LIMIT);
+  for (let index = 0; index < returnedCount; index += 1) {
+    const entry = inventory.entries[index];
+    worktrees.push(
+      worktreeEntry(entry.record, entry.index, entry.canonicalPath === inventory.canonicalCurrentPath),
+    );
+  }
+
+  return {
+    action: "list_worktrees",
+    repoRoot: safeWorktreeValue(inventory.repoRoot, GIT_WORKTREE_PATH_LIMIT_CHARS),
+    worktrees,
+    omitted: inventory.entries.length - returnedCount,
+  };
+}
+
+function validateCreateWorktreeMode(branchMode: unknown): asserts branchMode is CreateWorktreeMode {
+  if (branchMode !== "new" && branchMode !== "existing") {
+    throw new Error("branchMode must be either 'new' or 'existing'.");
+  }
+}
+
+async function getCurrentHeadCommit(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  signal?: AbortSignal,
+): Promise<string> {
+  const args = ["rev-parse", "--verify", "HEAD^{commit}"];
+  const result = await runGit(pi, ctx, args, {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+    allowFailure: true,
+  });
+  const head = trimOutput(result.stdout);
+  if (result.code !== 0 || !/^[0-9a-f]{40,64}$/iu.test(head)) {
+    throw new Error("Current HEAD must resolve to a valid commit before creating a worktree.");
+  }
+  return head;
+}
+
+function requireSourceWorktreeEntry(
+  inventory: WorktreeInventory,
+  source: CurrentBranchInfo,
+  sourceHead: string,
+): WorktreeInventoryEntry {
+  const matches = inventory.entries.filter(
+    (entry) => entry.canonicalPath === inventory.canonicalCurrentPath,
+  );
+  if (matches.length !== 1) {
+    throw new Error("Unable to verify the source worktree in the current repository inventory.");
+  }
+
+  const sourceEntry = matches[0];
+  const record = sourceEntry.record;
+  const branchMatches = source.detached
+    ? record.detached && record.branch === null
+    : !record.detached && record.branch === source.currentBranch;
+  if (
+    record.bare ||
+    record.head?.toLowerCase() !== sourceHead.toLowerCase() ||
+    !branchMatches
+  ) {
+    throw new Error("Unable to verify the source branch and HEAD against the worktree inventory.");
+  }
+  return sourceEntry;
+}
+
+function branchIsCheckedOut(inventory: WorktreeInventory, branchName: string): boolean {
+  return inventory.entries.some((entry) => entry.record.branch === branchName);
+}
+
+function requireCreatedWorktreeEntry(
+  inventory: WorktreeInventory,
+  canonicalPath: string,
+  branchName: string,
+  expectedHead: string,
+): VerifiedLinkedWorktreeEntry {
+  const matches = inventory.entries.filter((entry) => entry.canonicalPath === canonicalPath);
+  if (matches.length !== 1) {
+    throw new Error("The created destination was not registered exactly once in the worktree inventory.");
+  }
+
+  const matched = matches[0];
+  const record = matched.record;
+  const current = canonicalPath === inventory.canonicalCurrentPath;
+  if (
+    matched.index === 0 ||
+    current ||
+    record.head?.toLowerCase() !== expectedHead.toLowerCase() ||
+    record.branch !== branchName ||
+    record.detached ||
+    record.bare ||
+    record.locked ||
+    record.prunable
+  ) {
+    throw new Error("The created worktree did not match the requested path, local branch, and HEAD.");
+  }
+
+  return {
+    path: canonicalPath,
+    head: record.head,
+    branch: branchName,
+    detached: false,
+    bare: false,
+    locked: false,
+    lockReason: null,
+    prunable: false,
+    pruneReason: null,
+    main: false,
+    current: false,
+  };
+}
+
+async function inspectWorktreeState(
+  pi: Pick<ExtensionAPI, "exec">,
+  canonicalPath: string,
+  signal?: AbortSignal,
+): Promise<WorkingTreeDetails> {
+  const args = ["status", "--porcelain=v1", "-z", "--untracked-files=normal"];
+  const result = await runGit(pi, { cwd: canonicalPath }, args, {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+  });
+  return parseWorkingTreeStatus(result.stdout).workingTree;
+}
+
+async function inspectCreatedWorktree(
+  pi: Pick<ExtensionAPI, "exec">,
+  canonicalPath: string,
+  signal?: AbortSignal,
+): Promise<WorkingTreeDetails> {
+  const workingTree = await inspectWorktreeState(pi, canonicalPath, signal);
+  if (workingTree.state !== "clean") {
+    throw new Error("The created worktree was not clean after checkout.");
+  }
+  return workingTree;
+}
+
+function worktreeCreationFailure(
+  error: unknown,
+  canonicalPath: string,
+  branchName: string,
+): Error {
+  const rawReason = error instanceof Error ? error.message : String(error);
+  const reason = safeOutput(rawReason, [canonicalPath, branchName]);
+  const reasonText = reason ? ` Reason: ${reason}` : "";
+  return new Error(
+    `Worktree creation at ${safeWorktreePathLabel(canonicalPath)} did not complete with verified postconditions.${reasonText} ` +
+    "The repository and destination should be inspected; no automatic cleanup was attempted.",
+  );
+}
+
+export async function createWorktree(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  worktreePath: unknown,
+  branchName: string,
+  branchMode: CreateWorktreeMode,
+  signal?: AbortSignal,
+): Promise<CreateWorktreeDetails> {
+  validateCreateWorktreeMode(branchMode);
+  const requestedWorktreePath = validateWorktreePathInput(worktreePath);
+  const repoRoot = await getGitRoot(pi, ctx, signal);
+  const rootCtx = { cwd: repoRoot };
+
+  return withRepositoryMutationQueue(repoRoot, async () => {
+    const source = await getCurrentBranch(pi, rootCtx, signal);
+    const sourceHead = await getCurrentHeadCommit(pi, rootCtx, signal);
+    const prepared = await prepareWorktreeCreation(pi, rootCtx, requestedWorktreePath, signal);
+    if (prepared.inventory.repoRoot !== repoRoot) {
+      throw new Error("The current repository changed while preparing worktree creation.");
+    }
+    const handoffCwd = requireLosslessWorktreeIdentity(prepared.canonicalPath, "cwd");
+    validateBranchNameInput(branchName);
+    const handoffBranch = requireLosslessWorktreeIdentity(branchName, "branch");
+    requireSourceWorktreeEntry(prepared.inventory, source, sourceHead);
+
+    await validateBranchName(pi, rootCtx, branchName, signal);
+    const branchExisted = await localBranchExists(pi, rootCtx, branchName, signal);
+    if (branchMode === "new" && branchExisted) {
+      throw new Error(`Local branch ${safeWorktreeBranchLabel(branchName)} already exists.`);
+    }
+    if (branchMode === "existing" && !branchExisted) {
+      throw new Error(`Local branch ${safeWorktreeBranchLabel(branchName)} does not exist.`);
+    }
+    if (branchMode === "existing" && branchIsCheckedOut(prepared.inventory, branchName)) {
+      throw new Error(`Local branch ${safeWorktreeBranchLabel(branchName)} is already checked out in a worktree.`);
+    }
+
+    const expectedHead = branchMode === "new"
+      ? sourceHead
+      : await getLocalBranchCommit(pi, rootCtx, branchName, signal);
+    const args = branchMode === "new"
+      ? ["worktree", "add", "-b", branchName, prepared.canonicalPath, "HEAD"]
+      : ["worktree", "add", prepared.canonicalPath, branchName];
+
+    try {
+      await runGit(pi, rootCtx, args, {
+        signal,
+        timeout: GIT_WORKTREE_MUTATION_TIMEOUT_MS,
+      });
+      const afterInventory = await collectWorktreeInventory(pi, rootCtx, signal);
+      if (
+        afterInventory.repoRoot !== repoRoot ||
+        afterInventory.canonicalCurrentPath !== prepared.inventory.canonicalCurrentPath
+      ) {
+        throw new Error("The source repository changed while verifying worktree creation.");
+      }
+      requireSourceWorktreeEntry(afterInventory, source, sourceHead);
+      const worktree = requireCreatedWorktreeEntry(
+        afterInventory,
+        prepared.canonicalPath,
+        branchName,
+        expectedHead,
+      );
+      const workingTree = await inspectCreatedWorktree(pi, prepared.canonicalPath, signal);
+      const displayCanonicalPath = safeWorktreeValue(handoffCwd, GIT_WORKTREE_PATH_LIMIT_CHARS);
+      const displayBranchName = safeWorktreeValue(handoffBranch, GIT_CONTEXT_VALUE_LIMIT_CHARS);
+      const summary = safeWorktreeValue(
+        `Worktree ready at ${displayCanonicalPath} on branch ${displayBranchName} at ${worktree.head}.`,
+        GIT_WORKTREE_SUMMARY_LIMIT_CHARS,
+      );
+
+      return {
+        action: "create_worktree",
+        repoRoot: safeWorktreeValue(repoRoot, GIT_WORKTREE_PATH_LIMIT_CHARS),
+        request: {
+          worktreePath: safeWorktreeValue(requestedWorktreePath, GIT_WORKTREE_PATH_LIMIT_CHARS),
+          branchName: handoffBranch,
+          branchMode,
+        },
+        verified: {
+          before: {
+            sourcePath: safeWorktreeValue(
+              prepared.inventory.canonicalCurrentPath,
+              GIT_WORKTREE_PATH_LIMIT_CHARS,
+            ),
+            sourceBranch: source.currentBranch === null
+              ? null
+              : safeWorktreeValue(source.currentBranch, GIT_CONTEXT_VALUE_LIMIT_CHARS),
+            sourceDetached: source.detached,
+            sourceHead,
+            canonicalWorktreePath: handoffCwd,
+            branchExisted,
+            destinationRegistered: false,
+          },
+          after: {
+            worktreePresent: true,
+            worktree,
+            workingTree,
+          },
+        },
+        handoff: {
+          cwd: handoffCwd,
+          branch: handoffBranch,
+          head: worktree.head,
+          ready: true,
+          summary,
+        },
+      };
+    } catch (error) {
+      throw worktreeCreationFailure(error, prepared.canonicalPath, branchName);
+    }
+  });
+}
+
+function requireRemovableWorktreeEntry(
+  resolved: ResolvedWorktreeRemovalTarget,
+): VerifiedLinkedWorktreeEntry {
+  const record = resolved.entry.record;
+  if (resolved.entry.index === 0) throw new Error("The main worktree cannot be removed.");
+  if (resolved.current) throw new Error("The current worktree cannot be removed.");
+  if (record.bare) throw new Error("A bare worktree entry cannot be removed.");
+  if (record.locked) throw new Error("A locked worktree cannot be removed.");
+  if (record.prunable) throw new Error("A prunable or missing worktree cannot be removed.");
+  if (record.detached || record.branch === null) {
+    throw new Error("A detached worktree cannot be removed by this operation.");
+  }
+  if (record.head === null) throw new Error("The target worktree HEAD could not be verified.");
+
+  return {
+    path: resolved.canonicalPath,
+    head: record.head,
+    branch: record.branch,
+    detached: false,
+    bare: false,
+    locked: false,
+    lockReason: null,
+    prunable: false,
+    pruneReason: null,
+    main: false,
+    current: false,
+  };
+}
+
+async function requirePresentWorktreeDirectory(canonicalPath: string): Promise<void> {
+  let targetStats;
+  try {
+    targetStats = await stat(canonicalPath);
+  } catch {
+    throw new Error(`Worktree ${safeWorktreePathLabel(canonicalPath)} is missing and cannot be removed.`);
+  }
+  if (!targetStats.isDirectory()) {
+    throw new Error(`Worktree ${safeWorktreePathLabel(canonicalPath)} is not a directory.`);
+  }
+
+  let resolvedPath: string;
+  try {
+    resolvedPath = await realpath(canonicalPath);
+  } catch {
+    throw new Error(`Worktree ${safeWorktreePathLabel(canonicalPath)} could not be resolved.`);
+  }
+  if (resolvedPath !== canonicalPath) {
+    throw new Error("The target worktree path changed while preparing removal.");
+  }
+}
+
+interface WorktreeRemovalStatus {
+  workingTree: WorkingTreeDetails;
+  hasIgnoredEntries: boolean;
+}
+
+function parseWorktreeRemovalStatus(output: string): WorktreeRemovalStatus {
+  if (Buffer.byteLength(output, "utf8") > GIT_WORKTREE_RAW_OUTPUT_LIMIT_BYTES) {
+    throw new Error("Unable to inspect ignored worktree entries: git status output exceeded the safety limit.");
+  }
+
+  const records = output.split(NUL_SEPARATOR);
+  let hasIgnoredEntries = false;
+  let skipNextRecord = false;
+  for (const [index, record] of records.entries()) {
+    if (skipNextRecord) {
+      skipNextRecord = false;
+      continue;
+    }
+    if (record.length === 0) continue;
+
+    const parsed = parsePorcelainChange(records, index);
+    skipNextRecord = parsed.nextIndex > index;
+    if (parsed.status === "!!") hasIgnoredEntries = true;
+  }
+
+  return {
+    workingTree: parseWorkingTreeStatus(output).workingTree,
+    hasIgnoredEntries,
+  };
+}
+
+async function inspectRemovableWorktree(
+  pi: Pick<ExtensionAPI, "exec">,
+  canonicalPath: string,
+  signal?: AbortSignal,
+): Promise<WorkingTreeDetails> {
+  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.");
+  }
+
+  const ignoredResult = await runGit(pi, { cwd: canonicalPath }, GIT_WORKTREE_REMOVAL_IGNORED_STATUS_ARGS, {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+  });
+  const removalStatus = parseWorktreeRemovalStatus(ignoredResult.stdout);
+  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) {
+    throw new Error(
+      "The target worktree contains ignored files or directories; remove or preserve them outside the checkout before removal.",
+    );
+  }
+  return workingTree;
+}
+
+function assertWorktreeRemoved(
+  inventory: WorktreeInventory,
+  canonicalPath: string,
+): void {
+  if (inventory.entries.some((entry) => entry.canonicalPath === canonicalPath)) {
+    throw new Error("The target remained registered after git worktree remove.");
+  }
+}
+
+function worktreeRemovalFailure(
+  error: unknown,
+  canonicalPath: string,
+  branchName: string,
+): Error {
+  const rawReason = error instanceof Error ? error.message : String(error);
+  const reason = safeOutput(rawReason, [canonicalPath, branchName]);
+  const reasonText = reason ? ` Reason: ${reason}` : "";
+  return new Error(
+    `Worktree removal at ${safeWorktreePathLabel(canonicalPath)} did not complete with verified postconditions.${reasonText} ` +
+    "The repository and target should be inspected; no force or branch deletion was attempted.",
+  );
+}
+
+export async function removeWorktree(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  worktreePath: unknown,
+  signal?: AbortSignal,
+): Promise<RemoveWorktreeDetails> {
+  const requestedWorktreePath = validateWorktreePathInput(worktreePath);
+  const repoRoot = await getGitRoot(pi, ctx, signal);
+  const rootCtx = { cwd: repoRoot };
+
+  return withRepositoryMutationQueue(repoRoot, async () => {
+    const resolved = await resolveWorktreeRemovalTarget(
+      pi,
+      rootCtx,
+      requestedWorktreePath,
+      signal,
+    );
+    if (resolved.repoRoot !== repoRoot) {
+      throw new Error("The current repository changed while preparing worktree removal.");
+    }
+
+    const worktree = requireRemovableWorktreeEntry(resolved);
+    const branchName = resolved.entry.record.branch;
+    const head = resolved.entry.record.head;
+    if (branchName === null || head === null) {
+      throw new Error("The target branch and HEAD could not be captured before removal.");
+    }
+    const verifiedCanonicalPath = requireLosslessWorktreeIdentity(resolved.canonicalPath, "cwd");
+    const retainedBranch = requireLosslessWorktreeIdentity(branchName, "branch");
+    await requirePresentWorktreeDirectory(verifiedCanonicalPath);
+    const workingTree = await inspectRemovableWorktree(pi, verifiedCanonicalPath, signal);
+    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.");
+    }
+
+    const args = ["worktree", "remove", verifiedCanonicalPath];
+    try {
+      await runGit(pi, rootCtx, args, {
+        signal,
+        timeout: GIT_WORKTREE_MUTATION_TIMEOUT_MS,
+      });
+      const afterInventory = await collectWorktreeInventory(pi, rootCtx, signal);
+      if (
+        afterInventory.repoRoot !== repoRoot ||
+        afterInventory.canonicalCurrentPath !== resolved.inventory.canonicalCurrentPath
+      ) {
+        throw new Error("The source repository changed while verifying worktree removal.");
+      }
+      assertWorktreeRemoved(afterInventory, verifiedCanonicalPath);
+      const branchHeadAfter = await getLocalBranchCommit(pi, rootCtx, retainedBranch, signal);
+      if (branchHeadAfter.toLowerCase() !== head.toLowerCase()) {
+        throw new Error("The retained local branch moved after worktree removal.");
+      }
+
+      const displayCanonicalPath = safeWorktreeValue(verifiedCanonicalPath, GIT_WORKTREE_PATH_LIMIT_CHARS);
+      const displayBranchName = safeWorktreeValue(retainedBranch, GIT_CONTEXT_VALUE_LIMIT_CHARS);
+      const summary = safeWorktreeValue(
+        `Worktree directory ${displayCanonicalPath} was removed; local branch ${displayBranchName} was retained at ${head}.`,
+        GIT_WORKTREE_SUMMARY_LIMIT_CHARS,
+      );
+      return {
+        action: "remove_worktree",
+        repoRoot: safeWorktreeValue(repoRoot, GIT_WORKTREE_PATH_LIMIT_CHARS),
+        request: {
+          worktreePath: safeWorktreeValue(requestedWorktreePath, GIT_WORKTREE_PATH_LIMIT_CHARS),
+        },
+        verified: {
+          before: {
+            worktree,
+            workingTree,
+          },
+          after: {
+            worktreePresent: false,
+            branchRetained: true,
+            branch: retainedBranch,
+            head,
+          },
+        },
+        handoff: {
+          cwd: null,
+          branch: retainedBranch,
+          head,
+          ready: false,
+          summary,
+        },
+      };
+    } catch (error) {
+      throw worktreeRemovalFailure(error, resolved.canonicalPath, branchName);
+    }
+  });
+}
+
 function isRenameOrCopyStatus(status: string): boolean {
   return status.startsWith("R") || status.startsWith("C") || status.endsWith("R") || status.endsWith("C");
 }
@@ -568,6 +1596,98 @@ export async function getRecentCommits(
   throw new Error(formatGitFailure(args, result));
 }
 
+function truncatePullRequestCommitSubject(value: string): string {
+  if (value.length <= PULL_REQUEST_AUTOFILL_SUBJECT_LIMIT_CHARS) return value;
+
+  let end = PULL_REQUEST_AUTOFILL_SUBJECT_LIMIT_CHARS - 1;
+  const lastCodePoint = value.codePointAt(end - 1);
+  if (lastCodePoint !== undefined && lastCodePoint > 0xffff) end -= 1;
+  return `${value.slice(0, end).trimEnd()}…`;
+}
+
+function safePullRequestCommitSubject(value: string, tokens: readonly string[]): string {
+  const normalized = redactSecrets(value, tokens)
+    .replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, " ")
+    .replace(/\s+/gu, " ")
+    .trim();
+  return truncatePullRequestCommitSubject(normalized);
+}
+
+async function getOriginDefaultBranch(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  signal?: AbortSignal,
+): Promise<string | null> {
+  const args = ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"];
+  const result = await runGit(pi, ctx, args, {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+    allowFailure: true,
+  });
+  if (result.code !== 0) return null;
+
+  const remoteBranch = trimOutput(result.stdout);
+  const prefix = "origin/";
+  if (!remoteBranch.startsWith(prefix)) return null;
+
+  const branch = remoteBranch.slice(prefix.length);
+  try {
+    validateBranchNameInput(branch, "Default base branch");
+  } catch {
+    return null;
+  }
+  return branch;
+}
+
+export async function inferPullRequestBaseBranch(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  headBranch: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  validateBranchNameInput(headBranch, "headBranch");
+  const originDefault = await getOriginDefaultBranch(pi, ctx, signal);
+  if (originDefault) {
+    if (originDefault === headBranch) {
+      throw new Error("Unable to infer baseBranch because the current branch is the origin default branch.");
+    }
+    if (await localBranchExists(pi, ctx, originDefault, signal)) return originDefault;
+  }
+
+  for (const candidate of ["main", "master", "trunk", "develop"]) {
+    if (candidate !== headBranch && await localBranchExists(pi, ctx, candidate, signal)) return candidate;
+  }
+
+  throw new Error(
+    "Unable to infer baseBranch from origin/HEAD or a local main, master, trunk, or develop branch; provide baseBranch explicitly.",
+  );
+}
+
+export async function getPullRequestCommitSubjects(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  headBranch: string,
+  baseBranch: string,
+  signal?: AbortSignal,
+  tokens: readonly string[] = [],
+): Promise<string[]> {
+  validateBranchNameInput(headBranch, "headBranch");
+  validateBranchNameInput(baseBranch, "baseBranch");
+  const revisionRange = `refs/heads/${baseBranch}..refs/heads/${headBranch}`;
+  const args = [
+    "log",
+    `--max-count=${PULL_REQUEST_AUTOFILL_COMMIT_LIMIT}`,
+    "--format=%s",
+    revisionRange,
+    "--",
+  ];
+  const result = await runGit(pi, ctx, args, { signal, timeout: GIT_STATUS_TIMEOUT_MS, tokens });
+  return result.stdout
+    .split(/\r?\n/u)
+    .map((subject) => safePullRequestCommitSubject(subject, tokens))
+    .filter(Boolean);
+}
+
 export async function getAheadBehindCount(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -608,7 +1728,7 @@ export async function validateBranchName(
   const args = ["check-ref-format", "--branch", branchName];
   const result = await runGit(pi, ctx, args, { signal, timeout: GIT_STATUS_TIMEOUT_MS, allowFailure: true });
   if (result.code !== 0) {
-    throw new Error(`Invalid branch name '${redactSecrets(branchName)}': ${safeOutput(result.stderr || result.stdout) || "git rejected the ref"}`);
+    throw new Error(`Invalid branch name '${safeGitContextValue(branchName)}': ${safeOutput(result.stderr || result.stdout) || "git rejected the ref"}`);
   }
 }
 
@@ -639,7 +1759,7 @@ export async function getLocalBranchCommit(
   });
   const commit = trimOutput(result.stdout);
   if (!/^[0-9a-f]{40,64}$/iu.test(commit)) {
-    throw new Error(`Unable to resolve local branch '${redactSecrets(branchName)}' to a commit: ${safeOutput(result.stdout) || "empty output"}`);
+    throw new Error(`Unable to resolve local branch '${safeGitContextValue(branchName)}' to a commit: ${safeOutput(result.stdout) || "empty output"}`);
   }
   return commit;
 }