@senad-d/branchme 0.3.5 → 0.3.8

package/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 
-## 0.3.5 - Unreleased
+## 0.3.8 - Unreleased
+
+- Resolved four Sonar maintainability findings: fetch the bounded failing-job logs concurrently and simplify feedback formatting by extracting nested template literals.
+
+## 0.3.7 - Unreleased
+
+- Added read-only `pull_request_feedback`: one GraphQL request returns a same-repository PR's unresolved, current review threads with their comments (resolved and outdated threads counted only), review summaries with a body or requested changes, the latest 50 conversation comments, and the head commit's failing checks; for up to three failing GitHub Actions jobs it adds the log lines leading to the last `##[error]`. Agents that address PR feedback no longer need `gh pr view`, `gh api` or `gh run view`.
+
+## 0.3.6 - Unreleased
+
+- Resolved Sonar maintainability findings by using a set for integration-branch membership and non-mutating sorting for changed worktree paths.
+
+- `create_branch`, `change_branch`, `pull_branch` and `push_branch` receipts carry the resulting full HEAD (`head`); `push_branch` also names the remote-tracking ref it updated (`remoteTrackingRef`) and its commit after the push (`remoteHead`), and the text result says whether it matches the local HEAD. A caller no longer needs `branch_status` after these calls to learn or prove the HEAD.
+## 0.3.5 - Released
 
 - `push_branch` never pushes onto a differently named integration branch: when the current branch's upstream is `main`, `master`, `trunk`, `develop`, or the origin default branch under another name (a feature branch created from `origin/main` with tracking), it publishes to the same-named branch on that remote with `--set-upstream`, reports `mode: "publish"`, and keeps the previous upstream in `upstream`. Previously such a branch was pushed straight onto the integration branch. Other differently named upstreams keep their explicit `HEAD:<upstream-ref>` push.
 - Added optional `remove_worktree.discardChanges` (default `false`, unchanged behavior). When `true`, the user's explicit authorization, a worktree with staged, unstaged, untracked, or unmerged changes is removed with `git worktree remove --force` and the result lists every discarded path in `discardedPaths`; without it a dirty worktree is still refused, now naming the option. Locked, detached, main, current, prunable, missing, and foreign worktrees stay rejected, and the local branch is retained.

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-one 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, and create GitHub pull requests.
+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-two 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, and create GitHub pull requests.
 
 <table align="center">
   <tr>
@@ -184,7 +184,7 @@ git remote set-url origin git@github.com:OWNER/REPO.git
 export GITHUB_REPOSITORY=OWNER/REPO
 ```
 
-For automatic related-PR lookup, `pull_request_status`, PR-aware `land_branch`, and `pull_request`, set a token in the process environment before starting pi:
+For automatic related-PR lookup, `pull_request_status`, `pull_request_feedback`, PR-aware `land_branch`, and `pull_request`, set a token in the process environment before starting pi:
 
 ```bash
 export GITHUB_TOKEN=github_pat_...
@@ -214,7 +214,7 @@ BranchMe has no separate project config file. It reads process environment varia
 
 | Variable | Meaning |
 | --- | --- |
-| `GITHUB_TOKEN` | Preferred token for automatic related-PR lookup, `pull_request_status`, PR-aware `land_branch`, and `pull_request`; process environment first, then local `.env` fallback. |
+| `GITHUB_TOKEN` | Preferred token for automatic related-PR lookup, `pull_request_status`, `pull_request_feedback`, PR-aware `land_branch`, and `pull_request`; process environment first, then local `.env` fallback. |
 | `GH_TOKEN` | Fallback token for the same GitHub API operations; process environment first, then local `.env` fallback. |
 | `BRANCHME_PR_AUTOFILL=true` | Allow `pull_request` to fill omitted PR fields. Accepts `true`/`false`, `1`/`0`, `yes`/`no`, or `on`/`off`; disabled by default. |
 | `GITHUB_REPOSITORY=owner/repo` | Optional CI fallback and boundary check for the current GitHub repository; process environment only. |
@@ -257,6 +257,7 @@ 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_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. 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. |
 | `init_repository` | `{ "initialBranch"?: string }` | Initializes only pi's exact current working directory as a verified non-bare Git repository with an unborn branch (default `main`). Rejects existing or nested repositories and accepts no path, bare, template, shared, remote, commit, or project-file controls. |
 | `branch_status` | `{ "ancestry"?: { "sourceBranch": string, "targetBranch": string } }` | Explicitly refreshes the same bounded context used at agent start. An optional strict ancestry query captures both exact HEADs and reports whether the source commit is an ancestor of the target commit; each endpoint may be an exact local branch or a remote-tracking ref such as `origin/main` (a local branch of the same name takes precedence). It is read-only and never checks out or resets remote-tracking refs; automatic Git context does not run ancestry queries. |
@@ -564,7 +565,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-one 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-two 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-one strict agent-callable tools.
+- Tool count: twenty-two strict agent-callable tools.
 
 ## 3. Users and use cases
 
@@ -56,6 +56,7 @@ Originally approved on 2026-06-30. Updated to describe the implemented `0.3.1` p
 | Tool | `update_from_base` | Fetch and merge an explicit remote base | Preserves published history; fixed merge policy, listed conflict paths, automatic abort unless `keepConflicts` |
 | 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 Actions log tails; read-only |
 | 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 |
 | Tool | `integrate_branch` | Integrate one exact local source into the already-current clean local target | Fixed normal-merge policy; verified automatic abort/restoration on conflict |
@@ -95,7 +96,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-one tools, and automatic context hook.
+  - The extension entry point registers the informational command, twenty-two 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-one tools—`fetch_remote`, `list_branches`, `track_branch`, `update_from_base`, `conclude_merge`, `pull_request_status`, `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-two tools—`fetch_remote`, `list_branches`, `track_branch`, `update_from_base`, `conclude_merge`, `pull_request_status`, `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.
 - 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-one 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-two 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

@@ -28,7 +28,7 @@ src/
 
 ## Module boundaries
 
-1. `src/extension.ts` stays small and registers the command, twenty-one tools, and one `before_agent_start` context hook.
+1. `src/extension.ts` stays small and registers the command, twenty-two 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.
@@ -86,7 +86,7 @@ src/
 - `pull_request` reads `GITHUB_TOKEN` or `GH_TOKEN` from process environment first; only when neither process token is set does it read those token keys from a small regular `.env` file in the verified git root as a fallback. `BRANCHME_PR_AUTOFILL` uses the same process-first, `.env`-fallback precedence and defaults off.
 - BranchMe does not force checkout/removal, move/prune/repair/lock/unlock worktrees, create detached/orphan worktrees, infer remote worktree branches, copy ignored/untracked files such as `.env`, delete ignored worktree residue through standalone `remove_worktree` without explicit `deleteIgnored: true` authorization, delete retained worktree branches during standalone removal, change Pi's cwd, or start Pi sessions. It also does not stash, create user-authored commits, accept commit messages, reset, force-push, directly edit project files, read unsupported `.env` keys, follow unsafe `.env` file types, depend on GitHub CLI, or collect telemetry. Explicit `integrate_branch`, `update_from_base`, and `conclude_merge` may let Git create a standard merge commit for divergent histories; `conclude_merge` is the only tool that stages, and only the formerly unmerged paths; only explicit leased `retire_branch` or merged-only `land_branch` may delete one exact local branch ref. Retirement has no bulk, inferred-target, remote, remote-tracking, rollback, or automatic worktree deletion. Git documents submodule worktree support as incomplete; BranchMe adds no force-based submodule cleanup.
 
-`list_branches` returns bounded display metadata, including cached upstream counts and occupancy; optional kind and Git branch-list patterns filter before raw/entry limits and display redaction. `{}` preserves the full cached inventory, and automatic context is unchanged. For unknown issue branches, run `fetch_remote` separately and wait before listing. `pull_request_status` reads exact-number or latest-head PR state, not CI/review requirements. `pull_request` reuses matching open PRs without overwriting their metadata. PR-aware landing verifies repository/remote identity, exact merged head/base, and merge-commit containment before allowing non-ancestor local retirement; it retains the expected-HEAD lease and reports graph ancestry separately from host evidence.
+`list_branches` returns bounded display metadata, including cached upstream counts and occupancy; optional kind and Git branch-list patterns filter before raw/entry limits and display redaction. `{}` preserves the full cached inventory, and automatic context is unchanged. For unknown issue branches, run `fetch_remote` separately and wait before listing. `pull_request_status` reads exact-number or latest-head PR state, not CI/review requirements. `pull_request_feedback` (in `src/github-feedback.ts`) reads unresolved review threads, review summaries, conversation comments and failing checks with Actions log tails. `pull_request` reuses matching open PRs without overwriting their metadata. PR-aware landing verifies repository/remote identity, exact merged head/base, and merge-commit containment before allowing non-ancestor local retirement; it retains the expected-HEAD lease and reports graph ancestry separately from host evidence.
 
 ## Documentation
 

package/docs/TUI_CAPTURE.md

@@ -42,6 +42,7 @@ Commands only show info; BranchMe tools perform actions.
 - `update_from_base` — fetch and merge an explicit base into the current clean feature, preserving published history and upstream; a conflict is aborted unless `keepConflicts: true` leaves it in progress.
 - `conclude_merge` — `action: "conclude"` commits the kept merge once every conflict marker is removed; `action: "abort"` restores the branch.
 - `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.
 - `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.5",
+  "version": "0.3.8",
   "type": "module",
   "description": "Pi extension for verified Git repository initialization, branch, worktree, integration, retirement, push, and pull request workflows.",
   "license": "MIT",

package/src/commands/branchme-command.ts

@@ -51,6 +51,7 @@ export function getBranchMeHelpText(): string {
     "- `update_from_base` — fetch and merge an explicit base into the current clean feature, preserving published history and upstream; a conflict is aborted unless `keepConflicts: true` leaves it in progress.",
     "- `conclude_merge` — `action: \"conclude\"` commits the kept merge once every conflict marker is removed; `action: \"abort\"` restores the branch.",
     "- `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.",
     "- `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

@@ -16,6 +16,7 @@ export const REBASE_BRANCH_TOOL_NAME = "rebase_branch";
 export const PUSH_BRANCH_TOOL_NAME = "push_branch";
 export const PULL_REQUEST_TOOL_NAME = "pull_request";
 export const PULL_REQUEST_STATUS_TOOL_NAME = "pull_request_status";
+export const PULL_REQUEST_FEEDBACK_TOOL_NAME = "pull_request_feedback";
 export const LIST_WORKTREES_TOOL_NAME = "list_worktrees";
 export const CREATE_WORKTREE_TOOL_NAME = "create_worktree";
 export const REMOVE_WORKTREE_TOOL_NAME = "remove_worktree";
@@ -43,6 +44,7 @@ export const BRANCHME_TOOL_NAMES = [
   PUSH_BRANCH_TOOL_NAME,
   PULL_REQUEST_TOOL_NAME,
   PULL_REQUEST_STATUS_TOOL_NAME,
+  PULL_REQUEST_FEEDBACK_TOOL_NAME,
   LIST_WORKTREES_TOOL_NAME,
   CREATE_WORKTREE_TOOL_NAME,
   REMOVE_WORKTREE_TOOL_NAME,
@@ -86,3 +88,12 @@ export const GITHUB_USER_AGENT = "BranchMe Pi extension";
 
 export const MAX_SUMMARY_OUTPUT_CHARS = 4_000;
 export const GITHUB_RESPONSE_BODY_LIMIT_BYTES = 64 * 1024;
+export const PULL_REQUEST_FEEDBACK_RESPONSE_LIMIT_BYTES = 1024 * 1024;
+export const PULL_REQUEST_FEEDBACK_LOG_TAIL_BYTES = 128 * 1024;
+export const PULL_REQUEST_FEEDBACK_LOG_TAIL_LINES = 60;
+export const PULL_REQUEST_FEEDBACK_LOG_JOB_LIMIT = 3;
+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 GITHUB_GRAPHQL_TIMEOUT_MS = 15_000;
+export const GITHUB_JOB_LOG_TIMEOUT_MS = 30_000;

package/src/git.ts

@@ -563,7 +563,7 @@ async function resolvePushTarget(
   };
 }
 
-const INTEGRATION_BRANCH_NAMES = ["main", "master", "trunk", "develop"];
+const INTEGRATION_BRANCH_NAMES = new Set(["main", "master", "trunk", "develop"]);
 
 async function isIntegrationBranch(
   pi: Pick<ExtensionAPI, "exec">,
@@ -573,7 +573,7 @@ async function isIntegrationBranch(
   signal?: AbortSignal,
 ): Promise<boolean> {
   const branch = remoteRef.slice("refs/heads/".length);
-  if (INTEGRATION_BRANCH_NAMES.includes(branch)) return true;
+  if (INTEGRATION_BRANCH_NAMES.has(branch)) return true;
   return remote === "origin" && branch === await getOriginDefaultBranch(pi, ctx, signal);
 }
 
@@ -1828,7 +1828,7 @@ function parseWorktreeRemovalStatus(output: string): WorktreeRemovalStatus {
   return {
     workingTree: parseWorkingTreeStatus(output).workingTree,
     ignoredPaths: [...ignoredPaths].sort(compareIgnoredPaths),
-    changedPaths: changedPaths.sort(compareIgnoredPaths),
+    changedPaths: [...changedPaths].sort(compareIgnoredPaths),
   };
 }
 
@@ -2687,8 +2687,9 @@ export async function createLocalBranch(
       signal,
       timeout: GIT_MUTATION_TIMEOUT_MS,
     });
+    const head = await getVerifiedRefCommit(pi, rootCtx, "HEAD", "HEAD", signal);
 
-    return { repoRoot, previousBranch: safeDetail(previousBranch), newBranch: safeDetail(branchName) };
+    return { repoRoot, previousBranch: safeDetail(previousBranch), newBranch: safeDetail(branchName), head };
   });
 }
 
@@ -2726,6 +2727,7 @@ export async function changeExistingLocalBranch(
     if (current.detached || current.currentBranch !== branchName) {
       throw new Error(`git switch did not end on branch '${redactSecrets(branchName)}'.`);
     }
+    const head = await getVerifiedRefCommit(pi, rootCtx, "HEAD", "HEAD", signal);
 
     return {
       repoRoot,
@@ -2733,6 +2735,7 @@ export async function changeExistingLocalBranch(
       previousDetached: previous.detached,
       currentBranch: safeDetail(current.currentBranch),
       hasChangesBeforeSwitch: false,
+      head,
     };
   });
 }
@@ -2882,6 +2885,7 @@ export async function pullCurrentBranch(
       signal,
       timeout: GIT_PULL_TIMEOUT_MS,
     });
+    const head = await getVerifiedRefCommit(pi, rootCtx, "HEAD", "HEAD", signal);
 
     return {
       repoRoot,
@@ -2890,6 +2894,7 @@ export async function pullCurrentBranch(
       remote: safeDetail(target.remote),
       remoteRef: safeDetail(target.remoteRef),
       output: safeOutput(result.stdout || result.stderr),
+      head,
     };
   });
 }
@@ -2981,6 +2986,11 @@ export async function pushCurrentBranch(
       signal,
       timeout: GIT_PUSH_TIMEOUT_MS,
     });
+    // The push updated the remote-tracking ref of the pushed branch; reading it
+    // back is the remote-visible HEAD the receipt proves, without another fetch.
+    const remoteTrackingRef = `${target.remote}/${target.remoteRef.replace(/^refs\/heads\//u, "")}`;
+    const head = await getVerifiedRefCommit(pi, rootCtx, "HEAD", "HEAD", signal);
+    const remoteHead = await getRemoteTrackingRefCommit(pi, rootCtx, remoteTrackingRef, signal);
 
     return {
       repoRoot,
@@ -2991,6 +3001,9 @@ export async function pushCurrentBranch(
       remoteRef: safeDetail(target.remoteRef),
       refspec: safeDetail(target.refspec),
       output: safeOutput(result.stdout || result.stderr),
+      head,
+      remoteTrackingRef: safeDetail(remoteTrackingRef),
+      remoteHead,
     };
   });
 }

package/src/github-feedback.ts

@@ -0,0 +1,252 @@
+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,
+} from "./constants.ts";
+import {
+  encodePathSegment, fetchGitHubResponse, gitHubJsonHeaders, isRecord, parseGitHubJson, pullRequestNumberField,
+  readBoundedResponseText, requireFetchImplementation, requireGitHubResponseObject, validateGitHubRepository,
+  type PullRequestFetchOptions,
+} from "./github.ts";
+import { redactSecrets } from "./redaction.ts";
+import type {
+  GitHubRepository, PullRequestFeedbackCheck, PullRequestFeedbackComment, PullRequestFeedbackDetails,
+  PullRequestFeedbackReview, PullRequestFeedbackThread,
+} from "./types.ts";
+
+// One GraphQL request reads review threads with their resolution state, review summaries, conversation
+// comments and the head commit's check rollup; REST has no thread resolution state.
+const FEEDBACK_QUERY = `query($owner: String!, $repo: String!, $number: Int!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $number) {
+      number url headRefOid
+      reviewThreads(first: 100) { totalCount nodes { isResolved isOutdated path line comments(first: 20) { nodes { author { login } body url } } } }
+      reviews(last: 50) { nodes { author { login } state body url } }
+      comments(last: 50) { totalCount nodes { author { login } body url } }
+      commits(last: 1) { nodes { commit { statusCheckRollup { state contexts(first: 100) { totalCount nodes {
+        __typename
+        ... on CheckRun { name conclusion databaseId detailsUrl }
+        ... on StatusContext { context state targetUrl }
+      } } } } } }
+    }
+  }
+}`;
+
+const FAILING_CHECK_CONCLUSIONS = new Set(["FAILURE", "TIMED_OUT", "STARTUP_FAILURE", "ACTION_REQUIRED", "CANCELLED"]);
+const FAILING_STATUS_STATES = new Set(["FAILURE", "ERROR"]);
+const ANSI_ESCAPE_PATTERN = /\u001b\[[0-9;]*[A-Za-z]/gu;
+const LOG_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z ?/u;
+const UNSAFE_TEXT_PATTERN = /[\p{Cc}\p{Cf}\u2028\u2029]/gu;
+
+function safeText(value: unknown, token: string, limit: number): string {
+  if (typeof value !== "string") return "";
+  const text = redactSecrets(value, [token]).replace(UNSAFE_TEXT_PATTERN, (character) => (character === "\n" ? "\n" : " ")).trim();
+  return text.length <= limit ? text : `${text.slice(0, limit - 1)}…`;
+}
+
+function nodes(connection: unknown): Record<string, unknown>[] {
+  if (!isRecord(connection) || !Array.isArray(connection.nodes)) return [];
+  return connection.nodes.filter(isRecord);
+}
+
+function totalCount(connection: unknown): number {
+  return isRecord(connection) && typeof connection.totalCount === "number" ? connection.totalCount : 0;
+}
+
+function parseComment(node: Record<string, unknown>, token: string): PullRequestFeedbackComment {
+  const author = isRecord(node.author) ? safeText(node.author.login, token, 100) : "";
+  return {
+    author: author || "ghost",
+    body: safeText(node.body, token, PULL_REQUEST_FEEDBACK_BODY_LIMIT_CHARS),
+    url: safeText(node.url, token, 300),
+  };
+}
+
+function parseThreads(connection: unknown, token: string): Pick<PullRequestFeedbackDetails, "unresolvedThreads" | "resolvedThreadCount" | "outdatedThreadCount"> {
+  const unresolvedThreads: PullRequestFeedbackThread[] = [];
+  let resolvedThreadCount = 0;
+  let outdatedThreadCount = 0;
+  for (const thread of nodes(connection)) {
+    if (thread.isResolved === true) resolvedThreadCount += 1;
+    else if (thread.isOutdated === true) outdatedThreadCount += 1;
+    else {
+      unresolvedThreads.push({
+        path: safeText(thread.path, token, 300),
+        line: typeof thread.line === "number" ? thread.line : null,
+        comments: nodes(thread.comments).map((comment) => parseComment(comment, token)),
+      });
+    }
+  }
+  return { unresolvedThreads, resolvedThreadCount, outdatedThreadCount };
+}
+
+function parseReviews(connection: unknown, token: string): PullRequestFeedbackReview[] {
+  return nodes(connection)
+    .map((review) => ({ ...parseComment(review, token), state: safeText(review.state, token, 40) }))
+    .filter((review) => review.body !== "" || review.state === "CHANGES_REQUESTED");
+}
+
+function parseCheck(node: Record<string, unknown>, token: string): PullRequestFeedbackCheck | null {
+  if (node.__typename === "CheckRun") {
+    const conclusion = typeof node.conclusion === "string" ? node.conclusion : "";
+    if (!FAILING_CHECK_CONCLUSIONS.has(conclusion)) return null;
+    const detailsUrl = safeText(node.detailsUrl, token, 300);
+    const isActionsJob = detailsUrl.includes("/actions/runs/") && typeof node.databaseId === "number";
+    return { name: safeText(node.name, token, 200), conclusion, url: detailsUrl, jobId: isActionsJob ? node.databaseId as number : null };
+  }
+  const state = typeof node.state === "string" ? node.state : "";
+  if (!FAILING_STATUS_STATES.has(state)) return null;
+  return { name: safeText(node.context, token, 200), conclusion: state, url: safeText(node.targetUrl, token, 300), jobId: null };
+}
+
+async function postFeedbackQuery(repository: GitHubRepository, number: number, token: string, options: PullRequestFetchOptions): Promise<Record<string, unknown>> {
+  const controller = new AbortController();
+  const timer = setTimeout(controller.abort.bind(controller), GITHUB_GRAPHQL_TIMEOUT_MS);
+  const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+  try {
+    const response = await fetchGitHubResponse(requireFetchImplementation(options.fetchImpl ?? globalThis.fetch), `${GITHUB_API_BASE_URL}/graphql`, {
+      method: "POST",
+      headers: gitHubJsonHeaders(token),
+      body: JSON.stringify({ query: FEEDBACK_QUERY, variables: { owner: repository.owner, repo: repository.repo, number } }),
+      signal,
+    }, "GitHub pull request feedback lookup failed", token);
+    if (!response.ok) throw new Error(`GitHub pull request feedback lookup returned HTTP ${response.status}.`);
+    const body = await readBoundedResponseText(response, signal, PULL_REQUEST_FEEDBACK_RESPONSE_LIMIT_BYTES);
+    if (body.truncated) throw new Error("GitHub pull request feedback exceeded the response byte limit.");
+    const payload = requireGitHubResponseObject(parseGitHubJson(body.text, "GitHub pull request feedback response", token), "Pull request feedback");
+    if (Array.isArray(payload.errors) && payload.errors.length > 0) {
+      const messages = payload.errors.map((error) => (isRecord(error) ? safeText(error.message, token, 300) : "")).filter(Boolean);
+      throw new Error(`GitHub pull request feedback query failed: ${messages.join("; ") || "unknown GraphQL error"}`);
+    }
+    return payload;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function readResponseTail(response: Response, signal: AbortSignal): Promise<string> {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  let tail = Buffer.alloc(0);
+  try {
+    while (true) {
+      signal.throwIfAborted();
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value || value.byteLength === 0) continue;
+      tail = Buffer.concat([tail, Buffer.from(value)]);
+      if (tail.byteLength > PULL_REQUEST_FEEDBACK_LOG_TAIL_BYTES) tail = tail.subarray(tail.byteLength - PULL_REQUEST_FEEDBACK_LOG_TAIL_BYTES);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return tail.toString("utf8");
+}
+
+// Keep the lines leading up to the last error annotation; without one, the end of the log.
+export function extractLogTail(log: string, token: string): string {
+  const lines = log.split(/\r?\n/u).map((line) => line.replace(ANSI_ESCAPE_PATTERN, "").replace(LOG_TIMESTAMP_PATTERN, "")).filter((line) => line.trim() !== "");
+  let end = lines.length;
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    if (lines[index].includes("##[error]")) {
+      end = index + 1;
+      break;
+    }
+  }
+  const excerpt = lines.slice(Math.max(0, end - PULL_REQUEST_FEEDBACK_LOG_TAIL_LINES), end).join("\n");
+  const text = safeText(excerpt, token, Number.MAX_SAFE_INTEGER);
+  return text.length <= PULL_REQUEST_FEEDBACK_LOG_LIMIT_CHARS ? text : `…${text.slice(text.length - PULL_REQUEST_FEEDBACK_LOG_LIMIT_CHARS + 1)}`;
+}
+
+async function attachJobLog(repository: GitHubRepository, check: PullRequestFeedbackCheck, token: string, options: PullRequestFetchOptions): Promise<void> {
+  const controller = new AbortController();
+  const timer = setTimeout(controller.abort.bind(controller), GITHUB_JOB_LOG_TIMEOUT_MS);
+  const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+  try {
+    const url = `${GITHUB_API_BASE_URL}/repos/${encodePathSegment(repository.owner)}/${encodePathSegment(repository.repo)}/actions/jobs/${check.jobId}/logs`;
+    const response = await fetchGitHubResponse(requireFetchImplementation(options.fetchImpl ?? globalThis.fetch), url, {
+      method: "GET", headers: gitHubJsonHeaders(token), signal,
+    }, "GitHub job log lookup failed", token);
+    if (!response.ok) {
+      check.logError = `job log returned HTTP ${response.status}`;
+      return;
+    }
+    check.logTail = extractLogTail(await readResponseTail(response, signal), token);
+  } catch (error) {
+    check.logError = safeText(error instanceof Error ? error.message : String(error), token, 300);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function getPullRequestFeedback(repository: GitHubRepository, number: number, token: string, options: PullRequestFetchOptions = {}): Promise<PullRequestFeedbackDetails> {
+  validateGitHubRepository(repository);
+  pullRequestNumberField(number);
+  const payload = await postFeedbackQuery(repository, number, token, options);
+  const data = isRecord(payload.data) ? payload.data : {};
+  const pullRequest = isRecord(data.repository) && isRecord(data.repository.pullRequest) ? data.repository.pullRequest : null;
+  if (!pullRequest) throw new Error(`Pull request #${number} was not found in ${repository.owner}/${repository.repo}.`);
+  if (pullRequestNumberField(pullRequest.number) !== number) throw new Error("GitHub returned a different pull request number.");
+
+  const commit = nodes(pullRequest.commits)[0];
+  const rollup = isRecord(commit?.commit) && isRecord(commit.commit.statusCheckRollup) ? commit.commit.statusCheckRollup : null;
+  const contexts = rollup ? nodes(rollup.contexts) : [];
+  const failingChecks = contexts.map((node) => parseCheck(node, token)).filter((check): check is PullRequestFeedbackCheck => check !== null);
+  // ponytail: logs for the first few failing Actions jobs only; raise the limit if wide matrices hide the cause.
+  const logChecks = failingChecks.filter((item) => item.jobId !== null).slice(0, PULL_REQUEST_FEEDBACK_LOG_JOB_LIMIT);
+  await Promise.all(logChecks.map((check) => attachJobLog(repository, check, token, options)));
+
+  const threadNodes = nodes(pullRequest.reviewThreads);
+  const commentNodes = nodes(pullRequest.comments);
+  return {
+    repository,
+    number,
+    url: safeText(pullRequest.url, token, 300),
+    headSha: safeText(pullRequest.headRefOid, token, 64),
+    checksState: rollup ? safeText(rollup.state, token, 40) : null,
+    ...parseThreads(pullRequest.reviewThreads, token),
+    reviews: parseReviews(pullRequest.reviews, token),
+    comments: commentNodes.map((comment) => parseComment(comment, token)).filter((comment) => comment.body !== ""),
+    failingChecks,
+    omitted: {
+      threads: Math.max(0, totalCount(pullRequest.reviewThreads) - threadNodes.length),
+      comments: Math.max(0, totalCount(pullRequest.comments) - commentNodes.length),
+      checks: rollup ? Math.max(0, totalCount(rollup.contexts) - contexts.length) : 0,
+    },
+  };
+}
+
+function indent(text: string): string {
+  return text.split("\n").map((line) => `    ${line}`).join("\n");
+}
+
+function formatThread(thread: PullRequestFeedbackThread): string {
+  const location = thread.line === null ? thread.path : `${thread.path}:${thread.line}`;
+  return [`- ${location}`, ...thread.comments.map((comment) => `  @${comment.author}: ${comment.body}`)].join("\n");
+}
+
+function formatCheck(check: PullRequestFeedbackCheck): string {
+  const lines = [`- ${check.name}: ${check.conclusion} ${check.url}`.trimEnd()];
+  if (check.logTail) lines.push(`  Log tail (job ${check.jobId}):`, indent(check.logTail));
+  if (check.logError) lines.push(`  Log unavailable: ${check.logError}`);
+  return lines.join("\n");
+}
+
+export function formatPullRequestFeedback(details: PullRequestFeedbackDetails): string {
+  const omittedThreads = details.omitted.threads ? `; ${details.omitted.threads} beyond the first 100 not read` : "";
+  const omittedComments = details.omitted.comments ? ` (latest 50; ${details.omitted.comments} older not read)` : "";
+  const omittedChecks = details.omitted.checks ? ` (${details.omitted.checks} checks beyond the first 100 not read)` : "";
+  const sections = [
+    `PR #${details.number} feedback at head ${details.headSha.slice(0, 12)}; checks ${details.checksState ?? "not reported"}. ${details.url}`,
+    `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) => `- @${review.author} ${review.state}: ${review.body}`),
+    `Conversation comments: ${details.comments.length}${omittedComments}.`,
+    ...details.comments.map((comment) => `- @${comment.author}: ${comment.body}`),
+    `Failing checks: ${details.failingChecks.length}${omittedChecks}.`,
+    ...details.failingChecks.map(formatCheck),
+  ];
+  const text = sections.join("\n");
+  return text.length <= PULL_REQUEST_FEEDBACK_SUMMARY_LIMIT_CHARS ? text : `${text.slice(0, PULL_REQUEST_FEEDBACK_SUMMARY_LIMIT_CHARS - 40)}\n… [truncated; full data in details]`;
+}

package/src/github.ts

@@ -380,7 +380,7 @@ function truncate(value: string): string {
 
 export { redactSecrets } from "./redaction.ts";
 
-function encodePathSegment(value: string): string {
+export function encodePathSegment(value: string): string {
   return encodeURIComponent(value);
 }
 
@@ -433,7 +433,7 @@ function validatePullRequestInput(input: unknown): asserts input is PullRequestI
   if (typeof input.draft !== "boolean") throw new Error("draft must be a boolean.");
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
+export function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
@@ -442,7 +442,7 @@ function stringField(value: unknown, field: string): string {
   return value;
 }
 
-function pullRequestNumberField(value: unknown): number {
+export function pullRequestNumberField(value: unknown): number {
   if (typeof value !== "number" || !Number.isFinite(value) || !Number.isSafeInteger(value) || value <= 0) {
     throw new Error("GitHub response pull request number must be a finite positive safe integer.");
   }
@@ -458,7 +458,7 @@ function throwIfResponseReadAborted(signal: AbortSignal | undefined): void {
   if (signal?.aborted) throw new Error("GitHub pull request response read was aborted.");
 }
 
-async function readBoundedResponseText(response: Response, signal: AbortSignal | undefined): Promise<BoundedResponseBody> {
+export async function readBoundedResponseText(response: Response, signal: AbortSignal | undefined, limitBytes = GITHUB_RESPONSE_BODY_LIMIT_BYTES): Promise<BoundedResponseBody> {
   throwIfResponseReadAborted(signal);
   if (!response.body) return { text: "", truncated: false };
 
@@ -474,7 +474,7 @@ async function readBoundedResponseText(response: Response, signal: AbortSignal |
       if (done) break;
       if (!value || value.byteLength === 0) continue;
 
-      const remainingBytes = GITHUB_RESPONSE_BODY_LIMIT_BYTES - capturedBytes;
+      const remainingBytes = limitBytes - capturedBytes;
       if (remainingBytes > 0) {
         const capturedChunk = value.byteLength <= remainingBytes ? value : value.subarray(0, remainingBytes);
         chunks.push(Buffer.from(capturedChunk));
@@ -495,7 +495,7 @@ async function readBoundedResponseText(response: Response, signal: AbortSignal |
   return { text: truncated ? `${text}… [truncated]` : text, truncated };
 }
 
-function gitHubJsonHeaders(token: string): Record<string, string> {
+export function gitHubJsonHeaders(token: string): Record<string, string> {
   return {
     Accept: "application/vnd.github+json",
     Authorization: `Bearer ${token}`,
@@ -505,7 +505,7 @@ function gitHubJsonHeaders(token: string): Record<string, string> {
   };
 }
 
-function requireFetchImplementation(fetchImpl: typeof fetch | undefined): typeof fetch {
+export function requireFetchImplementation(fetchImpl: typeof fetch | undefined): typeof fetch {
   if (typeof fetchImpl !== "function") throw new Error("fetch is unavailable in this Node.js runtime.");
   return fetchImpl;
 }
@@ -515,7 +515,7 @@ function redactedErrorMessage(error: unknown, tokens: readonly string[]): string
   return redactSecrets(message, tokens);
 }
 
-async function fetchGitHubResponse(
+export async function fetchGitHubResponse(
   fetchImpl: typeof fetch,
   url: string,
   init: RequestInit,
@@ -542,7 +542,7 @@ async function readGitHubResponseBody(
   }
 }
 
-function parseGitHubJson(text: string, responseContext: string, token: string): unknown {
+export function parseGitHubJson(text: string, responseContext: string, token: string): unknown {
   try {
     return JSON.parse(text);
   } catch (error) {
@@ -550,7 +550,7 @@ function parseGitHubJson(text: string, responseContext: string, token: string):
   }
 }
 
-function requireGitHubResponseObject(payload: unknown, responseContext: string): Record<string, unknown> {
+export function requireGitHubResponseObject(payload: unknown, responseContext: string): Record<string, unknown> {
   if (!isRecord(payload)) throw new Error(`${responseContext} was not an object.`);
   return payload;
 }

package/src/tools/branchme-tools.ts

@@ -245,7 +245,7 @@ export function formatBranchStatus(details: GitContextDetails): string {
 
 export function formatChangeBranch(details: ChangeBranchDetails): string {
   const previous = details.previousDetached ? "detached HEAD" : details.previousBranch ?? "unknown branch";
-  return `Changed branch from ${previous} to ${details.currentBranch}.`;
+  return `Changed branch from ${previous} to ${details.currentBranch} at ${details.head}.`;
 }
 
 export function formatPullRequest(details: PullRequestToolDetails, autofilledFields: PullRequestInputField[] = []): string {
@@ -641,7 +641,7 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
         content: [
           {
             type: "text",
-            text: `Created and checked out branch ${details.newBranch} from ${details.previousBranch}.`,
+            text: `Created and checked out branch ${details.newBranch} from ${details.previousBranch} at ${details.head}.`,
           },
         ],
         details,
@@ -735,7 +735,7 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
     async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
       const details = await pullCurrentBranch(pi, ctx, signal);
       return {
-        content: [{ type: "text", text: `Pulled current branch ${details.currentBranch} with fast-forward-only semantics.` }],
+        content: [{ type: "text", text: `Pulled current branch ${details.currentBranch} with fast-forward-only semantics; HEAD ${details.head}.` }],
         details,
       };
     },
@@ -846,8 +846,9 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
     async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
       const details = await pushCurrentBranch(pi, ctx, signal);
       const action = details.mode === "publish" ? "Published" : "Pushed";
+      const remoteState = details.remoteHead === details.head ? "matches" : `is at ${details.remoteHead}`;
       return {
-        content: [{ type: "text", text: `${action} current branch ${details.currentBranch}.` }],
+        content: [{ type: "text", text: `${action} current branch ${details.currentBranch} at ${details.head}; ${details.remoteTrackingRef} ${remoteState}.` }],
         details,
       };
     },

package/src/tools/workflow-tools.ts

@@ -2,12 +2,13 @@ import { StringEnum } from "@earendil-works/pi-ai";
 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_STATUS_TOOL_NAME, TRACK_BRANCH_TOOL_NAME,
-  UPDATE_FROM_BASE_TOOL_NAME,
+  CONCLUDE_MERGE_TOOL_NAME, GIT_CONTEXT_VALUE_LIMIT_CHARS, PULL_REQUEST_FEEDBACK_TOOL_NAME, PULL_REQUEST_STATUS_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, getPullRequestFeedback } 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";
@@ -90,6 +91,36 @@ export function registerWorkflowTools(pi: Pick<ExtensionAPI, "registerTool" | "e
       };
     },
   });
+  pi.registerTool({
+    name: PULL_REQUEST_FEEDBACK_TOOL_NAME,
+    label: "Pull Request Feedback",
+    description: "pull_request_feedback reads what a same-repository GitHub PR asks to be fixed: unresolved review threads with their comments, review summaries, conversation comments, and the head commit's failing checks with the log tail of up to three failing GitHub Actions jobs. Resolved and outdated threads are counted, not listed. No mutations.",
+    promptSnippet: "pull_request_feedback: read a PR's unresolved review comments and failing checks with their log tails",
+    promptGuidelines: [
+      "Use pull_request_feedback with number to collect the review comments and failing checks a follow-up must address; number and headBranch are mutually exclusive.",
+      "Without number, pull_request_feedback reads the most recently updated PR for headBranch or the current branch.",
+      "pull_request_feedback never comments, resolves threads, reruns checks, or edits the PR; a job log that cannot be read is reported per check, not as a failure of the call.",
+    ],
+    parameters: Type.Object({
+      number: Type.Optional(Type.Integer({ minimum: 1, description: "Exact PR number; mutually exclusive with headBranch." })),
+      headBranch: Type.Optional(Type.String({ minLength: 1, description: "Head branch to look up; defaults to current branch when number is omitted." })),
+    }, { additionalProperties: false }),
+    async execute(_id, params, signal, _update, ctx) {
+      if (params.number !== undefined && params.headBranch !== undefined) throw new Error("Supply number or headBranch, not both.");
+      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 requestOptions = { fetchImpl: options.fetchImpl, signal };
+      let number = params.number;
+      if (number === undefined) {
+        const found = await findGitHubPullRequest(repository, params.headBranch ?? await requireCurrentBranch(pi, rootCtx, signal), token, requestOptions);
+        if (!found) return { content: [{ type: "text", text: "No matching pull request found." }], details: { action: "pull_request_feedback", feedback: null } };
+        number = found.number;
+      }
+      const feedback = await getPullRequestFeedback(repository, number, token, requestOptions);
+      return { content: [{ type: "text", text: formatPullRequestFeedback(feedback) }], details: { action: "pull_request_feedback", feedback } };
+    },
+  });
   pi.registerTool({
     name: UPDATE_FROM_BASE_TOOL_NAME,
     label: "Update From Base",

package/src/types.ts

@@ -280,6 +280,8 @@ export interface CreateBranchDetails {
   repoRoot: string;
   previousBranch: string;
   newBranch: string;
+  /** Full commit identity the new branch starts at (HEAD after the switch). */
+  head: string;
 }
 
 export interface ChangeBranchDetails {
@@ -288,6 +290,8 @@ export interface ChangeBranchDetails {
   previousDetached: boolean;
   currentBranch: string;
   hasChangesBeforeSwitch: false;
+  /** Full commit identity of HEAD after the switch. */
+  head: string;
 }
 
 export interface FetchBranchDetails {
@@ -318,6 +322,8 @@ export interface PullBranchDetails {
   remote: string;
   remoteRef: string;
   output: string;
+  /** Full commit identity of HEAD after the fast-forward. */
+  head: string;
 }
 
 export interface RebaseBranchDetails {
@@ -338,6 +344,12 @@ export interface PushBranchDetails {
   remoteRef: string;
   refspec: string;
   output: string;
+  /** Full commit identity of the local HEAD that was pushed. */
+  head: string;
+  /** Remote-tracking ref updated by the push, for example origin/feature/x. */
+  remoteTrackingRef: string;
+  /** Full commit identity of that remote-tracking ref after the push: the remote-visible HEAD. */
+  remoteHead: string;
 }
 
 export type IntegrateBranchStatus = "already_integrated" | "fast_forward" | "merge_commit" | "conflict" | "conflict_kept";
@@ -589,6 +601,46 @@ export interface PullRequestStatusDetails extends PullRequestDetails {
   mergeCommitSha: string | null;
 }
 
+export interface PullRequestFeedbackComment {
+  author: string;
+  body: string;
+  url: string;
+}
+
+export interface PullRequestFeedbackThread {
+  path: string;
+  line: number | null;
+  comments: PullRequestFeedbackComment[];
+}
+
+export interface PullRequestFeedbackReview extends PullRequestFeedbackComment {
+  state: string;
+}
+
+export interface PullRequestFeedbackCheck {
+  name: string;
+  conclusion: string;
+  url: string;
+  jobId: number | null;
+  logTail?: string;
+  logError?: string;
+}
+
+export interface PullRequestFeedbackDetails {
+  repository: GitHubRepository;
+  number: number;
+  url: string;
+  headSha: string;
+  checksState: string | null;
+  unresolvedThreads: PullRequestFeedbackThread[];
+  resolvedThreadCount: number;
+  outdatedThreadCount: number;
+  reviews: PullRequestFeedbackReview[];
+  comments: PullRequestFeedbackComment[];
+  failingChecks: PullRequestFeedbackCheck[];
+  omitted: { threads: number; comments: number; checks: number };
+}
+
 export interface PullRequestInput {
   headBranch: string;
   baseBranch: string;