@senad-d/branchme 0.1.9 → 0.2.1

package/src/git.ts

@@ -629,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;
@@ -998,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'.");
@@ -1836,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,

package/src/tools/branchme-tools.ts

@@ -8,6 +8,7 @@ import {
   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,
@@ -16,6 +17,7 @@ import {
   PUSH_BRANCH_TOOL_NAME,
   REBASE_BRANCH_TOOL_NAME,
   REMOVE_WORKTREE_TOOL_NAME,
+  RETIRE_BRANCH_TOOL_NAME,
 } from "../constants.ts";
 import {
   changeExistingLocalBranch,
@@ -38,6 +40,7 @@ import {
 } 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,
@@ -60,6 +63,7 @@ import type {
   PullRequestToolDetails,
   PullRequestToolInput,
   RemoveWorktreeDetails,
+  RetireBranchDetails,
   WorktreeEntry,
 } from "../types.ts";
 
@@ -88,6 +92,19 @@ const IntegrateBranchParametersSchema = Type.Object(
   { 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." }),
@@ -301,6 +318,18 @@ export function formatIntegrateBranch(details: IntegrateBranchDetails): string {
   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 {
@@ -616,6 +645,30 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
     },
   });
 
+  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",
@@ -643,7 +696,8 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
     description: "pull_request creates a GitHub pull request in the resolved current repository. PR fields are optional only when BRANCHME_PR_AUTOFILL=true; pull_request then infers branches, derives title/body from commit subjects, and defaults draft to false. Branches must exist locally and on GitHub, and headBranch must match the GitHub-visible commit. Owner-prefixed refs, owner, and repo are never accepted as inputs.",
     promptSnippet: "pull_request: create a GitHub pull request with explicit fields or optional configured PR field autofill",
     promptGuidelines: [
-      "Use pull_request only when the user explicitly asks to create a pull request; pull_request must not create one merely because a branch was pushed.",
+      "Use pull_request whenever creating a pull request is appropriate for the active workflow; authorization may come from user prompts, system or developer instructions, AGENTS.md, skills, automation, or delegated/subagent prompts.",
+      "Agents may invoke pull_request without a separate end-user confirmation when the active workflow makes pull request creation appropriate.",
       "When automatic Git context reports pull request field autofill disabled, use pull_request only with explicit headBranch, baseBranch, title, body, and draft values.",
       "When automatic Git context reports pull request field autofill enabled, pull_request may omit fields the user did not provide; prefer the user's explicit values whenever present.",
       "Use pull_request only with existing local branches for headBranch and baseBranch; headBranch must match the GitHub-visible branch commit.",

package/src/types.ts

@@ -34,6 +34,13 @@ export interface IntegrateBranchToolInput {
   targetBranch: string;
 }
 
+export interface RetireBranchToolInput {
+  branchName: string;
+  expectedHead: string;
+  targetBranch: string;
+  force: boolean;
+}
+
 export type CreateWorktreeMode = "new" | "existing";
 
 export type ListWorktreesToolInput = Record<string, never>;
@@ -354,6 +361,75 @@ export type IntegrateBranchDetails =
   | IntegrateBranchMergeCommitDetails
   | IntegrateBranchConflictDetails;
 
+export type RetireBranchMode = "merged" | "forced_unmerged";
+
+export interface RetireBranchRepositoryIdentity {
+  worktreeRoot: string;
+  canonicalCommonGitDirectory: string;
+}
+
+export interface RetireBranchRefIdentity {
+  branchName: string;
+  fullRef: string;
+  head: string;
+}
+
+export interface RetireBranchAbsentRefProof {
+  branchName: string;
+  fullRef: string;
+  absent: true;
+}
+
+export interface RetireBranchWorktreeOccupancyProof {
+  branchName: string;
+  completeInventoryInspected: true;
+  occupied: false;
+  matchingWorktreeCount: 0;
+}
+
+export interface RetireBranchDetails {
+  action: "retire_branch";
+  status: "retired";
+  mode: RetireBranchMode;
+  /** Exact normalized request values used for the verified retirement. */
+  request: RetireBranchToolInput;
+  verified: {
+    repository: {
+      before: RetireBranchRepositoryIdentity;
+      after: RetireBranchRepositoryIdentity;
+      identityPreserved: true;
+    };
+    refs: {
+      before: {
+        retiring: RetireBranchRefIdentity;
+        target: RetireBranchRefIdentity;
+        expectedHead: string;
+        expectedHeadMatches: true;
+      };
+      after: {
+        retiring: RetireBranchAbsentRefProof;
+        target: RetireBranchRefIdentity;
+        targetHeadPreserved: true;
+      };
+    };
+    ancestry: {
+      retiringHead: string;
+      targetHead: string;
+      retiringIsAncestorOfTarget: boolean;
+    };
+    worktreeOccupancy: {
+      before: RetireBranchWorktreeOccupancyProof;
+      after: RetireBranchWorktreeOccupancyProof;
+    };
+    mutation: {
+      exactLocalRefDeletionAttempted: true;
+      localBranchAbsentAfterDeletion: true;
+      directRemoteDeletionAttempted: false;
+      remoteTrackingRefDeletionAttempted: false;
+    };
+  };
+}
+
 export interface PullRequestDetails {
   repository: GitHubRepository;
   number: number;

package/src/ui/branchme-panel.ts

@@ -154,7 +154,7 @@ function sectionTitle(section: BranchMePanelSection): string {
     case "workflow":
       return "WORKFLOW";
     case "integration":
-      return "INTEGRATION";
+      return "LIFECYCLE";
     case "worktrees":
       return "WORKTREES";
   }
@@ -183,7 +183,7 @@ function sectionFooter(section: BranchMePanelSection, data: BranchMePanelData):
     case "workflow":
       return "workflow • inspect → change → fetch/pull/rebase → create → push → PR";
     case "integration":
-      return "integration • local refs • clean target • conflicts auto-abort";
+      return "lifecycle • integrate → remove worktree separately → retire local ref";
     case "worktrees":
       return "worktrees • create → handoff cwd → next session • remove retains branch";
   }
@@ -214,12 +214,15 @@ function sectionRows(section: BranchMePanelSection, data: BranchMePanelData): Pa
       ];
     case "integration":
       return [
-        heading("INTEGRATION"),
+        heading("LIFECYCLE"),
         workflowDetailRow("integrate_branch", "exact local source -> target"),
         workflowDetailRow("control target", "checked out + clean"),
-        workflowDetailRow("remote effects", "never fetch or push"),
         workflowDetailRow("conflict", "automatic verified abort"),
         workflowDetailRow("semantic intent", "separate developer workflow"),
+        workflowDetailRow("remove_worktree", "separate; branch retained"),
+        workflowDetailRow("retire_branch", "leased local ref deletion"),
+        workflowDetailRow("retirement guard", "unoccupied + target ancestry"),
+        workflowDetailRow("remote effects", "never delete remote refs"),
       ];
     case "worktrees":
       return [