@senad-d/branchme 0.3.10 → 0.3.12

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.12 - Unreleased
+
+- Added `pull_request_files` (read-only: a PR's first 100 changed files with change type and line counts, plus its labels) and `label_pull_request` (adds 1 to 5 existing repository labels to a PR; GitHub would create an unknown label, so it is refused first). An agent can now choose and set a PR's area label from what it changes.
+- `pull_request_feedback` prints each comment's and review's URL, and review ids, so a follow-up issue can quote and link the exact comment.
+
+## 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

@@ -16,7 +16,7 @@
 
 ---
 
-BranchMe is a Pi extension for safe Git repository, branch, and worktree workflow automation. Before each agent run, it appends a bounded, read-only snapshot of the current Git repository to the system prompt. It also adds an informational `/branchme` command and twenty-three agent-callable tools that initialize a repository, refresh state, manage, integrate, and retire local branches, conclude a kept merge, inspect/create/remove linked worktrees, push the current branch, create GitHub pull requests, and read and answer PR feedback.
+BranchMe is a Pi extension for safe Git repository, branch, and worktree workflow automation. Before each agent run, it appends a bounded, read-only snapshot of the current Git repository to the system prompt. It also adds an informational `/branchme` command and twenty-five agent-callable tools that initialize a repository, refresh state, manage, integrate, and retire local branches, conclude a kept merge, inspect/create/remove linked worktrees, push the current branch, create GitHub pull requests, read and answer PR feedback, and list and label a PR's changed files.
 
 <table align="center">
   <tr>
@@ -257,6 +257,8 @@ Commands are informational only. BranchMe actions are performed by agent-callabl
 | `track_branch` | `{ "branchName": string, "remote"?: string, "remoteBranch"?: string }` | Fetch one exact remote branch and create/check out a new local tracking branch. Remote defaults to `origin`; remoteBranch defaults to branchName. Requires a clean idle checkout; verifies HEAD and upstream. |
 | `update_from_base` | `{ "baseBranch": string, "remote"?: string, "keepConflicts"?: boolean }` | Fetch the exact remote base (remote defaults to `origin`) and merge its captured commit into the clean current feature. Uses verified normal-merge policy; a `conflict` is automatically aborted with its paths listed, or with `keepConflicts: true` reported as `conflict_kept` and left in progress (MERGE_HEAD set, conflicted paths unmerged) for `conclude_merge`. Never rebases, pushes, or changes upstream configuration. |
 | `conclude_merge` | `{ "action": "conclude" \| "abort" }` | Finish or abandon the in-progress merge on the current checkout. `conclude` refuses default/custom-sized `<<<<<<<`, `|||||||`, `=======`, or `>>>>>>>` marker lines in unmerged working-tree paths and staged blobs (including CRLF and binary content, naming the paths), stages only the currently unmerged paths, rechecks the candidate index, commits with `git commit --no-edit`, and verifies MERGE_HEAD is gone and HEAD is a two-parent merge of the previous HEAD and MERGE_HEAD; unrelated unstaged changes stay unstaged. `abort` runs `git merge --abort` and verifies the restored HEAD, cleared operation state, and clean tree. Refuses when no merge is in progress. |
+| `pull_request_files` | `{ "number": integer }` | List a pull request's first 100 changed files (path, change type, additions, deletions; the rest counted) and its current labels. Read-only. |
+| `label_pull_request` | `{ "number": integer, "labels": string[] }` | Add 1 to 5 labels that already exist in the repository to a pull request; an unknown label is refused before anything changes, existing labels stay. |
 | `reply_pull_request_feedback` | `{ "number": integer, "body": string, "threadId"?: string, "resolve"?: boolean }` | Answer PR feedback on an open, merged or closed PR of this repository (forks included). With `threadId` (from `pull_request_feedback`) it replies in that review thread after verifying the thread belongs to the PR, and `resolve: true` then resolves it; without `threadId` it posts one conversation comment after confirming the number is a pull request, not an issue. Body is Markdown, at most 4,000 characters. Never edits, deletes, approves, merges, or closes. |
 | `pull_request_feedback` | `{ "number"?: integer, "headBranch"?: string }` | Read what a same-repository PR asks to be fixed in one GraphQL request: unresolved, current review threads with their comments (resolved and outdated threads are counted only), review summaries with a body or requested changes, the latest 50 conversation comments, and the head commit's failing checks with up to 20 failure and warning annotations each (`path:line LEVEL: message`). Threads and conversation comments carry their GraphQL ids, every comment its author and time, and comments by the token's own user are marked `(you)`, so a caller can reply to a thread and tell new comments from its own replies. For up to three failing GitHub Actions jobs it adds the log lines leading to the last `##[error]`. A job log that cannot be read is reported per check. No mutations. |
 | `pull_request_status` | `{ "number"?: integer, "headBranch"?: string }` | Read exact same-repository PR lifecycle and head/base/merge identities. Number and headBranch are mutually exclusive. Without number, returns the most recently updated PR for headBranch or the current branch. Does not certify CI checks or review approvals. |
@@ -415,7 +417,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:
 
@@ -566,7 +568,7 @@ npm run check:pack
 printf '/branchme help\n/quit\n' | pi --no-extensions -e .
 ```
 
-Validation covers TypeScript typechecking, formatting checks, automatic context collection and prompt injection, mocked GitHub lookup, isolated real-Git worktree, branch-integration, and leased branch-retirement lifecycle tests, package checks, checkout Pi runtime smoke, and package-content verification. The checkout smoke loads BranchMe through Pi, then uses a temporary verifier command to confirm all twenty-three BranchMe tools are visible through `pi.getAllTools()` with strict schemas and prompt metadata, including `integrate_branch`, `retire_branch`, `conclude_merge`, and targeted `branch_status.ancestry`, with no generic `continue_merge` or `abort_merge` tool. Runtime smoke inspects retirement and landing registration/schema but never executes either cleanup tool. Smoke-test notes are recorded in [`docs/SMOKE_TEST.md`](docs/SMOKE_TEST.md), and TUI/help captures are stored in [`docs/TUI_CAPTURE.md`](docs/TUI_CAPTURE.md).
+Validation covers TypeScript typechecking, formatting checks, automatic context collection and prompt injection, mocked GitHub lookup, isolated real-Git worktree, branch-integration, and leased branch-retirement lifecycle tests, package checks, checkout Pi runtime smoke, and package-content verification. The checkout smoke loads BranchMe through Pi, then uses a temporary verifier command to confirm all twenty-five BranchMe tools are visible through `pi.getAllTools()` with strict schemas and prompt metadata, including `integrate_branch`, `retire_branch`, `conclude_merge`, and targeted `branch_status.ancestry`, with no generic `continue_merge` or `abort_merge` tool. Runtime smoke inspects retirement and landing registration/schema but never executes either cleanup tool. Smoke-test notes are recorded in [`docs/SMOKE_TEST.md`](docs/SMOKE_TEST.md), and TUI/help captures are stored in [`docs/TUI_CAPTURE.md`](docs/TUI_CAPTURE.md).
 
 Refresh TUI captures intentionally with:
 

package/docs/PROJECT_DEFINITION_BRIEF.md

@@ -15,7 +15,7 @@ Originally approved on 2026-06-30. Updated to describe the implemented `0.3.1` p
 - Exported extension function: `branchMeExtension`
 - Repository URL: `https://github.com/senad-d/branchme`
 - One-sentence pitch: Verified Pi tools for Git repository initialization plus current-repository branch, integration, retirement, linked-worktree, push, and GitHub pull request workflows.
-- Tool count: twenty-three strict agent-callable tools.
+- Tool count: twenty-five strict agent-callable tools.
 
 ## 3. Users and use cases
 
@@ -57,6 +57,8 @@ Originally approved on 2026-06-30. Updated to describe the implemented `0.3.1` p
 | Tool | `conclude_merge` | Commit or abort the in-progress kept merge | Refuses remaining markers; stages only formerly unmerged paths; `commit --no-edit`; verified two-parent result or verified abort |
 | Tool | `pull_request_status` | Read exact PR or latest PR for a head | Open/closed/merged state and commit identities; not a CI/review verdict |
 | Tool | `pull_request_feedback` | Read what a PR asks to be fixed | Unresolved review threads, review summaries, conversation comments, failing checks with annotations and Actions log tails; read-only |
+| Tool | `pull_request_files` | List a PR's changed files | Path, change type and line counts of the first 100 changed files, plus current labels; read-only |
+| Tool | `label_pull_request` | Label a PR | Adds 1-5 labels that already exist in the repository; refuses unknown labels; never removes |
 | Tool | `reply_pull_request_feedback` | Answer PR feedback | One reply in a review thread of the PR (optionally resolving it) or one conversation comment; the thread must belong to the PR; never edits, deletes, approves, merges or closes |
 | Tool | `init_repository` | Initialize the exact current directory as a new non-bare Git repository | Optional initial branch; rejects reinitialization/nesting; no path, commit, or project-file controls |
 | Tool | `branch_status` | Refresh bounded current-worktree Git and related-PR context; optionally prove captured local or remote-tracking ancestry | Read-only; targeted ancestry is absent from automatic context |
@@ -97,7 +99,7 @@ Originally approved on 2026-06-30. Updated to describe the implemented `0.3.1` p
   - `src/github.ts`
   - `src/ui/branchme-panel.ts`
 - Module boundaries:
-  - The extension entry point registers the informational command, twenty-three tools, and automatic context hook.
+  - The extension entry point registers the informational command, twenty-five tools, and automatic context hook.
   - `src/git-workflow.ts` and `src/tools/workflow-tools.ts` own verified remote tracking, base updates, and the new PR status registration.
   - The context module owns bounded read-only collection, prompt formatting, targeted ancestry rendering, and the `before_agent_start` hook; automatic context never runs ancestry queries.
   - The command and UI modules own mode-safe informational help/status behavior and never invoke mutations.

package/docs/SMOKE_TEST.md

@@ -23,9 +23,9 @@ pi --no-extensions -e .
 ## Automated smoke behavior
 
 - `npm run smoke:pi` first runs isolated checkout Pi processes from a temporary non-Git working directory: one with `pi --no-extensions -e <package> -e <temporary verifier>` and `/branchmeverify verify`, then one with `pi --no-extensions -e <package>` and `/branchme help`.
-- The temporary command verifier calls `pi.getAllTools()` after BranchMe loads and confirms exactly twenty-three tools—`fetch_remote`, `list_branches`, `track_branch`, `update_from_base`, `conclude_merge`, `pull_request_status`, `pull_request_feedback`, `reply_pull_request_feedback`, `branch_status`, `init_repository`, `change_branch`, `create_branch`, `create_worktree`, `fetch_branch`, `integrate_branch`, `land_branch`, `list_worktrees`, `pull_branch`, `pull_request`, `push_branch`, `rebase_branch`, `remove_worktree`, and `retire_branch`—are each registered exactly once and active with strict schemas, named prompt guidelines, descriptions, and extension source metadata. It also proves `continue_merge` and `abort_merge` are absent.
+- The temporary command verifier calls `pi.getAllTools()` after BranchMe loads and confirms exactly twenty-five tools—`fetch_remote`, `list_branches`, `track_branch`, `update_from_base`, `conclude_merge`, `pull_request_status`, `pull_request_feedback`, `reply_pull_request_feedback`, `pull_request_files`, `label_pull_request`, `branch_status`, `init_repository`, `change_branch`, `create_branch`, `create_worktree`, `fetch_branch`, `integrate_branch`, `land_branch`, `list_worktrees`, `pull_branch`, `pull_request`, `push_branch`, `rebase_branch`, `remove_worktree`, and `retire_branch`—are each registered exactly once and active with strict schemas, named prompt guidelines, descriptions, and extension source metadata. It also proves `continue_merge` and `abort_merge` are absent.
 - Runtime schema inspection verifies that `integrate_branch` has exactly the required `sourceBranch` and `targetBranch` fields and that `retire_branch` has exactly the required `branchName`, `expectedHead`, `targetBranch`, and `force` fields with `additionalProperties: false`. It also verifies that `branch_status` has only an optional top-level `ancestry` object whose required nested `sourceBranch` and `targetBranch` fields reject additional nested or top-level properties.
-- A second temporary verifier registers a deterministic local smoke model, blocks `fetch`, and runs normal prompts through real Pi lifecycle handling. It verifies automatic no-tool Git context in a temporary repository, one real `branch_status` tool refresh after a verifier-created local change, safe credential-free related-PR status with no request, and non-Git startup fallback. It expects all twenty-three tools but forbids `land_branch`, `retire_branch`, `integrate_branch`, `conclude_merge`, and every remote or worktree mutation tool (including `fetch_remote`) from executing.
+- A second temporary verifier registers a deterministic local smoke model, blocks `fetch`, and runs normal prompts through real Pi lifecycle handling. It verifies automatic no-tool Git context in a temporary repository, one real `branch_status` tool refresh after a verifier-created local change, safe credential-free related-PR status with no request, and non-Git startup fallback. It expects all twenty-five tools but forbids `land_branch`, `retire_branch`, `integrate_branch`, `conclude_merge`, and every remote or worktree mutation tool (including `fetch_remote`) from executing.
 - The Pi runtime smoke validates worktree, integration, and retirement tool registration, strict schemas, and prompt contracts only; it never creates or removes a worktree, runs a merge, or retires a branch. Real-Git lifecycle coverage runs under `npm run test` in isolated temporary local repositories with no remote contact.
 - Isolated real-Git integration tests cover `already_integrated`, `fast_forward`, exact two-parent `merge_commit`, and conflict-path capture followed by verified automatic abort/restoration. They also cover target mismatch, dirty control state, rejection of branch-specific target merge options, unrelated histories, ignored-file overwrite protection, preserved repository hooks, and a committed source ref checked out in another dirty linked worktree. The recorded merge argv proves autostash and rerere are disabled, ignored-file protection is enabled, and `--no-verify` is absent.
 - Isolated real-Git retirement tests cover merged and explicitly forced-unmerged local-ref deletion, stale expected-`HEAD` rejection, current and linked-worktree occupancy, dirty unrelated worktrees, non-current targets, and preservation of target refs, remote-tracking refs, worktrees, working-tree files, and `branch.<name>.*` configuration without contacting a remote. Recorded argv proves retirement uses `update-ref --no-deref -d` with the captured expected commit and never uses `git branch -d/-D`, fetch, push, or a remote ref target.

package/docs/STRUCTURE.md

@@ -30,7 +30,7 @@ src/
 
 ## Module boundaries
 
-1. `src/extension.ts` stays small and registers the command, twenty-three tools, and one `before_agent_start` context hook.
+1. `src/extension.ts` stays small and registers the command, twenty-five tools, and one `before_agent_start` context hook.
 2. `src/git-context.ts` owns the shared read-only collector, escaped/bounded formatter, automatic system-prompt append, and the current-state output used by `branch_status`.
 3. `src/commands/branchme-command.ts` parses `/branchme`, `/branchme help`, `--help`, and `-h`; it never performs git or GitHub mutations and avoids raw stdout in JSON mode.
 4. `src/tools/branchme-tools.ts` owns strict TypeBox schemas, prompt metadata, bounded tool content, and safe structured details. `branch_status` delegates to the shared context collector and optional ancestry verifier; `integrate_branch` and `retire_branch` delegate to focused mutation state machines; worktree tools expose explicit inventory and verified handoff operations.

package/docs/TUI_CAPTURE.md

@@ -44,6 +44,8 @@ Commands only show info; BranchMe tools perform actions.
 - `pull_request_status` — inspect a PR by number, or the latest PR for a head branch; not a CI/review verdict.
 - `pull_request_feedback` — read a PR's unresolved review comments and failing checks with log tails.
 - `reply_pull_request_feedback` — reply to a PR review thread (optionally resolving it) or post a PR comment.
+- `pull_request_files` — list a PR's changed files and current labels.
+- `label_pull_request` — add existing repository labels to a PR.
 - `pull_request` — reuses an exact matching open PR without changing its title, body, or draft state.
 - `land_branch` — after host merge, clean up from the primary checkout; use `pullRequestNumber` for squash/rebase evidence.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senad-d/branchme",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "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/commands/branchme-command.ts

@@ -53,6 +53,8 @@ export function getBranchMeHelpText(): string {
     "- `pull_request_status` — inspect a PR by number, or the latest PR for a head branch; not a CI/review verdict.",
     "- `pull_request_feedback` — read a PR's unresolved review comments and failing checks with log tails.",
     "- `reply_pull_request_feedback` — reply to a PR review thread (optionally resolving it) or post a PR comment.",
+    "- `pull_request_files` — list a PR's changed files and current labels.",
+    "- `label_pull_request` — add existing repository labels to a PR.",
     "- `pull_request` — reuses an exact matching open PR without changing its title, body, or draft state.",
     "- `land_branch` — after host merge, clean up from the primary checkout; use `pullRequestNumber` for squash/rebase evidence.",
     "",

package/src/constants.ts

@@ -18,6 +18,8 @@ export const PULL_REQUEST_TOOL_NAME = "pull_request";
 export const PULL_REQUEST_STATUS_TOOL_NAME = "pull_request_status";
 export const PULL_REQUEST_FEEDBACK_TOOL_NAME = "pull_request_feedback";
 export const REPLY_PULL_REQUEST_FEEDBACK_TOOL_NAME = "reply_pull_request_feedback";
+export const PULL_REQUEST_FILES_TOOL_NAME = "pull_request_files";
+export const LABEL_PULL_REQUEST_TOOL_NAME = "label_pull_request";
 export const LIST_WORKTREES_TOOL_NAME = "list_worktrees";
 export const CREATE_WORKTREE_TOOL_NAME = "create_worktree";
 export const REMOVE_WORKTREE_TOOL_NAME = "remove_worktree";
@@ -47,6 +49,8 @@ export const BRANCHME_TOOL_NAMES = [
   PULL_REQUEST_STATUS_TOOL_NAME,
   PULL_REQUEST_FEEDBACK_TOOL_NAME,
   REPLY_PULL_REQUEST_FEEDBACK_TOOL_NAME,
+  PULL_REQUEST_FILES_TOOL_NAME,
+  LABEL_PULL_REQUEST_TOOL_NAME,
   LIST_WORKTREES_TOOL_NAME,
   CREATE_WORKTREE_TOOL_NAME,
   REMOVE_WORKTREE_TOOL_NAME,
@@ -98,5 +102,6 @@ export const PULL_REQUEST_FEEDBACK_BODY_LIMIT_CHARS = 2_000;
 export const PULL_REQUEST_FEEDBACK_LOG_LIMIT_CHARS = 6_000;
 export const PULL_REQUEST_FEEDBACK_SUMMARY_LIMIT_CHARS = 24_000;
 export const PULL_REQUEST_REPLY_BODY_LIMIT_CHARS = 4_000;
+export const PULL_REQUEST_LABEL_LIMIT = 5;
 export const GITHUB_GRAPHQL_TIMEOUT_MS = 15_000;
 export const GITHUB_JOB_LOG_TIMEOUT_MS = 30_000;

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";
 }
 

package/src/github-feedback.ts

@@ -2,7 +2,7 @@ import {
   GITHUB_API_BASE_URL, GITHUB_GRAPHQL_TIMEOUT_MS, GITHUB_JOB_LOG_TIMEOUT_MS, PULL_REQUEST_FEEDBACK_BODY_LIMIT_CHARS,
   PULL_REQUEST_FEEDBACK_LOG_JOB_LIMIT, PULL_REQUEST_FEEDBACK_LOG_LIMIT_CHARS, PULL_REQUEST_FEEDBACK_LOG_TAIL_BYTES,
   PULL_REQUEST_FEEDBACK_LOG_TAIL_LINES, PULL_REQUEST_FEEDBACK_RESPONSE_LIMIT_BYTES, PULL_REQUEST_FEEDBACK_SUMMARY_LIMIT_CHARS,
-  PULL_REQUEST_REPLY_BODY_LIMIT_CHARS,
+  PULL_REQUEST_LABEL_LIMIT, PULL_REQUEST_REPLY_BODY_LIMIT_CHARS,
 } from "./constants.ts";
 import {
   encodePathSegment, fetchGitHubResponse, gitHubJsonHeaders, isRecord, parseGitHubJson, pullRequestNumberField,
@@ -12,7 +12,8 @@ import {
 import { redactSecrets } from "./redaction.ts";
 import type {
   GitHubRepository, PullRequestFeedbackAnnotation, PullRequestFeedbackCheck, PullRequestFeedbackComment, PullRequestFeedbackDetails,
-  PullRequestFeedbackReview, PullRequestFeedbackThread, PullRequestReplyDetails, PullRequestReplyInput,
+  PullRequestFeedbackReview, PullRequestFeedbackThread, PullRequestFilesDetails, PullRequestLabelDetails,
+  PullRequestReplyDetails, PullRequestReplyInput,
 } from "./types.ts";
 
 // One GraphQL request reads review threads with their resolution state, review summaries, conversation
@@ -255,9 +256,10 @@ function location(path: string, line: number | null): string {
   return line === null ? path : `${path}:${line}`;
 }
 
-// "@alice (you) 2026-10-14T19:50:15Z" — the marker and time decide what is new.
+// "@alice (you) 2026-10-14T19:50:15Z <url>" — the marker and time decide what is new;
+// the URL lets a follow-up issue link the exact comment.
 function byline(comment: PullRequestFeedbackComment): string {
-  return [`@${comment.author}`, comment.byViewer ? "(you)" : "", comment.createdAt].filter(Boolean).join(" ");
+  return [`@${comment.author}`, comment.byViewer ? "(you)" : "", comment.createdAt, comment.url ? `<${comment.url}>` : ""].filter(Boolean).join(" ");
 }
 
 function idTag(kind: string, id: string): string {
@@ -291,7 +293,7 @@ export function formatPullRequestFeedback(details: PullRequestFeedbackDetails):
     `Unresolved review threads: ${details.unresolvedThreads.length} (${details.resolvedThreadCount} resolved and ${details.outdatedThreadCount} outdated not listed${omittedThreads}).`,
     ...details.unresolvedThreads.map(formatThread),
     `Reviews with a body or requested changes: ${details.reviews.length}.`,
-    ...details.reviews.map((review) => `- ${byline(review)} ${review.state}: ${review.body}`),
+    ...details.reviews.map((review) => `- ${idTag("review", review.id)}${byline(review)} ${review.state}: ${review.body}`),
     `Conversation comments: ${details.comments.length}${omittedComments}.`,
     ...details.comments.map((comment) => `- ${idTag("comment", comment.id)}${byline(comment)}: ${comment.body}`),
     `Failing checks: ${details.failingChecks.length}${omittedChecks}.`,
@@ -392,3 +394,84 @@ export function formatPullRequestReply(details: PullRequestReplyDetails): string
   if (details.resolved !== null) resolution = details.resolved ? "; thread resolved" : "; thread NOT resolved";
   return `Replied to thread ${details.threadId} on PR #${details.number}${resolution}: ${details.commentUrl}`;
 }
+
+const PULL_REQUEST_FILES_QUERY = `query($owner: String!, $repo: String!, $number: Int!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $number) {
+      number
+      labels(first: 50) { nodes { name } }
+      files(first: 100) { totalCount nodes { path changeType additions deletions } }
+    }
+  }
+}`;
+
+function requirePullRequestNode(payload: Record<string, unknown>, repository: GitHubRepository, number: number): Record<string, unknown> {
+  const pullRequest = isRecord(payload.data) && isRecord(payload.data.repository) ? payload.data.repository.pullRequest : null;
+  if (!isRecord(pullRequest) || pullRequest.number !== number) {
+    throw new Error(`Pull request #${number} was not found in ${repository.owner}/${repository.repo}.`);
+  }
+  return pullRequest;
+}
+
+/** The first 100 changed files of a pull request and its current labels. */
+export async function getPullRequestFiles(repository: GitHubRepository, number: number, token: string, options: PullRequestFetchOptions = {}): Promise<PullRequestFilesDetails> {
+  validateGitHubRepository(repository);
+  pullRequestNumberField(number);
+  const payload = await postGraphQL(PULL_REQUEST_FILES_QUERY, { owner: repository.owner, repo: repository.repo, number }, token, options, "GitHub pull request files");
+  const pullRequest = requirePullRequestNode(payload, repository, number);
+  const files = nodes(pullRequest.files).map((file) => ({
+    path: safeText(file.path, token, 500),
+    change: safeText(file.changeType, token, 20).toLowerCase(),
+    additions: typeof file.additions === "number" ? file.additions : 0,
+    deletions: typeof file.deletions === "number" ? file.deletions : 0,
+  }));
+  return {
+    action: "pull_request_files",
+    repository,
+    number,
+    labels: nodes(pullRequest.labels).map((label) => safeText(label.name, token, 100)).filter(Boolean),
+    files,
+    omitted: Math.max(0, totalCount(pullRequest.files) - files.length),
+  };
+}
+
+export function formatPullRequestFiles(details: PullRequestFilesDetails): string {
+  const omitted = details.omitted > 0 ? `; ${details.omitted} more not listed` : "";
+  return [
+    `PR #${details.number}: ${details.files.length} changed file(s)${omitted}. Labels: ${details.labels.join(", ") || "none"}.`,
+    ...details.files.map((file) => `- ${file.path} (${file.change}, +${file.additions} -${file.deletions})`),
+  ].join("\n");
+}
+
+async function requireExistingLabel(repository: GitHubRepository, label: string, token: string, options: PullRequestFetchOptions): Promise<void> {
+  const url = `${GITHUB_API_BASE_URL}/repos/${encodePathSegment(repository.owner)}/${encodePathSegment(repository.repo)}/labels/${encodePathSegment(label)}`;
+  const response = await fetchGitHubResponse(requireFetchImplementation(options.fetchImpl ?? globalThis.fetch), url, {
+    method: "GET", headers: gitHubJsonHeaders(token), signal: options.signal,
+  }, "GitHub label lookup failed", token);
+  if (response.status === 404) throw new Error(`Label "${label}" does not exist in ${repository.owner}/${repository.repo}; label_pull_request adds existing labels only.`);
+  if (!response.ok) throw new Error(`GitHub label lookup returned HTTP ${response.status}.`);
+}
+
+/** Adds existing repository labels to a pull request; GitHub would create unknown ones, so they are refused first. */
+export async function labelPullRequest(repository: GitHubRepository, number: number, labels: readonly string[], token: string, options: PullRequestFetchOptions = {}): Promise<PullRequestLabelDetails> {
+  validateGitHubRepository(repository);
+  pullRequestNumberField(number);
+  const wanted = [...new Set(labels.map((label) => label.trim()).filter(Boolean))];
+  if (wanted.length === 0 || wanted.length > PULL_REQUEST_LABEL_LIMIT) throw new Error(`labels must name 1 to ${PULL_REQUEST_LABEL_LIMIT} labels.`);
+  const found = await postGraphQL(PULL_REQUEST_EXISTS_QUERY, { owner: repository.owner, repo: repository.repo, number }, token, options, "GitHub pull request");
+  requirePullRequestNode(found, repository, number);
+  await Promise.all(wanted.map((label) => requireExistingLabel(repository, label, token, options)));
+  const url = `${GITHUB_API_BASE_URL}/repos/${encodePathSegment(repository.owner)}/${encodePathSegment(repository.repo)}/issues/${number}/labels`;
+  const response = await fetchGitHubResponse(requireFetchImplementation(options.fetchImpl ?? globalThis.fetch), url, {
+    method: "POST", headers: gitHubJsonHeaders(token), body: JSON.stringify({ labels: wanted }), signal: options.signal,
+  }, "GitHub pull request labeling failed", token);
+  if (!response.ok) throw new Error(`GitHub pull request labeling returned HTTP ${response.status}.`);
+  const text = await readBoundedResponseText(response, options.signal, PULL_REQUEST_FEEDBACK_RESPONSE_LIMIT_BYTES);
+  const payload: unknown = parseGitHubJson(text.text, "GitHub pull request labels response", token);
+  const after = Array.isArray(payload) ? payload.filter(isRecord).map((label) => safeText(label.name, token, 100)).filter(Boolean) : [];
+  return { action: "label_pull_request", repository, number, added: wanted, labels: after };
+}
+
+export function formatPullRequestLabel(details: PullRequestLabelDetails): string {
+  return `Labeled PR #${details.number} with ${details.added.join(", ")}; labels now: ${details.labels.join(", ") || "none"}.`;
+}

package/src/tools/workflow-tools.ts

@@ -3,12 +3,16 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import {
   CONCLUDE_MERGE_TOOL_NAME, GIT_CONTEXT_VALUE_LIMIT_CHARS, PULL_REQUEST_FEEDBACK_TOOL_NAME, PULL_REQUEST_REPLY_BODY_LIMIT_CHARS,
-  PULL_REQUEST_STATUS_TOOL_NAME, REPLY_PULL_REQUEST_FEEDBACK_TOOL_NAME, TRACK_BRANCH_TOOL_NAME, UPDATE_FROM_BASE_TOOL_NAME,
+  LABEL_PULL_REQUEST_TOOL_NAME, PULL_REQUEST_FILES_TOOL_NAME, PULL_REQUEST_LABEL_LIMIT, PULL_REQUEST_STATUS_TOOL_NAME,
+  REPLY_PULL_REQUEST_FEEDBACK_TOOL_NAME, TRACK_BRANCH_TOOL_NAME, UPDATE_FROM_BASE_TOOL_NAME,
 } from "../constants.ts";
 import { getGitRoot, requireCurrentBranch, safeWorktreeValue } from "../git.ts";
 import { concludeMerge, formatConflictPathList } from "../git-integration.ts";
 import { findGitHubPullRequest, getGitHubPullRequest, resolveGitHubRepository, resolveGitHubToken } from "../github.ts";
-import { formatPullRequestFeedback, formatPullRequestReply, getPullRequestFeedback, replyPullRequestFeedback } from "../github-feedback.ts";
+import {
+  formatPullRequestFeedback, formatPullRequestFiles, formatPullRequestLabel, formatPullRequestReply, getPullRequestFeedback,
+  getPullRequestFiles, labelPullRequest, replyPullRequestFeedback,
+} from "../github-feedback.ts";
 import type { ConcludeMergeDetails, PullRequestStatusDetails } from "../types.ts";
 import type { BranchMeToolOptions } from "./branchme-tools.ts";
 import { trackBranch, updateFromBase, type UpdateFromBaseDetails } from "../git-workflow.ts";
@@ -146,6 +150,47 @@ export function registerWorkflowTools(pi: Pick<ExtensionAPI, "registerTool" | "e
       return { content: [{ type: "text", text: formatPullRequestReply(details) }], details };
     },
   });
+  pi.registerTool({
+    name: PULL_REQUEST_FILES_TOOL_NAME,
+    label: "Pull Request Files",
+    description: "pull_request_files lists the changed files of a pull request of this GitHub repository (path, change type, additions, deletions; the first 100, with a count of the rest) and its current labels. No mutations.",
+    promptSnippet: "pull_request_files: list a PR's changed files and current labels",
+    promptGuidelines: [
+      "Use pull_request_files to see which areas of the repository a pull request touches, for example before choosing its labels.",
+      "pull_request_files never reads file contents or diffs, and never changes the pull request.",
+    ],
+    parameters: Type.Object({
+      number: Type.Integer({ minimum: 1, description: "PR number." }),
+    }, { additionalProperties: false }),
+    async execute(_id, params, signal, _update, ctx) {
+      const rootCtx = { cwd: await getGitRoot(pi, ctx, signal) };
+      const repository = await resolveGitHubRepository(pi, rootCtx, signal, options.env);
+      const token = (await resolveGitHubToken(options.env, { cwd: rootCtx.cwd, signal })).token;
+      const details = await getPullRequestFiles(repository, params.number, token, { fetchImpl: options.fetchImpl, signal });
+      return { content: [{ type: "text", text: formatPullRequestFiles(details) }], details };
+    },
+  });
+  pi.registerTool({
+    name: LABEL_PULL_REQUEST_TOOL_NAME,
+    label: "Label Pull Request",
+    description: "label_pull_request adds labels that already exist in this GitHub repository to one of its pull requests (1 to 5 per call). A label that does not exist is refused before anything changes; existing labels on the pull request stay.",
+    promptSnippet: "label_pull_request: add existing repository labels to a PR",
+    promptGuidelines: [
+      "Use label_pull_request only with label names the assignment or the repository's labels name exactly; it never creates, renames or removes labels.",
+      "label_pull_request adds labels and keeps the pull request's existing ones.",
+    ],
+    parameters: Type.Object({
+      number: Type.Integer({ minimum: 1, description: "PR number." }),
+      labels: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: PULL_REQUEST_LABEL_LIMIT, description: "Exact names of existing labels." }),
+    }, { additionalProperties: false }),
+    async execute(_id, params, signal, _update, ctx) {
+      const rootCtx = { cwd: await getGitRoot(pi, ctx, signal) };
+      const repository = await resolveGitHubRepository(pi, rootCtx, signal, options.env);
+      const token = (await resolveGitHubToken(options.env, { cwd: rootCtx.cwd, signal })).token;
+      const details = await labelPullRequest(repository, params.number, params.labels, token, { fetchImpl: options.fetchImpl, signal });
+      return { content: [{ type: "text", text: formatPullRequestLabel(details) }], details };
+    },
+  });
   pi.registerTool({
     name: UPDATE_FROM_BASE_TOOL_NAME,
     label: "Update From Base",

package/src/types.ts

@@ -660,6 +660,24 @@ export interface PullRequestFeedbackDetails {
   omitted: { threads: number; comments: number; checks: number };
 }
 
+export interface PullRequestFilesDetails {
+  action: "pull_request_files";
+  repository: GitHubRepository;
+  number: number;
+  labels: string[];
+  files: { path: string; change: string; additions: number; deletions: number }[];
+  omitted: number;
+}
+
+export interface PullRequestLabelDetails {
+  action: "label_pull_request";
+  repository: GitHubRepository;
+  number: number;
+  added: string[];
+  /** Every label on the pull request after the call. */
+  labels: string[];
+}
+
 export interface PullRequestReplyInput {
   number: number;
   body: string;