@senad-d/branchme 0.2.2 → 0.3.1

package/src/constants.ts

@@ -2,6 +2,10 @@ export const EXTENSION_DISPLAY_NAME = "BranchMe";
 export const BRANCHME_COMMAND_NAME = "branchme";
 
 export const BRANCH_STATUS_TOOL_NAME = "branch_status";
+export const LIST_BRANCHES_TOOL_NAME = "list_branches";
+export const TRACK_BRANCH_TOOL_NAME = "track_branch";
+export const UPDATE_FROM_BASE_TOOL_NAME = "update_from_base";
+export const INIT_REPOSITORY_TOOL_NAME = "init_repository";
 export const CREATE_BRANCH_TOOL_NAME = "create_branch";
 export const CHANGE_BRANCH_TOOL_NAME = "change_branch";
 export const FETCH_BRANCH_TOOL_NAME = "fetch_branch";
@@ -9,15 +13,21 @@ export const PULL_BRANCH_TOOL_NAME = "pull_branch";
 export const REBASE_BRANCH_TOOL_NAME = "rebase_branch";
 export const PUSH_BRANCH_TOOL_NAME = "push_branch";
 export const PULL_REQUEST_TOOL_NAME = "pull_request";
+export const PULL_REQUEST_STATUS_TOOL_NAME = "pull_request_status";
 export const LIST_WORKTREES_TOOL_NAME = "list_worktrees";
 export const CREATE_WORKTREE_TOOL_NAME = "create_worktree";
 export const REMOVE_WORKTREE_TOOL_NAME = "remove_worktree";
 export const INTEGRATE_BRANCH_TOOL_NAME = "integrate_branch";
 export const RETIRE_BRANCH_TOOL_NAME = "retire_branch";
+export const LAND_BRANCH_TOOL_NAME = "land_branch";
 export const PULL_REQUEST_AUTOFILL_ENV_NAME = "BRANCHME_PR_AUTOFILL";
 
 export const BRANCHME_TOOL_NAMES = [
   BRANCH_STATUS_TOOL_NAME,
+  LIST_BRANCHES_TOOL_NAME,
+  TRACK_BRANCH_TOOL_NAME,
+  UPDATE_FROM_BASE_TOOL_NAME,
+  INIT_REPOSITORY_TOOL_NAME,
   CREATE_BRANCH_TOOL_NAME,
   CHANGE_BRANCH_TOOL_NAME,
   FETCH_BRANCH_TOOL_NAME,
@@ -25,8 +35,10 @@ export const BRANCHME_TOOL_NAMES = [
   REBASE_BRANCH_TOOL_NAME,
   INTEGRATE_BRANCH_TOOL_NAME,
   RETIRE_BRANCH_TOOL_NAME,
+  LAND_BRANCH_TOOL_NAME,
   PUSH_BRANCH_TOOL_NAME,
   PULL_REQUEST_TOOL_NAME,
+  PULL_REQUEST_STATUS_TOOL_NAME,
   LIST_WORKTREES_TOOL_NAME,
   CREATE_WORKTREE_TOOL_NAME,
   REMOVE_WORKTREE_TOOL_NAME,
@@ -49,6 +61,9 @@ export const GIT_CONTEXT_VALUE_LIMIT_CHARS = 512;
 export const GIT_CONTEXT_SUMMARY_LIMIT_CHARS = 4_000;
 export const PULL_REQUEST_AUTOFILL_COMMIT_LIMIT = 20;
 export const PULL_REQUEST_AUTOFILL_SUBJECT_LIMIT_CHARS = 256;
+export const GIT_BRANCH_RAW_OUTPUT_LIMIT_BYTES = 128 * 1024;
+export const GIT_BRANCH_ENTRY_LIMIT = 200;
+export const GIT_BRANCH_SUMMARY_LIMIT_CHARS = 4_000;
 export const GIT_WORKTREE_RAW_OUTPUT_LIMIT_BYTES = 128 * 1024;
 export const GIT_WORKTREE_ENTRY_LIMIT = 100;
 export const GIT_WORKTREE_PATH_LIMIT_CHARS = 4_096;

package/src/git-integration.ts

@@ -16,6 +16,8 @@ import {
   getCurrentBranch,
   getGitOperationState,
   getLocalBranchCommit,
+  getRemoteTrackingRefCommit,
+  inspectDirectRemoteTrackingRef,
   isCommitAncestor,
   isLosslessGitMetadata,
   parseWorkingTreeStatus,
@@ -44,6 +46,7 @@ export interface PreparedBranchIntegration {
   sourceHead: string;
   targetHead: string;
   sourceAlreadyIntegrated: boolean;
+  remoteSource?: true;
 }
 
 interface IntegrationStateSnapshot {
@@ -186,6 +189,20 @@ function parseConflictPaths(output: string): CapturedConflictPaths {
   };
 }
 
+async function integrationSourceHead(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  sourceBranch: string,
+  signal?: AbortSignal,
+  remoteSource = false,
+): Promise<string> {
+  if (!remoteSource) return getLocalBranchCommit(pi, ctx, sourceBranch, signal);
+  const ref = await inspectDirectRemoteTrackingRef(pi, ctx, sourceBranch, signal);
+  const head = await getRemoteTrackingRefCommit(pi, ctx, sourceBranch, signal);
+  if (ref.status !== "present" || ref.objectId !== head) throw new Error("Integration source must be a direct remote-tracking commit ref.");
+  return head;
+}
+
 async function inspectIntegrationState(
   pi: Pick<ExtensionAPI, "exec">,
   prepared: PreparedBranchIntegration,
@@ -195,7 +212,7 @@ async function inspectIntegrationState(
   const worktreeRoot = await getCanonicalGitWorktreeRoot(pi, rootCtx, signal);
   const canonicalCommonGitDirectory = await getCanonicalCommonGitDirectory(pi, rootCtx, signal);
   const current = await getCurrentBranch(pi, rootCtx, signal);
-  const sourceHead = await getLocalBranchCommit(pi, rootCtx, prepared.sourceBranch, signal);
+  const sourceHead = await integrationSourceHead(pi, rootCtx, prepared.sourceBranch, signal, prepared.remoteSource);
   const targetHead = await getLocalBranchCommit(pi, rootCtx, prepared.targetBranch, signal);
   const operationState = await getGitOperationState(pi, rootCtx, signal);
   const statusResult = await runGit(pi, rootCtx, INTEGRATION_STATUS_ARGS, {
@@ -357,7 +374,7 @@ async function runMerge(
   prepared: PreparedBranchIntegration,
   signal?: AbortSignal,
 ): Promise<Error | null> {
-  const args = mergeArgs(prepared.sourceBranch);
+  const args = prepared.remoteSource ? [...INTEGRATION_MERGE_POLICY_ARGS, prepared.sourceHead] : mergeArgs(prepared.sourceBranch);
   let result: GitExecResult;
   try {
     result = await runGit(pi, { cwd: prepared.worktreeRoot }, args, {
@@ -544,14 +561,16 @@ async function recoverFailedMerge(
   throw mergeFailure;
 }
 
-async function integrateBranchWithinQueue(
+// Caller holds the mutation queue. Remote sources are internal to update_from_base only.
+export async function integrateBranchWithinQueue(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
   request: IntegrateBranchToolInput,
   queuedWorktreeRoot: string,
   signal?: AbortSignal,
+  remoteSource = false,
 ): Promise<IntegrateBranchDetails> {
-  const prepared = await prepareBranchIntegration(pi, ctx, request, signal);
+  const prepared = await prepareBranchIntegration(pi, ctx, request, signal, remoteSource);
   if (prepared.worktreeRoot !== queuedWorktreeRoot) {
     throw new Error("The control worktree changed while preparing branch integration.");
   }
@@ -591,6 +610,7 @@ export async function prepareBranchIntegration(
   ctx: GitCommandContext,
   request: IntegrateBranchToolInput,
   signal?: AbortSignal,
+  remoteSource = false,
 ): Promise<PreparedBranchIntegration> {
   validateBranchNameInput(request.sourceBranch, "Source branch");
   validateBranchNameInput(request.targetBranch, "Target branch");
@@ -604,9 +624,9 @@ export async function prepareBranchIntegration(
 
   await validateBranchName(pi, rootCtx, request.sourceBranch, signal);
   await validateBranchName(pi, rootCtx, request.targetBranch, signal);
-  await requireExistingLocalBranch(pi, rootCtx, request.sourceBranch, "Source", signal);
+  if (!remoteSource) await requireExistingLocalBranch(pi, rootCtx, request.sourceBranch, "Source", signal);
   await requireExistingLocalBranch(pi, rootCtx, request.targetBranch, "Target", signal);
-  const sourceHead = await getLocalBranchCommit(pi, rootCtx, request.sourceBranch, signal);
+  const sourceHead = await integrationSourceHead(pi, rootCtx, request.sourceBranch, signal, remoteSource);
   const targetHead = await getLocalBranchCommit(pi, rootCtx, request.targetBranch, signal);
 
   const current = await getCurrentBranch(pi, rootCtx, signal);
@@ -651,6 +671,7 @@ export async function prepareBranchIntegration(
     sourceHead,
     targetHead,
     sourceAlreadyIntegrated,
+    ...(remoteSource ? { remoteSource: true as const } : {}),
   };
 }
 

package/src/git-landing.ts

@@ -0,0 +1,501 @@
+import { lstat, realpath } from "node:fs/promises";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { GIT_FETCH_TIMEOUT_MS, GIT_PULL_TIMEOUT_MS, MAX_SUMMARY_OUTPUT_CHARS } from "./constants.ts";
+import {
+  canonicalizePathAllowMissing,
+  collectWorktreeInventory,
+  fetchRemoteBranchWithinQueue,
+  formatGitFailure,
+  getAheadBehindCount,
+  getCanonicalCommonGitDirectory,
+  getCanonicalGitWorktreeRoot,
+  getCurrentBranch,
+  getGitOperationState,
+  getLocalBranchCommit,
+  getRemoteTrackingRefCommit,
+  getWorkingTreeStatus,
+  inspectDirectLocalBranchRef,
+  inspectDirectRemoteTrackingRef,
+  isCommitAncestor,
+  pathIsInsideOrEqual,
+  removeWorktreeWithinQueue,
+  requireLosslessWorktreeIdentity,
+  runGit,
+  validateBranchName,
+  validateBranchNameInput,
+  validateWorktreePathInput,
+  validateWorktreeRemovalPath,
+  withRepositoryMutationQueue,
+  type GitCommandContext,
+} from "./git.ts";
+import { retireBranchWithinQueue } from "./git-retirement.ts";
+import { redactSecrets } from "./redaction.ts";
+import { getGitHubPullRequest, parseGitHubRepository, repositoriesEqual, resolveGitHubRepository, resolveGitHubToken, type RelatedPullRequestLookupOptions } from "./github.ts";
+import type { AheadBehindCount } from "./types.ts";
+
+type GitAPI = Pick<ExtensionAPI, "exec">;
+type Inventory = Awaited<ReturnType<typeof collectWorktreeInventory>>;
+
+export interface LandBranchInput {
+  sourceBranch: string;
+  targetBranch: string;
+  remote?: string;
+  worktreePath?: string;
+  pullRequestNumber?: number;
+}
+
+export interface LandBranchReceipt {
+  repositoryRoot: string;
+  remote: string;
+  targetBranch: string;
+  remoteTargetHead: string | null;
+  sourceBranch: string;
+  sourceHead: string | null;
+  ancestry: { isAncestor: boolean | null };
+  mergeProof: "ancestry" | "pull-request" | null;
+  pullRequest: { number: number; headSha: string; mergeCommitSha: string } | null;
+  worktree: {
+    path: string | null;
+    outcome: "removed" | "absent" | "refused";
+    reason: string | null;
+    deletedIgnoredPaths: string[];
+  };
+  branch: {
+    outcome: "deleted" | "absent" | "refused";
+    reason: string | null;
+    expectedHead: string | null;
+  };
+  targetSync: {
+    mode: "fetch-refspec" | "pull-ff" | "skipped-dirty" | "noop" | "not-run" | "failed";
+    worktreePath: string | null;
+    before: string | null;
+    after: string | null;
+    aheadBehind: AheadBehindCount | null;
+    reason: string | null;
+  };
+  steps: {
+    step: "repository" | "cwd" | "fetch" | "ancestry" | "worktree" | "branch" | "targetSync";
+    outcome: string;
+    reason: string | null;
+  }[];
+}
+
+function landingError(error: unknown): string {
+  const text = error instanceof Error ? error.message : String(error);
+  return redactSecrets(text).replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, " ").slice(0, MAX_SUMMARY_OUTPUT_CHARS);
+}
+
+function validateLandingInput(input: LandBranchInput): void {
+  for (const key of Object.keys(input)) {
+    if (!["sourceBranch", "targetBranch", "remote", "worktreePath", "pullRequestNumber"].includes(key)) {
+      throw new Error("land_branch accepts only sourceBranch, targetBranch, remote, worktreePath, and pullRequestNumber.");
+    }
+  }
+  for (const branch of [input.sourceBranch, input.targetBranch]) {
+    validateBranchNameInput(branch);
+    requireLosslessWorktreeIdentity(branch, "branch");
+    if (branch.startsWith("refs/") || branch.includes("@{")) {
+      throw new Error("land_branch requires exact local branch names, not full refs or revision expressions.");
+    }
+  }
+  if (input.sourceBranch === input.targetBranch) throw new Error("Source and target branches must be distinct.");
+  if (input.remote !== undefined) {
+    validateBranchNameInput(input.remote, "Remote");
+    requireLosslessWorktreeIdentity(input.remote, "branch");
+  }
+  if (input.worktreePath !== undefined) validateWorktreePathInput(input.worktreePath);
+  if (input.pullRequestNumber !== undefined && (!Number.isSafeInteger(input.pullRequestNumber) || input.pullRequestNumber <= 0)) {
+    throw new Error("pullRequestNumber must be a positive safe integer.");
+  }
+}
+
+// Reused Git helpers all receive explicit -C routing. Disable config-driven pruning,
+// extra fetch mappings and submodule recursion as well as command-line force options.
+async function executeLandingGit(
+  pi: GitAPI,
+  remote: string,
+  command: string,
+  args: string[],
+  options: Parameters<GitAPI["exec"]>[2],
+) {
+  if (!options?.cwd) throw new Error("Landing Git commands require an explicit working directory.");
+  let routedArgs = args;
+  if (args[0] === "fetch") {
+    routedArgs = ["fetch", "--no-prune", "--no-prune-tags", "--refmap=", ...args.slice(1)];
+  } else if (args[0] === "pull") {
+    routedArgs = [
+      "-c", "fetch.prune=false", "-c", "fetch.pruneTags=false",
+      "-c", `remote.${remote}.prune=false`, "-c", `remote.${remote}.pruneTags=false`,
+      "pull", "--no-tags", "--no-prune", "--refmap=", "--no-recurse-submodules", ...args.slice(1),
+    ];
+  }
+  return pi.exec(command, ["-C", options.cwd, ...routedArgs], options);
+}
+
+function newLandingReceipt(root: string, input: LandBranchInput): LandBranchReceipt {
+  return {
+    repositoryRoot: root,
+    remote: input.remote ?? "origin",
+    targetBranch: input.targetBranch,
+    remoteTargetHead: null,
+    sourceBranch: input.sourceBranch,
+    sourceHead: null,
+    ancestry: { isAncestor: null },
+    mergeProof: null,
+    pullRequest: null,
+    worktree: { path: null, outcome: "refused", reason: "Not attempted.", deletedIgnoredPaths: [] },
+    branch: { outcome: "refused", reason: "Not attempted.", expectedHead: null },
+    targetSync: { mode: "not-run", worktreePath: null, before: null, after: null, aheadBehind: null, reason: "Not attempted." },
+    steps: [{ step: "repository", outcome: "resolved", reason: null }],
+  };
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function registeredBranchEntries(inventory: Inventory, branch: string) {
+  return inventory.entries.filter((entry) => entry.record.branch === branch);
+}
+
+async function resolveLandingWorktree(
+  inventory: Inventory,
+  input: LandBranchInput,
+): Promise<string | null> {
+  if (input.worktreePath !== undefined) {
+    const path = await canonicalizePathAllowMissing(validateWorktreePathInput(input.worktreePath));
+    if (!path) throw new Error("worktreePath could not be resolved.");
+    return requireLosslessWorktreeIdentity(path, "cwd");
+  }
+  const entries = registeredBranchEntries(inventory, input.sourceBranch).filter((entry) => entry.index !== 0);
+  if (entries.length > 1) throw new Error("Source branch occupies multiple worktrees; provide an exact worktreePath.");
+  if (entries.length === 0) return null;
+  const path = entries[0].canonicalPath;
+  if (!path) throw new Error("Source worktree path could not be resolved.");
+  return requireLosslessWorktreeIdentity(path, "cwd");
+}
+
+async function requireSafeLandingCwd(cwd: string, worktreePath: string | null): Promise<void> {
+  if (worktreePath === null) return;
+  const callerCwd = await realpath(cwd);
+  const processCwd = await realpath(process.cwd());
+  if (pathIsInsideOrEqual(callerCwd, worktreePath) || pathIsInsideOrEqual(processCwd, worktreePath)) {
+    throw new Error("The running cwd is inside worktreePath; run from the repository root.");
+  }
+}
+
+async function captureLocalHead(pi: GitAPI, ctx: GitCommandContext, branch: string, signal?: AbortSignal) {
+  const ref = await inspectDirectLocalBranchRef(pi, ctx, branch, signal);
+  if (ref.status === "absent") return null;
+  const head = await getLocalBranchCommit(pi, ctx, branch, signal);
+  if (ref.objectId !== head) throw new Error("Local branch is not a direct ref to its captured commit.");
+  return head;
+}
+
+async function requireIdleWorktree(pi: GitAPI, ctx: GitCommandContext, signal?: AbortSignal): Promise<void> {
+  const state = await getGitOperationState(pi, ctx, signal);
+  if (state.active.length > 0) throw new Error("Worktree has an in-progress Git operation; it will not be touched.");
+}
+
+async function removeLandingWorktree(pi: GitAPI, receipt: LandBranchReceipt, signal?: AbortSignal): Promise<void> {
+  const worktree = receipt.worktree;
+  const ctx = { cwd: receipt.repositoryRoot };
+  const inventory = await collectWorktreeInventory(pi, ctx, signal);
+  if (worktree.path === null) {
+    if (registeredBranchEntries(inventory, receipt.sourceBranch).some((entry) => entry.index !== 0)) {
+      throw new Error("Source branch became occupied after preflight.");
+    }
+    worktree.outcome = "absent";
+    worktree.reason = null;
+    return;
+  }
+  const matches = inventory.entries.filter((entry) => entry.canonicalPath === worktree.path);
+  if (matches.some((entry) => entry.index === 0) || worktree.path === receipt.repositoryRoot) {
+    throw new Error("The primary checkout / repository root can never be removed.");
+  }
+  if (!(await pathExists(worktree.path))) {
+    worktree.outcome = "absent";
+    worktree.reason = matches.length > 0 ? "Directory absent; registration retained (no prune)." : null;
+    return;
+  }
+  const validated = await validateWorktreeRemovalPath(pi, ctx, worktree.path, signal);
+  if (![receipt.sourceBranch, receipt.targetBranch].includes(validated.worktree.branch ?? "")) {
+    throw new Error("The selected worktree must hold the source or target branch, not an unrelated branch.");
+  }
+  if (receipt.sourceHead === null) throw new Error("Source branch is absent; cannot prove this existing worktree is merged.");
+  const sourceHead = await captureLocalHead(pi, ctx, receipt.sourceBranch, signal);
+  if (sourceHead !== receipt.sourceHead) throw new Error("Source branch moved after the ancestry proof; no worktree removed.");
+  const worktreeHead = validated.worktree.head;
+  const exactMergedPrHead = receipt.mergeProof === "pull-request" &&
+    validated.worktree.branch === receipt.sourceBranch && worktreeHead === receipt.pullRequest?.headSha;
+  if (!worktreeHead || !receipt.remoteTargetHead ||
+      (!exactMergedPrHead && !(await isCommitAncestor(pi, ctx, worktreeHead, receipt.remoteTargetHead, signal)))) {
+    throw new Error("Selected worktree HEAD is not merged into the fetched target.");
+  }
+  await requireIdleWorktree(pi, { cwd: worktree.path }, signal);
+  const removed = await removeWorktreeWithinQueue(pi, ctx, worktree.path, signal, true, {
+    branch: validated.worktree.branch!, head: worktreeHead,
+  });
+  if (await pathExists(worktree.path)) throw new Error("Git unregistered the worktree but its directory is still present.");
+  worktree.outcome = "removed";
+  worktree.reason = null;
+  worktree.deletedIgnoredPaths = removed.deletedIgnoredPaths;
+}
+
+async function retireLandingBranch(pi: GitAPI, receipt: LandBranchReceipt, signal?: AbortSignal): Promise<void> {
+  const ctx = { cwd: receipt.repositoryRoot };
+  const head = await captureLocalHead(pi, ctx, receipt.sourceBranch, signal);
+  if (head === null) {
+    receipt.branch.outcome = "absent";
+    receipt.branch.reason = null;
+    return;
+  }
+  if (receipt.worktree.outcome === "refused") throw new Error("Worktree removal was refused; source branch retained.");
+  if (head !== receipt.sourceHead || receipt.remoteTargetHead === null) {
+    throw new Error("Source branch moved after the captured expected-HEAD lease; branch retained.");
+  }
+  await retireBranchWithinQueue(pi, ctx, {
+    branchName: receipt.sourceBranch,
+    expectedHead: head,
+    targetBranch: `${receipt.remote}/${receipt.targetBranch}`,
+    // A verified host merge authorizes retiring rewritten source history, not a
+    // general force option. Identity, occupancy, target stability and lease checks remain.
+    force: receipt.mergeProof === "pull-request" && receipt.pullRequest?.headSha === head,
+  }, ctx.cwd, signal, "remote-tracking", receipt.remoteTargetHead);
+  receipt.branch.outcome = "deleted";
+  receipt.branch.reason = null;
+}
+
+async function requireLandingPullPolicy(pi: GitAPI, ctx: GitCommandContext, branch: string, signal?: AbortSignal): Promise<void> {
+  const args = ["config", "--get-all", `branch.${branch}.mergeOptions`];
+  const result = await runGit(pi, ctx, args, { signal, allowFailure: true });
+  if (result.code === 1) return;
+  if (result.code !== 0) throw new Error(formatGitFailure(args, result));
+  if (result.stdout.trim()) {
+    throw new Error("Target has branch-specific mergeOptions; sync refused to preserve the fixed fast-forward policy.");
+  }
+}
+
+async function syncLandingTarget(pi: GitAPI, receipt: LandBranchReceipt, signal?: AbortSignal): Promise<void> {
+  const ctx = { cwd: receipt.repositoryRoot };
+  const sync = receipt.targetSync;
+  sync.before = await captureLocalHead(pi, ctx, receipt.targetBranch, signal);
+  if (sync.before === null) throw new Error("Local target branch is absent; landing will not create it.");
+  const inventory = await collectWorktreeInventory(pi, ctx, signal);
+  const entries = registeredBranchEntries(inventory, receipt.targetBranch);
+  if (entries.length > 1) throw new Error("Target branch is checked out in multiple worktrees; sync refused.");
+  if (entries.length === 1) {
+    sync.worktreePath = entries[0].canonicalPath;
+    if (!sync.worktreePath) throw new Error("Target worktree path could not be resolved.");
+    requireLosslessWorktreeIdentity(sync.worktreePath, "cwd");
+  }
+  if (sync.before === receipt.remoteTargetHead) {
+    sync.mode = "noop";
+    sync.reason = null;
+    return;
+  }
+  if (sync.worktreePath !== null) {
+    const targetCtx = { cwd: sync.worktreePath };
+    const root = await getCanonicalGitWorktreeRoot(pi, targetCtx, signal);
+    if (root !== sync.worktreePath ||
+        await getCanonicalCommonGitDirectory(pi, targetCtx, signal) !== await getCanonicalCommonGitDirectory(pi, ctx, signal) ||
+        (await getCurrentBranch(pi, targetCtx, signal)).currentBranch !== receipt.targetBranch) {
+      throw new Error("Target checkout identity changed; sync refused.");
+    }
+    const status = await getWorkingTreeStatus(pi, targetCtx, signal);
+    if (status.workingTree.state !== "clean") {
+      sync.mode = "skipped-dirty";
+      sync.reason = "Target checkout is dirty; no pull attempted.";
+      return;
+    }
+    await requireIdleWorktree(pi, targetCtx, signal);
+    await requireLandingPullPolicy(pi, targetCtx, receipt.targetBranch, signal);
+    await runGit(pi, targetCtx, ["pull", "--ff-only", "--no-rebase", "--no-autostash", receipt.remote, `refs/heads/${receipt.targetBranch}`], {
+      signal, timeout: GIT_PULL_TIMEOUT_MS,
+    });
+    sync.mode = "pull-ff";
+  } else {
+    await runGit(pi, ctx, ["fetch", "--no-tags", "--no-recurse-submodules", receipt.remote, `refs/heads/${receipt.targetBranch}:refs/heads/${receipt.targetBranch}`], {
+      signal, timeout: GIT_FETCH_TIMEOUT_MS,
+    });
+    sync.mode = "fetch-refspec";
+  }
+  sync.reason = null;
+}
+
+async function recordTargetAfter(pi: GitAPI, receipt: LandBranchReceipt): Promise<void> {
+  const ctx = { cwd: receipt.repositoryRoot };
+  const sync = receipt.targetSync;
+  sync.after = await captureLocalHead(pi, ctx, receipt.targetBranch);
+  if (sync.after !== null && receipt.remoteTargetHead !== null) {
+    sync.aheadBehind = await getAheadBehindCount(pi, ctx, undefined, `${sync.after}...${receipt.remoteTargetHead}`);
+  }
+  if (["fetch-refspec", "pull-ff"].includes(sync.mode)) {
+    if (sync.before === null || sync.after === null ||
+        !(await isCommitAncestor(pi, ctx, sync.before, sync.after)) ||
+        receipt.remoteTargetHead === null || !(await isCommitAncestor(pi, ctx, receipt.remoteTargetHead, sync.after)) ||
+        (sync.after === sync.before && sync.before !== receipt.remoteTargetHead)) {
+      throw new Error("Git did not produce a verified target fast-forward; inspect the recorded before/after refs.");
+    }
+  } else if (["noop", "skipped-dirty"].includes(sync.mode) && sync.before !== sync.after) {
+    throw new Error("Target ref moved concurrently during a read-only sync decision.");
+  }
+}
+
+async function finishLandingSync(pi: GitAPI, receipt: LandBranchReceipt, signal?: AbortSignal): Promise<void> {
+  try {
+    await syncLandingTarget(pi, receipt, signal);
+  } catch (error) {
+    receipt.targetSync.mode = "failed";
+    receipt.targetSync.reason = landingError(error);
+  }
+  try {
+    // Verification is deliberately uncancelled after a possible mutation.
+    await recordTargetAfter(pi, receipt);
+  } catch (error) {
+    receipt.targetSync.mode = "failed";
+    receipt.targetSync.reason = landingError(error);
+  }
+  receipt.steps.push({ step: "targetSync", outcome: receipt.targetSync.mode, reason: receipt.targetSync.reason });
+}
+
+async function refuseLanding(pi: GitAPI, receipt: LandBranchReceipt, error: unknown): Promise<LandBranchReceipt> {
+  const reason = landingError(error);
+  receipt.worktree.reason = reason;
+  receipt.branch.reason = reason;
+  receipt.targetSync.reason = reason;
+  try {
+    receipt.targetSync.before ??= await captureLocalHead(pi, { cwd: receipt.repositoryRoot }, receipt.targetBranch);
+    await recordTargetAfter(pi, receipt);
+  } catch (verificationError) {
+    receipt.targetSync.reason = `${reason} Verification: ${landingError(verificationError)}`;
+  }
+  const recorded = new Set(receipt.steps.map((step) => step.step));
+  for (const step of ["cwd", "fetch", "ancestry", "worktree", "branch", "targetSync"] as const) {
+    if (!recorded.has(step)) receipt.steps.push({ step, outcome: "not-run", reason });
+  }
+  return receipt;
+}
+
+async function verifyLandingPullRequest(
+  pi: GitAPI,
+  ctx: GitCommandContext,
+  receipt: LandBranchReceipt,
+  number: number,
+  options: RelatedPullRequestLookupOptions,
+  signal?: AbortSignal,
+): Promise<void> {
+  const repository = await resolveGitHubRepository(pi, ctx, signal, options.env);
+  const remoteUrl = await runGit(pi, ctx, ["remote", "get-url", receipt.remote], { signal });
+  const remoteRepository = parseGitHubRepository(remoteUrl.stdout.trim());
+  if (!remoteRepository || !repositoriesEqual(repository, remoteRepository)) {
+    throw new Error("Landing remote does not match the GitHub repository used for PR evidence.");
+  }
+  const token = (await resolveGitHubToken(options.env, { cwd: ctx.cwd, signal })).token;
+  const pr = await getGitHubPullRequest(repository, number, token, { fetchImpl: options.fetchImpl, signal });
+  if (!pr.merged || pr.state !== "closed" || !pr.mergeCommitSha || pr.head !== receipt.sourceBranch ||
+      pr.base !== receipt.targetBranch || (receipt.sourceHead !== null && pr.headSha !== receipt.sourceHead)) {
+    throw new Error("PR merge evidence does not match the exact source commit and target branch; landing refused.");
+  }
+  if (!receipt.remoteTargetHead || !(await isCommitAncestor(pi, ctx, pr.mergeCommitSha, receipt.remoteTargetHead, signal))) {
+    throw new Error("The PR merge commit is not contained in the fetched remote target; landing refused.");
+  }
+  receipt.pullRequest = { number: pr.number, headSha: pr.headSha, mergeCommitSha: pr.mergeCommitSha };
+  receipt.mergeProof = "pull-request";
+}
+
+async function landBranchWithinQueue(
+  pi: GitAPI,
+  cwd: string,
+  root: string,
+  input: LandBranchInput,
+  signal: AbortSignal | undefined,
+  options: RelatedPullRequestLookupOptions,
+): Promise<LandBranchReceipt> {
+  const ctx = { cwd: root };
+  const receipt = newLandingReceipt(root, input);
+  let step: "cwd" | "fetch" | "ancestry" = "cwd";
+  try {
+    const inventory = await collectWorktreeInventory(pi, ctx, signal);
+    receipt.worktree.path = await resolveLandingWorktree(inventory, input);
+    await requireSafeLandingCwd(cwd, receipt.worktree.path);
+    receipt.steps.push({ step: "cwd", outcome: "safe", reason: null });
+    step = "fetch";
+    await validateBranchName(pi, ctx, input.sourceBranch, signal);
+    await validateBranchName(pi, ctx, input.targetBranch, signal);
+    receipt.sourceHead = await captureLocalHead(pi, ctx, input.sourceBranch, signal);
+    receipt.branch.expectedHead = receipt.sourceHead;
+    receipt.targetSync.before = await captureLocalHead(pi, ctx, input.targetBranch, signal);
+    if (receipt.targetSync.before === null) throw new Error("Local target branch does not exist.");
+    const tracking = `${receipt.remote}/${receipt.targetBranch}`;
+    await inspectDirectRemoteTrackingRef(pi, ctx, tracking, signal);
+    await fetchRemoteBranchWithinQueue(pi, ctx, receipt.remote, receipt.targetBranch, signal);
+    const ref = await inspectDirectRemoteTrackingRef(pi, ctx, tracking, signal);
+    receipt.remoteTargetHead = await getRemoteTrackingRefCommit(pi, ctx, tracking, signal);
+    if (ref.status !== "present" || ref.objectId !== receipt.remoteTargetHead) {
+      throw new Error("Fetched target is not a direct ref to its captured commit.");
+    }
+    receipt.steps.push({ step: "fetch", outcome: "fetched", reason: null });
+    step = "ancestry";
+    if (receipt.sourceHead !== null) {
+      receipt.ancestry.isAncestor = await isCommitAncestor(pi, ctx, receipt.sourceHead, receipt.remoteTargetHead, signal);
+    }
+    if (input.pullRequestNumber !== undefined) {
+      await verifyLandingPullRequest(pi, ctx, receipt, input.pullRequestNumber, options, signal);
+    } else if (receipt.ancestry.isAncestor === false) {
+      throw new Error("Source branch is not merged into the fetched remote target; landing refused. For a squash/rebase merge, supply pullRequestNumber for verified host evidence.");
+    } else if (receipt.ancestry.isAncestor) {
+      receipt.mergeProof = "ancestry";
+    }
+    let ancestryOutcome = "verified";
+    if (receipt.mergeProof === "pull-request") ancestryOutcome = "pr-verified";
+    else if (receipt.sourceHead === null) ancestryOutcome = "absent";
+    receipt.steps.push({ step: "ancestry", outcome: ancestryOutcome, reason: null });
+  } catch (error) {
+    receipt.steps.push({ step, outcome: "refused", reason: landingError(error) });
+    return refuseLanding(pi, receipt, error);
+  }
+  try {
+    await removeLandingWorktree(pi, receipt, signal);
+  } catch (error) {
+    receipt.worktree.reason = landingError(error);
+  }
+  receipt.steps.push({ step: "worktree", outcome: receipt.worktree.outcome, reason: receipt.worktree.reason });
+  try {
+    await retireLandingBranch(pi, receipt, signal);
+  } catch (error) {
+    receipt.branch.reason = landingError(error);
+  }
+  receipt.steps.push({ step: "branch", outcome: receipt.branch.outcome, reason: receipt.branch.reason });
+  await finishLandingSync(pi, receipt, signal);
+  return receipt;
+}
+
+export async function landBranch(pi: GitAPI, ctx: GitCommandContext, input: LandBranchInput, signal?: AbortSignal, options: RelatedPullRequestLookupOptions = {}): Promise<LandBranchReceipt> {
+  validateLandingInput(input);
+  const routedPi: GitAPI = { exec: executeLandingGit.bind(undefined, pi, input.remote ?? "origin") };
+  const callerRoot = await getCanonicalGitWorktreeRoot(routedPi, ctx, signal);
+  const inventory = await collectWorktreeInventory(routedPi, { cwd: callerRoot }, signal);
+  const primary = inventory.entries[0];
+  if (!primary?.canonicalPath || primary.record.bare) throw new Error("Landing requires a primary non-bare checkout.");
+  const root = await getCanonicalGitWorktreeRoot(routedPi, { cwd: primary.canonicalPath }, signal);
+  requireLosslessWorktreeIdentity(root, "cwd");
+  if (root !== primary.canonicalPath ||
+      await getCanonicalCommonGitDirectory(routedPi, { cwd: root }, signal) !== await getCanonicalCommonGitDirectory(routedPi, { cwd: callerRoot }, signal)) {
+    throw new Error("Primary checkout repository identity could not be verified.");
+  }
+  return withRepositoryMutationQueue(root, landBranchWithinQueue.bind(undefined, routedPi, ctx.cwd, root, input, signal, options));
+}
+
+export function formatLandBranch(receipt: LandBranchReceipt): string {
+  const proof = receipt.pullRequest ? ` Verified merged PR #${receipt.pullRequest.number}; source ancestry: ${receipt.ancestry.isAncestor ?? "unknown"}.` : "";
+  const summary = `land_branch: worktree ${receipt.worktree.outcome}; branch ${receipt.branch.outcome}; target sync ${receipt.targetSync.mode}.${proof}`;
+  const reason = receipt.worktree.reason ?? receipt.branch.reason ?? receipt.targetSync.reason;
+  return reason ? `${summary} ${landingError(reason)}` : summary;
+}