@senad-d/branchme 0.1.8 → 0.2.0

package/src/git.ts

@@ -24,6 +24,8 @@ import {
 import { redactSecrets } from "./redaction.ts";
 import type {
   AheadBehindCount,
+  BranchAncestryDetails,
+  BranchStatusAncestryQuery,
   BranchStatusDetails,
   ChangeBranchDetails,
   CreateBranchDetails,
@@ -157,6 +159,23 @@ export async function getGitRoot(
   return root;
 }
 
+export async function getCanonicalGitWorktreeRoot(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  signal?: AbortSignal,
+): Promise<string> {
+  const repoRoot = await getGitRoot(pi, ctx, signal);
+  if (!isAbsolute(repoRoot) || /[\p{Cc}\p{Cf}\u2028\u2029]/u.test(repoRoot)) {
+    throw new Error("Unable to verify the active worktree root: Git returned an invalid path.");
+  }
+
+  try {
+    return await realpath(repoRoot);
+  } catch {
+    throw new Error("Unable to verify the active worktree root: the path could not be resolved.");
+  }
+}
+
 export async function getCurrentBranch(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -610,6 +629,30 @@ export function parseWorktreePorcelain(output: string): Pick<ListWorktreesDetail
   return { worktrees, omitted: records.length - returnedCount };
 }
 
+export interface LocalBranchWorktreeOccupancy {
+  branchName: string;
+  completeInventoryInspected: true;
+  occupied: boolean;
+  matchingWorktreeCount: number;
+}
+
+export interface PresentDirectLocalBranchRef {
+  status: "present";
+  branchName: string;
+  fullRef: string;
+  objectId: string;
+}
+
+export interface AbsentDirectLocalBranchRef {
+  status: "absent";
+  branchName: string;
+  fullRef: string;
+}
+
+export type DirectLocalBranchRefInspection =
+  | PresentDirectLocalBranchRef
+  | AbsentDirectLocalBranchRef;
+
 interface WorktreeInventoryEntry {
   record: ParsedWorktreeRecord;
   index: number;
@@ -667,12 +710,16 @@ function safeWorktreeBranchLabel(branchName: string): string {
   return JSON.stringify(safeWorktreeValue(branchName, GIT_CONTEXT_VALUE_LIMIT_CHARS));
 }
 
+export function isLosslessGitMetadata(value: string, limit: number): boolean {
+  return safeWorktreeValue(value, limit) === value;
+}
+
 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;
+  if (isLosslessGitMetadata(value, limit)) return value;
 
   const label = identity === "cwd" ? "canonical worktree path" : "local branch name";
   throw new Error(
@@ -775,13 +822,13 @@ function stripSingleLineTerminator(value: string): string {
   return value;
 }
 
-async function getCommonGitDirectory(
+export async function getCanonicalCommonGitDirectory(
   pi: Pick<ExtensionAPI, "exec">,
-  repoRoot: string,
+  ctx: GitCommandContext,
   signal?: AbortSignal,
 ): Promise<string> {
   const args = ["rev-parse", "--path-format=absolute", "--git-common-dir"];
-  const result = await runGit(pi, { cwd: repoRoot }, args, {
+  const result = await runGit(pi, ctx, args, {
     signal,
     timeout: GIT_STATUS_TIMEOUT_MS,
   });
@@ -791,14 +838,77 @@ async function getCommonGitDirectory(
     !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.");
+    throw new Error("Unable to verify repository identity: 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.");
+    throw new Error("Unable to verify repository identity: the common Git directory could not be resolved.");
+  }
+}
+
+export type GitOperationKind = "merge" | "rebase" | "cherry-pick" | "revert" | "sequencer";
+
+export interface GitOperationState {
+  active: GitOperationKind[];
+  mergeHeadPresent: boolean;
+  autoMergePresent: boolean;
+}
+
+const GIT_OPERATION_MARKERS: ReadonlyArray<readonly [path: string, operation: GitOperationKind]> = [
+  ["MERGE_HEAD", "merge"],
+  ["AUTO_MERGE", "merge"],
+  ["rebase-merge", "rebase"],
+  ["rebase-apply", "rebase"],
+  ["CHERRY_PICK_HEAD", "cherry-pick"],
+  ["REVERT_HEAD", "revert"],
+  ["sequencer", "sequencer"],
+];
+
+async function gitOperationMarkerExists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (isMissingFilesystemPath(error)) return false;
+    throw new Error("Unable to inspect repository operation state: a Git state path could not be inspected.");
+  }
+}
+
+export async function getGitOperationState(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  signal?: AbortSignal,
+): Promise<GitOperationState> {
+  const args = ["rev-parse", "--path-format=absolute"];
+  for (const [path] of GIT_OPERATION_MARKERS) args.push("--git-path", path);
+  const result = await runGit(pi, ctx, args, {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+  });
+  const paths = stripSingleLineTerminator(result.stdout).split(/\r?\n/u);
+  if (
+    paths.length !== GIT_OPERATION_MARKERS.length ||
+    paths.some((path) => !isAbsolute(path) || /[\p{Cc}\p{Cf}\u2028\u2029]/u.test(path))
+  ) {
+    throw new Error("Unable to inspect repository operation state: Git returned invalid state paths.");
   }
+
+  const active: GitOperationKind[] = [];
+  const presentMarkers: boolean[] = [];
+  for (const [index, path] of paths.entries()) {
+    const present = await gitOperationMarkerExists(path);
+    presentMarkers.push(present);
+    if (!present) continue;
+    const operation = GIT_OPERATION_MARKERS[index][1];
+    if (!active.includes(operation)) active.push(operation);
+  }
+  return {
+    active,
+    mergeHeadPresent: presentMarkers[0] === true,
+    autoMergePresent: presentMarkers[1] === true,
+  };
 }
 
 async function prepareWorktreeCreation(
@@ -820,7 +930,11 @@ async function prepareWorktreeCreation(
     }
   }
 
-  const commonGitDir = await getCommonGitDirectory(pi, inventory.repoRoot, signal);
+  const commonGitDir = await getCanonicalCommonGitDirectory(
+    pi,
+    { cwd: inventory.repoRoot },
+    signal,
+  );
   if (pathIsInsideOrEqual(canonicalPath, commonGitDir)) {
     throw new Error("worktreePath destination cannot be inside the repository common Git directory.");
   }
@@ -908,6 +1022,33 @@ export async function listWorktrees(
   };
 }
 
+export async function inspectLocalBranchWorktreeOccupancy(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  branchName: string,
+  signal?: AbortSignal,
+): Promise<LocalBranchWorktreeOccupancy> {
+  validateBranchNameInput(branchName);
+  requireLosslessWorktreeIdentity(branchName, "branch");
+  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);
+  let matchingWorktreeCount = 0;
+  for (const record of records) {
+    if (record.branch === branchName) matchingWorktreeCount += 1;
+  }
+  return {
+    branchName,
+    completeInventoryInspected: true,
+    occupied: matchingWorktreeCount > 0,
+    matchingWorktreeCount,
+  };
+}
+
 function validateCreateWorktreeMode(branchMode: unknown): asserts branchMode is CreateWorktreeMode {
   if (branchMode !== "new" && branchMode !== "existing") {
     throw new Error("branchMode must be either 'new' or 'existing'.");
@@ -1746,6 +1887,113 @@ export async function localBranchExists(
   return result.code === 0;
 }
 
+function requireLosslessLocalRef(branchName: string): string {
+  requireLosslessWorktreeIdentity(branchName, "branch");
+  const fullRef = `refs/heads/${branchName}`;
+  if (!isLosslessGitMetadata(fullRef, GIT_CONTEXT_VALUE_LIMIT_CHARS)) {
+    throw new Error(
+      "The full local branch ref cannot be returned safely and losslessly. " +
+      `Use a branch name short enough to keep the full ref within ${GIT_CONTEXT_VALUE_LIMIT_CHARS} characters.`,
+    );
+  }
+  return fullRef;
+}
+
+interface ExactLocalRefListing {
+  exactObjectId: string | null;
+  exactRefFound: boolean;
+}
+
+function parseExactLocalRefListing(
+  branchName: string,
+  fullRef: string,
+  output: string,
+): ExactLocalRefListing {
+  const row = stripSingleLineTerminator(output);
+  if (!row) return { exactObjectId: null, exactRefFound: false };
+
+  const fields = row.split(NUL_SEPARATOR);
+  if (fields.length !== 2 || !fields[0] || !fields[1]) {
+    throw new Error(
+      `Unable to inspect local branch ${safeWorktreeBranchLabel(branchName)}: ` +
+      "Git returned a malformed exact-ref listing.",
+    );
+  }
+  const [observedRef, objectId] = fields;
+  if (observedRef !== fullRef) {
+    if (observedRef.startsWith(`${fullRef}/`)) {
+      return { exactObjectId: null, exactRefFound: false };
+    }
+    throw new Error(
+      `Unable to inspect local branch ${safeWorktreeBranchLabel(branchName)}: ` +
+      "Git returned a different ref identity for the requested exact local branch.",
+    );
+  }
+  if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu.test(objectId)) {
+    throw new Error(
+      `Unable to inspect local branch ${safeWorktreeBranchLabel(branchName)}: ` +
+      "Git returned a malformed full object identity.",
+    );
+  }
+  return { exactObjectId: objectId, exactRefFound: true };
+}
+
+async function rejectSymbolicLocalBranchRef(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  branchName: string,
+  fullRef: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  const symbolicRefArgs = ["symbolic-ref", "--quiet", fullRef];
+  const symbolicRef = await runGit(pi, ctx, symbolicRefArgs, {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+    allowFailure: true,
+  });
+  if (symbolicRef.code === 0) {
+    throw new Error(
+      `Local branch ${safeWorktreeBranchLabel(branchName)} is symbolic; ` +
+      "retirement requires a verified direct local branch ref.",
+    );
+  }
+  if (symbolicRef.code !== 1 || symbolicRef.stdout.length > 0 || symbolicRef.stderr.length > 0) {
+    throw new Error(formatGitFailure(symbolicRefArgs, symbolicRef));
+  }
+}
+
+export async function inspectDirectLocalBranchRef(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  branchName: string,
+  signal?: AbortSignal,
+): Promise<DirectLocalBranchRefInspection> {
+  validateBranchNameInput(branchName);
+  const fullRef = requireLosslessLocalRef(branchName);
+  const listArgs = [
+    "for-each-ref",
+    "--count=1",
+    "--sort=refname",
+    "--format=%(refname)%00%(objectname)",
+    fullRef,
+  ];
+  const listing = await runGit(pi, ctx, listArgs, {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+  });
+  const parsed = parseExactLocalRefListing(branchName, fullRef, listing.stdout);
+  await rejectSymbolicLocalBranchRef(pi, ctx, branchName, fullRef, signal);
+  if (!parsed.exactRefFound || parsed.exactObjectId === null) {
+    return { status: "absent", branchName, fullRef };
+  }
+  return {
+    status: "present",
+    branchName,
+    fullRef,
+    objectId: parsed.exactObjectId,
+  };
+}
+
 export async function getLocalBranchCommit(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -1764,6 +2012,64 @@ export async function getLocalBranchCommit(
   return commit;
 }
 
+export async function requireExistingLocalBranch(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  branchName: string,
+  label: "Source" | "Target",
+  signal?: AbortSignal,
+): Promise<void> {
+  if (await localBranchExists(pi, ctx, branchName, signal)) return;
+  throw new Error(`${label} local branch '${safeGitContextValue(branchName)}' does not exist.`);
+}
+
+export async function isCommitAncestor(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  ancestorCommit: string,
+  descendantCommit: string,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  if (!/^[0-9a-f]{40,64}$/iu.test(ancestorCommit) || !/^[0-9a-f]{40,64}$/iu.test(descendantCommit)) {
+    throw new Error("Ancestry verification requires two valid full commit identities.");
+  }
+
+  const args = ["merge-base", "--is-ancestor", ancestorCommit, descendantCommit];
+  const result = await runGit(pi, ctx, args, {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+    allowFailure: true,
+  });
+  if (result.code !== 0 && result.code !== 1) throw new Error(formatGitFailure(args, result));
+  return result.code === 0;
+}
+
+export async function getLocalBranchAncestry(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  query: BranchStatusAncestryQuery,
+  signal?: AbortSignal,
+): Promise<BranchAncestryDetails> {
+  validateBranchNameInput(query.sourceBranch, "Source branch");
+  validateBranchNameInput(query.targetBranch, "Target branch");
+  await validateBranchName(pi, ctx, query.sourceBranch, signal);
+  await validateBranchName(pi, ctx, query.targetBranch, signal);
+  await requireExistingLocalBranch(pi, ctx, query.sourceBranch, "Source", signal);
+  await requireExistingLocalBranch(pi, ctx, query.targetBranch, "Target", signal);
+
+  const sourceHead = await getLocalBranchCommit(pi, ctx, query.sourceBranch, signal);
+  const targetHead = await getLocalBranchCommit(pi, ctx, query.targetBranch, signal);
+  const isAncestor = await isCommitAncestor(pi, ctx, sourceHead, targetHead, signal);
+
+  return {
+    sourceBranch: query.sourceBranch,
+    targetBranch: query.targetBranch,
+    sourceHead,
+    targetHead,
+    isAncestor,
+  };
+}
+
 export async function createLocalBranch(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,

package/src/tools/branchme-tools.ts

@@ -7,13 +7,17 @@ import {
   CREATE_BRANCH_TOOL_NAME,
   CREATE_WORKTREE_TOOL_NAME,
   FETCH_BRANCH_TOOL_NAME,
+  GIT_INTEGRATION_SUMMARY_LIMIT_CHARS,
+  GIT_RETIREMENT_SUMMARY_LIMIT_CHARS,
   GIT_WORKTREE_SUMMARY_LIMIT_CHARS,
+  INTEGRATE_BRANCH_TOOL_NAME,
   LIST_WORKTREES_TOOL_NAME,
   PULL_BRANCH_TOOL_NAME,
   PULL_REQUEST_TOOL_NAME,
   PUSH_BRANCH_TOOL_NAME,
   REBASE_BRANCH_TOOL_NAME,
   REMOVE_WORKTREE_TOOL_NAME,
+  RETIRE_BRANCH_TOOL_NAME,
 } from "../constants.ts";
 import {
   changeExistingLocalBranch,
@@ -35,6 +39,8 @@ import {
   withRepositoryMutationQueue,
 } from "../git.ts";
 import { collectGitContext, formatGitContext } from "../git-context.ts";
+import { integrateBranch } from "../git-integration.ts";
+import { retireBranch } from "../git-retirement.ts";
 import {
   createGitHubPullRequest,
   ensureGitHubBranchExists,
@@ -49,6 +55,7 @@ import type {
   ChangeBranchDetails,
   CreateWorktreeDetails,
   GitContextDetails,
+  IntegrateBranchDetails,
   ListWorktreesDetails,
   PullRequestDetails,
   PullRequestInput,
@@ -56,11 +63,48 @@ import type {
   PullRequestToolDetails,
   PullRequestToolInput,
   RemoveWorktreeDetails,
+  RetireBranchDetails,
   WorktreeEntry,
 } from "../types.ts";
 
 const EmptyParametersSchema = Type.Object({}, { additionalProperties: false });
 
+const BranchStatusParametersSchema = Type.Object(
+  {
+    ancestry: Type.Optional(
+      Type.Object(
+        {
+          sourceBranch: Type.String({ minLength: 1, description: "Exact existing local source branch to verify." }),
+          targetBranch: Type.String({ minLength: 1, description: "Exact existing local target branch to verify." }),
+        },
+        { additionalProperties: false },
+      ),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+const IntegrateBranchParametersSchema = Type.Object(
+  {
+    sourceBranch: Type.String({ minLength: 1, description: "Exact existing local source branch to integrate." }),
+    targetBranch: Type.String({ minLength: 1, description: "Exact existing local target branch already checked out in the clean control worktree." }),
+  },
+  { additionalProperties: false },
+);
+
+const RetireBranchParametersSchema = Type.Object(
+  {
+    branchName: Type.String({ minLength: 1, description: "Exact existing local branch to retire." }),
+    expectedHead: Type.String({
+      pattern: "^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$",
+      description: "Full 40- or 64-character hexadecimal commit identity expected for branchName.",
+    }),
+    targetBranch: Type.String({ minLength: 1, description: "Exact existing local branch used for ancestry verification." }),
+    force: Type.Boolean({ description: "Explicit authorization for unmerged retirement; false for merged retirement." }),
+  },
+  { additionalProperties: false },
+);
+
 const CreateBranchParametersSchema = Type.Object(
   {
     branchName: Type.String({ minLength: 1, description: "Name of the new branch to create from current HEAD." }),
@@ -224,6 +268,68 @@ export function formatRemoveWorktree(details: RemoveWorktreeDetails): string {
   return `Removed linked worktree directory ${path}. Verified it is no longer registered and retained local branch ${branch} at HEAD ${shortCommit(details.handoff.head)}; the removed cwd is not ready for handoff.`;
 }
 
+function integrationConflictOmissionLine(omitted: number): string {
+  return `${omitted} conflict path${omitted === 1 ? "" : "s"} omitted.`;
+}
+
+function formatIntegrationConflict(details: Extract<IntegrateBranchDetails, { status: "conflict" }>): string {
+  const source = safeWorktreeFormatValue(details.request.sourceBranch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
+  const target = safeWorktreeFormatValue(details.request.targetBranch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
+  const lines = [
+    `integrate_branch found conflicts while integrating ${source} into ${target}; the merge was automatically aborted and exact restoration was verified at target HEAD ${shortCommit(details.verified.heads.after.targetHead)}.`,
+    "Conflict paths:",
+  ];
+  let omitted = details.conflict.omitted;
+
+  for (const [index, entry] of details.conflict.paths.entries()) {
+    const path = safeWorktreeFormatValue(entry.path, WORKTREE_FORMAT_PATH_LIMIT_CHARS);
+    const line = `- ${path}`;
+    const remaining = details.conflict.paths.length - index - 1;
+    const candidateOmitted = details.conflict.omitted + remaining;
+    const candidate = [
+      ...lines,
+      line,
+      ...(candidateOmitted > 0 ? [integrationConflictOmissionLine(candidateOmitted)] : []),
+    ].join("\n");
+    if (candidate.length > GIT_INTEGRATION_SUMMARY_LIMIT_CHARS) {
+      omitted += details.conflict.paths.length - index;
+      break;
+    }
+    lines.push(line);
+  }
+
+  if (omitted > 0) lines.push(integrationConflictOmissionLine(omitted));
+  return lines.join("\n");
+}
+
+export function formatIntegrateBranch(details: IntegrateBranchDetails): string {
+  if (details.status === "conflict") return formatIntegrationConflict(details);
+
+  const source = safeWorktreeFormatValue(details.request.sourceBranch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
+  const target = safeWorktreeFormatValue(details.request.targetBranch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
+  const beforeTarget = shortCommit(details.verified.heads.before.targetHead);
+  const afterTarget = shortCommit(details.verified.heads.after.targetHead);
+  if (details.status === "already_integrated") {
+    return `integrate_branch verified ${source} was already integrated into ${target}; no merge ran and target HEAD remained ${afterTarget}.`;
+  }
+  if (details.status === "fast_forward") {
+    return `integrate_branch fast-forwarded ${target} from ${beforeTarget} to ${afterTarget}, integrating ${source}.`;
+  }
+  return `integrate_branch created and verified a merge commit ${afterTarget} on ${target} from previous target ${beforeTarget} and source ${source}.`;
+}
+
+export function formatRetireBranch(details: RetireBranchDetails): string {
+  const branch = safeWorktreeFormatValue(details.request.branchName, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
+  const target = safeWorktreeFormatValue(details.request.targetBranch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
+  const retiredHead = shortCommit(details.verified.refs.before.retiring.head);
+  const targetHead = shortCommit(details.verified.refs.after.target.head);
+  const localOnly = "No remote or remote-tracking branch was deleted.";
+  const text = details.mode === "merged"
+    ? `retire_branch retired merged local branch ${branch} at HEAD ${retiredHead} after verifying ancestry to ${target} at ${targetHead}. ${localOnly}`
+    : `retire_branch force-retired unmerged local branch ${branch} at HEAD ${retiredHead} against ${target} at ${targetHead}. The retired commit may lose its remaining local branch reference and can eventually become unreachable. ${localOnly}`;
+  return text.slice(0, GIT_RETIREMENT_SUMMARY_LIMIT_CHARS);
+}
+
 const PULL_REQUEST_INPUT_FIELDS: PullRequestInputField[] = ["headBranch", "baseBranch", "title", "body", "draft"];
 
 interface ResolvedPullRequestBranches {
@@ -381,16 +487,18 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
   pi.registerTool({
     name: BRANCH_STATUS_TOOL_NAME,
     label: "Branch Status",
-    description: "branch_status explicitly refreshes the current Git repository snapshot, including branch, working tree, unstaged changes, related pull request, and recent commits. branch_status is read-only and never mutates files, Git state, or GitHub state.",
-    promptSnippet: "branch_status: explicitly refresh current-repository branch, working tree, changes, related PR, and recent commits without mutation",
+    description: "branch_status explicitly refreshes the current Git repository snapshot and can optionally verify whether one captured local branch commit is an ancestor of another. branch_status is read-only and never mutates files, Git state, or GitHub state.",
+    promptSnippet: "branch_status: explicitly refresh current-repository Git state and optionally verify targeted local-branch ancestry without mutation",
     promptGuidelines: [
       "Use the automatic Git context for start-of-run questions; call branch_status only for an explicit refresh or after Git state changes during the current run.",
       "Use branch_status as a read-only refresh; branch_status never mutates files, Git state, or GitHub state.",
+      "Use targeted branch_status ancestry verification only after integrate_branch completes; do not issue branch_status in the same parallel tool batch as integrate_branch.",
     ],
-    parameters: EmptyParametersSchema,
-    async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
+    parameters: BranchStatusParametersSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const details = await collectGitContext(pi, ctx, {
         signal,
+        ancestry: params.ancestry,
         env: options.env,
         fetchImpl: options.fetchImpl,
       });
@@ -514,6 +622,53 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
     },
   });
 
+  pi.registerTool({
+    name: INTEGRATE_BRANCH_TOOL_NAME,
+    label: "Integrate Branch",
+    description: "integrate_branch verifies and merges one exact existing local source branch into one exact existing local target branch from the current clean control worktree, returning an already-integrated, fast-forward, merge-commit, or automatically aborted conflict result. integrate_branch never fetches or pushes.",
+    promptSnippet: "integrate_branch: merge an exact local source branch into the checked-out clean local target with verified outcomes and automatic conflict abort",
+    promptGuidelines: [
+      "Use integrate_branch only when the user explicitly wants one exact existing local source branch integrated into one exact existing local target branch.",
+      "Before integrate_branch, require the current clean control worktree to already have targetBranch checked out; integrate_branch never switches branches, stashes, or discards changes.",
+      "Use integrate_branch only after local refs already contain the commits to integrate; integrate_branch never fetches or pushes.",
+      "Call integrate_branch by itself and wait for it to complete; never batch integrate_branch with other Git mutations.",
+      "After integrate_branch completes, run any targeted branch_status ancestry proof separately; never place integrate_branch and branch_status in the same parallel tool batch.",
+      "A conflict result from integrate_branch means the merge was automatically aborted and restoration was verified; semantic conflict analysis belongs to a separate delegated workflow, not integrate_branch.",
+    ],
+    parameters: IntegrateBranchParametersSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const details = await integrateBranch(pi, ctx, params, signal);
+      return {
+        content: [{ type: "text", text: formatIntegrateBranch(details) }],
+        details,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: RETIRE_BRANCH_TOOL_NAME,
+    label: "Retire Branch",
+    description: "retire_branch deletes one exact unoccupied local branch only when its current commit matches expectedHead and its ancestry to one exact local targetBranch is verified. retire_branch requires force: true for explicitly authorized unmerged retirement, never directly deletes remote or remote-tracking branches, and leaves local branch configuration untouched.",
+    promptSnippet: "retire_branch: delete one exact local branch with an expected-HEAD lease, target ancestry verification, worktree-occupancy rejection, and explicit unmerged force authorization",
+    promptGuidelines: [
+      "Use retire_branch only when the user explicitly intends to delete one exact local branch.",
+      "Before retire_branch, obtain a fresh expected commit and ancestry proof with branch_status unless the exact commit was already supplied.",
+      "Call branch_status and retire_branch sequentially; never place branch_status and retire_branch in the same parallel tool batch.",
+      "Call retire_branch by itself; never run retire_branch beside another Git mutation.",
+      "Use force: true with retire_branch only after explicit user authorization for unmerged data loss.",
+      "Treat remove_worktree and retire_branch as separate sequential operations: removing a linked worktree retains its branch, which may be retired only afterward.",
+      "retire_branch never directly deletes a remote or remote-tracking branch.",
+    ],
+    parameters: RetireBranchParametersSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const details = await retireBranch(pi, ctx, params, signal);
+      return {
+        content: [{ type: "text", text: formatRetireBranch(details) }],
+        details,
+      };
+    },
+  });
+
   pi.registerTool({
     name: PUSH_BRANCH_TOOL_NAME,
     label: "Push Branch",