@senad-d/branchme 0.3.0 → 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,6 +13,7 @@ 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";
@@ -19,6 +24,10 @@ 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,
@@ -29,6 +38,7 @@ export const BRANCHME_TOOL_NAMES = [
   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,
@@ -51,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

@@ -30,6 +30,7 @@ import {
 } 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">;
@@ -40,6 +41,7 @@ export interface LandBranchInput {
   targetBranch: string;
   remote?: string;
   worktreePath?: string;
+  pullRequestNumber?: number;
 }
 
 export interface LandBranchReceipt {
@@ -50,6 +52,8 @@ export interface LandBranchReceipt {
   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";
@@ -83,8 +87,8 @@ function landingError(error: unknown): string {
 
 function validateLandingInput(input: LandBranchInput): void {
   for (const key of Object.keys(input)) {
-    if (!["sourceBranch", "targetBranch", "remote", "worktreePath"].includes(key)) {
-      throw new Error("land_branch accepts only sourceBranch, targetBranch, remote, and worktreePath.");
+    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]) {
@@ -100,6 +104,9 @@ function validateLandingInput(input: LandBranchInput): void {
     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,
@@ -134,6 +141,8 @@ function newLandingReceipt(root: string, input: LandBranchInput): LandBranchRece
     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." },
@@ -223,8 +232,10 @@ async function removeLandingWorktree(pi: GitAPI, receipt: LandBranchReceipt, sig
   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 ||
-      !(await isCommitAncestor(pi, ctx, worktreeHead, receipt.remoteTargetHead, signal))) {
+      (!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);
@@ -253,7 +264,9 @@ async function retireLandingBranch(pi: GitAPI, receipt: LandBranchReceipt, signa
     branchName: receipt.sourceBranch,
     expectedHead: head,
     targetBranch: `${receipt.remote}/${receipt.targetBranch}`,
-    force: false,
+    // 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;
@@ -370,12 +383,40 @@ async function refuseLanding(pi: GitAPI, receipt: LandBranchReceipt, error: unkn
   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,
+  signal: AbortSignal | undefined,
+  options: RelatedPullRequestLookupOptions,
 ): Promise<LandBranchReceipt> {
   const ctx = { cwd: root };
   const receipt = newLandingReceipt(root, input);
@@ -392,8 +433,9 @@ async function landBranchWithinQueue(
     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.");
-    await fetchRemoteBranchWithinQueue(pi, ctx, receipt.remote, receipt.targetBranch, signal);
     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) {
@@ -403,9 +445,18 @@ async function landBranchWithinQueue(
     step = "ancestry";
     if (receipt.sourceHead !== null) {
       receipt.ancestry.isAncestor = await isCommitAncestor(pi, ctx, receipt.sourceHead, receipt.remoteTargetHead, signal);
-      if (!receipt.ancestry.isAncestor) throw new Error("Source branch is not merged into the fetched remote target; landing refused.");
     }
-    receipt.steps.push({ step: "ancestry", outcome: receipt.sourceHead === null ? "absent" : "verified", reason: null });
+    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);
@@ -426,7 +477,7 @@ async function landBranchWithinQueue(
   return receipt;
 }
 
-export async function landBranch(pi: GitAPI, ctx: GitCommandContext, input: LandBranchInput, signal?: AbortSignal): Promise<LandBranchReceipt> {
+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);
@@ -439,11 +490,12 @@ export async function landBranch(pi: GitAPI, ctx: GitCommandContext, input: Land
       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));
+  return withRepositoryMutationQueue(root, landBranchWithinQueue.bind(undefined, routedPi, ctx.cwd, root, input, signal, options));
 }
 
 export function formatLandBranch(receipt: LandBranchReceipt): string {
-  const summary = `land_branch: worktree ${receipt.worktree.outcome}; branch ${receipt.branch.outcome}; target sync ${receipt.targetSync.mode}.`;
+  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;
 }

package/src/git-workflow.ts

@@ -0,0 +1,136 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { GIT_MUTATION_TIMEOUT_MS } from "./constants.ts";
+import { integrateBranchWithinQueue } from "./git-integration.ts";
+import {
+  fetchRemoteBranchWithinQueue, getCanonicalGitWorktreeRoot, getCurrentBranch,
+  getGitOperationState, getLocalBranchCommit, getRemoteTrackingRefCommit, getUpstreamBranch,
+  getWorkingTreeStatus, inspectDirectRemoteTrackingRef, localBranchExists,
+  requireLosslessWorktreeIdentity, runGit, validateBranchName, withRepositoryMutationQueue,
+  type GitCommandContext,
+} from "./git.ts";
+
+export interface TrackBranchInput {
+  branchName: string;
+  remote?: string;
+  remoteBranch?: string;
+}
+
+export interface TrackBranchDetails {
+  action: "track_branch";
+  branchName: string;
+  previousBranch: string | null;
+  head: string;
+  upstream: string;
+  repoRoot: string;
+}
+
+type GitAPI = Pick<ExtensionAPI, "exec">;
+
+async function executeNarrowFetch(pi: GitAPI, command: string, args: string[], options: Parameters<GitAPI["exec"]>[2]) {
+  const safeArgs = args[0] === "fetch" ? ["fetch", "--no-prune", "--no-prune-tags", "--refmap=", ...args.slice(1)] : args;
+  return pi.exec(command, safeArgs, options);
+}
+
+export async function fetchWorkflowBase(pi: GitAPI, ctx: GitCommandContext, remote: string, branch: string, signal?: AbortSignal): Promise<void> {
+  // Fetch dereferences a symbolic destination, potentially updating a local branch.
+  // Reject it before fetching, not only when inspecting the fetched commit.
+  await inspectDirectRemoteTrackingRef(pi, ctx, `${remote}/${branch}`, signal);
+  const scopedPi: GitAPI = { exec: executeNarrowFetch.bind(undefined, pi) };
+  await fetchRemoteBranchWithinQueue(scopedPi, ctx, remote, branch, signal);
+}
+
+export async function requireCleanIdleCheckout(pi: GitAPI, ctx: GitCommandContext, signal?: AbortSignal): Promise<void> {
+  if ((await getGitOperationState(pi, ctx, signal)).active.length > 0) {
+    throw new Error("An in-progress Git operation must be completed or aborted first.");
+  }
+  if ((await getWorkingTreeStatus(pi, ctx, signal)).workingTree.state !== "clean") {
+    throw new Error("The working tree must be clean before this operation.");
+  }
+}
+
+async function trackBranchWithinQueue(pi: GitAPI, ctx: GitCommandContext, input: TrackBranchInput, signal?: AbortSignal): Promise<TrackBranchDetails> {
+  const remote = input.remote ?? "origin";
+  const remoteBranch = input.remoteBranch ?? input.branchName;
+  requireLosslessWorktreeIdentity(input.branchName, "branch");
+  requireLosslessWorktreeIdentity(remote, "branch");
+  requireLosslessWorktreeIdentity(remoteBranch, "branch");
+  await validateBranchName(pi, ctx, input.branchName, signal);
+  await validateBranchName(pi, ctx, remoteBranch, signal);
+  if (input.branchName.startsWith("refs/") || remoteBranch.startsWith("refs/")) {
+    throw new Error("track_branch requires branch names, not full refs.");
+  }
+  if (await localBranchExists(pi, ctx, input.branchName, signal)) throw new Error("Local branch already exists; use change_branch.");
+  await requireCleanIdleCheckout(pi, ctx, signal);
+  const previous = await getCurrentBranch(pi, ctx, signal);
+  if (previous.currentBranch !== null) requireLosslessWorktreeIdentity(previous.currentBranch, "branch");
+  await fetchWorkflowBase(pi, ctx, remote, remoteBranch, signal);
+  const upstream = `${remote}/${remoteBranch}`;
+  const ref = await inspectDirectRemoteTrackingRef(pi, ctx, upstream, signal);
+  const head = await getRemoteTrackingRefCommit(pi, ctx, upstream, signal);
+  if (ref.status !== "present" || ref.objectId !== head) throw new Error("Fetched branch is not a direct remote-tracking commit ref.");
+  await requireCleanIdleCheckout(pi, ctx, signal);
+  try {
+    await runGit(pi, ctx, ["switch", "--no-overwrite-ignore", "--track=direct", "-c", input.branchName, `refs/remotes/${upstream}`], {
+      signal, timeout: GIT_MUTATION_TIMEOUT_MS,
+    });
+    if ((await getCurrentBranch(pi, ctx)).currentBranch !== input.branchName ||
+        await getLocalBranchCommit(pi, ctx, input.branchName) !== head ||
+        await getUpstreamBranch(pi, ctx) !== upstream) {
+      throw new Error("Branch, commit, or configured upstream did not match the captured remote branch.");
+    }
+    await requireCleanIdleCheckout(pi, ctx);
+  } catch {
+    throw new Error("Tracking checkout did not complete with verified postconditions; inspect the repository before retrying. No automatic rollback was attempted.");
+  }
+  return { action: "track_branch", repoRoot: ctx.cwd, branchName: input.branchName, previousBranch: previous.currentBranch, head, upstream };
+}
+
+export interface UpdateFromBaseInput {
+  baseBranch: string;
+  remote?: string;
+}
+
+async function captureUpstreamConfiguration(pi: GitAPI, ctx: GitCommandContext, branch: string, signal?: AbortSignal): Promise<string> {
+  const values: string[] = [];
+  for (const key of ["remote", "merge"]) {
+    const result = await runGit(pi, ctx, ["config", "--null", "--get-all", `branch.${branch}.${key}`], { signal, allowFailure: true });
+    if (result.code !== 0 && (result.code !== 1 || result.stdout || result.stderr)) {
+      throw new Error("Unable to inspect upstream configuration.");
+    }
+    values.push(result.stdout);
+  }
+  return JSON.stringify(values);
+}
+
+async function updateFromBaseWithinQueue(pi: GitAPI, ctx: GitCommandContext, input: UpdateFromBaseInput, signal?: AbortSignal) {
+  const remote = input.remote ?? "origin";
+  requireLosslessWorktreeIdentity(remote, "branch");
+  requireLosslessWorktreeIdentity(input.baseBranch, "branch");
+  await validateBranchName(pi, ctx, input.baseBranch, signal);
+  await requireCleanIdleCheckout(pi, ctx, signal);
+  const current = await getCurrentBranch(pi, ctx, signal);
+  if (!current.currentBranch || current.detached) throw new Error("update_from_base requires a current local branch.");
+  if (current.currentBranch === input.baseBranch) throw new Error("Use pull_branch for the base branch itself.");
+  requireLosslessWorktreeIdentity(current.currentBranch, "branch");
+  const upstreamBefore = await captureUpstreamConfiguration(pi, ctx, current.currentBranch, signal);
+  await fetchWorkflowBase(pi, ctx, remote, input.baseBranch, signal);
+  const integration = await integrateBranchWithinQueue(pi, ctx, {
+    sourceBranch: `${remote}/${input.baseBranch}`, targetBranch: current.currentBranch,
+  }, ctx.cwd, signal, true);
+  if (await captureUpstreamConfiguration(pi, ctx, current.currentBranch) !== upstreamBefore) {
+    throw new Error("Upstream configuration changed during update; inspect the repository before retrying.");
+  }
+  return { action: "update_from_base" as const, request: input, status: integration.status, integration };
+}
+
+export async function updateFromBase(pi: GitAPI, ctx: GitCommandContext, input: UpdateFromBaseInput, signal?: AbortSignal) {
+  const root = await getCanonicalGitWorktreeRoot(pi, ctx, signal);
+  requireLosslessWorktreeIdentity(root, "cwd");
+  return withRepositoryMutationQueue(root, updateFromBaseWithinQueue.bind(undefined, pi, { cwd: root }, input, signal));
+}
+
+export async function trackBranch(pi: GitAPI, ctx: GitCommandContext, input: TrackBranchInput, signal?: AbortSignal): Promise<TrackBranchDetails> {
+  const root = await getCanonicalGitWorktreeRoot(pi, ctx, signal);
+  requireLosslessWorktreeIdentity(root, "cwd");
+  return withRepositoryMutationQueue(root, trackBranchWithinQueue.bind(undefined, pi, { cwd: root }, input, signal));
+}