@senad-d/branchme 0.3.10 → 0.3.11

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.3.11 - Unreleased
+
+- `land_branch` with `pullRequestNumber` accepts a local source branch that is the merged PR head or one of its ancestors: a branch left behind because the PR received commits pushed from another checkout (for example a merge of the base) holds nothing the PR lacks, and is retired. A local branch with commits the PR head does not contain is still refused, now with its own message and Blocked/Resolve guidance; a PR head that is not available locally counts as not containing it.
+- Blocked/Resolve guidance for the PR-evidence refusals of `land_branch`.
+
 ## 0.3.10 - Unreleased
 
 - Added `reply_pull_request_feedback`: one reply in a review thread of a PR, optionally resolving it, or one PR conversation comment, on open, merged and closed PRs of the repository (forks included). The thread is verified to belong to the PR, and a conversation comment's number to be a pull request, before anything is posted. Agents that address PR feedback can now answer every comment on GitHub, so the reviewer, and the next automated check, see what was handled.

package/README.md

@@ -415,7 +415,7 @@ After the pull request **merged on the host**, run from the repository root:
 
 `remote` defaults to `origin`. Omit `worktreePath` to find the linked worktree holding `sourceBranch`, if any. An explicit path can also select a worktree incorrectly parked on `targetBranch`; unrelated branches, primary/root checkouts, detached, locked, dirty, or foreign worktrees are not removed. Invocation from inside the removal directory (including a nested or symlinked cwd) is refused: **run from the repository root**. Other caller directories in the same repository are supported; every Git command has an explicit `-C` directory, and cleanup runs through the primary checkout. When the merged source branch is checked out in the primary checkout and its tracked files are clean, `land_branch` switches that checkout to the target branch first (`checkout: switched`) so the source can be retired; untracked files stay in place.
 
-The tool fetches the exact remote target and by default requires the captured source tip to be its ancestor before cleanup. For squash/rebase merges, supply `pullRequestNumber`. BranchMe verifies a closed, merged PR in the same GitHub repository as the configured landing remote, exact head/base branch names, the source SHA, and containment of the reported merge commit in the fetched target. Supplying a PR number requires valid evidence even when ordinary ancestry succeeds. There is no general force escape hatch. This host-merge proof authorizes retiring the original rewritten source history; those original commits may eventually become unreachable. An existing selected source checkout must match the proven PR head exactly; a checkout parked on the target still needs target ancestry. Tracked/staged changes and non-ignored untracked files block removal. **Ignored `.env`, `.pi/`, `node_modules/`, `dist/`, and other ignored residue are deleted with the worktree**; preserve anything needed first. Only their top-level path entries, never contents, appear in `deletedIgnoredPaths`. Source retirement uses the captured expected-HEAD lease and the **remote-tracking target**, not local `HEAD` or a stale local target.
+The tool fetches the exact remote target and by default requires the captured source tip to be its ancestor before cleanup. For squash/rebase merges, supply `pullRequestNumber`. BranchMe verifies a closed, merged PR in the same GitHub repository as the configured landing remote, exact head/base branch names, a source SHA equal to the PR head or one of its ancestors (a local branch left behind holds nothing the PR lacks; one with commits the PR head does not contain is refused), and containment of the reported merge commit in the fetched target. Supplying a PR number requires valid evidence even when ordinary ancestry succeeds. There is no general force escape hatch. This host-merge proof authorizes retiring the original rewritten source history; those original commits may eventually become unreachable. An existing selected source checkout must be at the proven PR head or at that contained source SHA; a checkout parked on the target still needs target ancestry. Tracked/staged changes and non-ignored untracked files block removal. **Ignored `.env`, `.pi/`, `node_modules/`, `dist/`, and other ignored residue are deleted with the worktree**; preserve anything needed first. Only their top-level path entries, never contents, appear in `deletedIgnoredPaths`. Source retirement uses the captured expected-HEAD lease and the **remote-tracking target**, not local `HEAD` or a stale local target.
 
 Target sync is last, even when worktree removal or branch retirement is refused:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senad-d/branchme",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "type": "module",
   "description": "Pi extension for verified Git repository initialization, branch, worktree, integration, retirement, push, and pull request workflows.",
   "license": "MIT",

package/src/blocker-guidance.ts

@@ -112,6 +112,16 @@ const BLOCKER_RULES: readonly BlockerRule[] = [
     why: "no local branch has that name.",
     resolve: "list_branches to check names (fetch_remote first for remote branches); track_branch creates a local branch from a remote one.",
   },
+  {
+    pattern: /has commits the merged PR head does not contain/iu,
+    why: "the local branch holds commits that never reached the merged pull request, so deleting it would lose them.",
+    resolve: "report the branch and the PR; those commits need their own delivery (a new branch and pull request from another step) or the user's decision to discard them. Do not retry land_branch unchanged.",
+  },
+  {
+    pattern: /PR merge evidence does not match/iu,
+    why: "the pull request is not merged, or names a different head or base branch than the landing request.",
+    resolve: "read pull_request_status for the PR and retry land_branch once with its exact head and base branch names.",
+  },
   {
     pattern: /moved after|changed while|moved concurrently|changed during/iu,
     why: "repository state changed while the call ran.",

package/src/git-landing.ts

@@ -55,7 +55,8 @@ export interface LandBranchReceipt {
   sourceHead: string | null;
   ancestry: { isAncestor: boolean | null };
   mergeProof: "ancestry" | "pull-request" | null;
-  pullRequest: { number: number; headSha: string; mergeCommitSha: string } | null;
+  /** sourceInHead: the local source head is the merged PR head or one of its ancestors (a branch left behind). */
+  pullRequest: { number: number; headSha: string; mergeCommitSha: string; sourceInHead: boolean } | null;
   worktree: {
     path: string | null;
     outcome: "removed" | "absent" | "refused";
@@ -240,8 +241,8 @@ 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;
+  const exactMergedPrHead = receipt.mergeProof === "pull-request" && validated.worktree.branch === receipt.sourceBranch &&
+    (worktreeHead === receipt.pullRequest?.headSha || (worktreeHead === receipt.sourceHead && receipt.pullRequest?.sourceInHead === true));
   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.");
@@ -297,7 +298,7 @@ async function retireLandingBranch(pi: GitAPI, receipt: LandBranchReceipt, signa
     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,
+    force: receipt.mergeProof === "pull-request" && receipt.pullRequest?.sourceInHead === true && head === receipt.sourceHead,
   }, ctx.cwd, signal, "remote-tracking", receipt.remoteTargetHead);
   receipt.branch.outcome = "deleted";
   receipt.branch.reason = null;
@@ -415,6 +416,15 @@ async function refuseLanding(pi: GitAPI, receipt: LandBranchReceipt, error: unkn
   return receipt;
 }
 
+// A commit missing locally (an unfetched squash-merged PR head) proves nothing: not contained.
+async function commitContains(pi: GitAPI, ctx: GitCommandContext, ancestor: string, descendant: string, signal?: AbortSignal): Promise<boolean> {
+  try {
+    return await isCommitAncestor(pi, ctx, ancestor, descendant, signal);
+  } catch {
+    return false;
+  }
+}
+
 async function verifyLandingPullRequest(
   pi: GitAPI,
   ctx: GitCommandContext,
@@ -431,14 +441,20 @@ async function verifyLandingPullRequest(
   }
   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)) {
+  if (!pr.merged || pr.state !== "closed" || !pr.mergeCommitSha || pr.head !== receipt.sourceBranch || pr.base !== receipt.targetBranch) {
     throw new Error("PR merge evidence does not match the exact source commit and target branch; landing refused.");
   }
+  // A local branch behind the merged head (the PR received commits pushed from another
+  // checkout, such as a merge of the base) holds nothing the PR lacks.
+  const sourceInHead = receipt.sourceHead === null || pr.headSha === receipt.sourceHead ||
+    await commitContains(pi, ctx, receipt.sourceHead, pr.headSha, signal);
+  if (!sourceInHead) {
+    throw new Error("The local source branch has commits the merged PR head does not contain; landing refused to keep them.");
+  }
   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.pullRequest = { number: pr.number, headSha: pr.headSha, mergeCommitSha: pr.mergeCommitSha, sourceInHead };
   receipt.mergeProof = "pull-request";
 }