@senad-d/branchme 0.3.9 → 0.3.11

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.11 - Unreleased
+
+- `land_branch` with `pullRequestNumber` accepts a local source branch that is the merged PR head or one of its ancestors: a branch left behind because the PR received commits pushed from another checkout (for example a merge of the base) holds nothing the PR lacks, and is retired. A local branch with commits the PR head does not contain is still refused, now with its own message and Blocked/Resolve guidance; a PR head that is not available locally counts as not containing it.
+- Blocked/Resolve guidance for the PR-evidence refusals of `land_branch`.
+
+## 0.3.10 - Unreleased
+
+- Added `reply_pull_request_feedback`: one reply in a review thread of a PR, optionally resolving it, or one PR conversation comment, on open, merged and closed PRs of the repository (forks included). The thread is verified to belong to the PR, and a conversation comment's number to be a pull request, before anything is posted. Agents that address PR feedback can now answer every comment on GitHub, so the reviewer, and the next automated check, see what was handled.
+- `pull_request_feedback` returns what replying and deduplication need: review thread ids, conversation comment ids, the author and time of every comment and review, the token's own login (`viewer`) with its comments marked `(you)`, and the pull request's node id. Failing check runs list up to 20 failure and warning annotations (`path:line LEVEL: message`) before their log tail, the most precise pointer for lint and test failures.
+
 ## 0.3.9 - Unreleased
 
 - Git network commands (`fetch`, `pull`, `push`, `ls-remote`) run with terminal prompts disabled: missing credentials fail at once with git's own message instead of waiting on an unanswerable prompt until the timeout reported only "killed". For `https://github.com` the `GITHUB_TOKEN`/`GH_TOKEN` BranchMe already uses for the API now also answers git's credential request (after the user's own helpers), through the child environment, never argv. A token alone is enough for push and pull.

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

@@ -43,6 +43,7 @@ Commands only show info; BranchMe tools perform actions.
 - `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.
+- `reply_pull_request_feedback` — reply to a PR review thread (optionally resolving it) or post a PR comment.
 - `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.9",
+  "version": "0.3.11",
   "type": "module",
   "description": "Pi extension for verified Git repository initialization, branch, worktree, integration, retirement, push, and pull request workflows.",
   "license": "MIT",

package/src/blocker-guidance.ts

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

package/src/commands/branchme-command.ts

@@ -52,6 +52,7 @@ export function getBranchMeHelpText(): string {
     "- `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.",
+    "- `reply_pull_request_feedback` — reply to a PR review thread (optionally resolving it) or post a PR comment.",
     "- `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

@@ -17,6 +17,7 @@ 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 REPLY_PULL_REQUEST_FEEDBACK_TOOL_NAME = "reply_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";
@@ -45,6 +46,7 @@ export const BRANCHME_TOOL_NAMES = [
   PULL_REQUEST_TOOL_NAME,
   PULL_REQUEST_STATUS_TOOL_NAME,
   PULL_REQUEST_FEEDBACK_TOOL_NAME,
+  REPLY_PULL_REQUEST_FEEDBACK_TOOL_NAME,
   LIST_WORKTREES_TOOL_NAME,
   CREATE_WORKTREE_TOOL_NAME,
   REMOVE_WORKTREE_TOOL_NAME,
@@ -95,5 +97,6 @@ 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 PULL_REQUEST_REPLY_BODY_LIMIT_CHARS = 4_000;
 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,6 +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,
 } from "./constants.ts";
 import {
   encodePathSegment, fetchGitHubResponse, gitHubJsonHeaders, isRecord, parseGitHubJson, pullRequestNumberField,
@@ -10,22 +11,24 @@ import {
 } from "./github.ts";
 import { redactSecrets } from "./redaction.ts";
 import type {
-  GitHubRepository, PullRequestFeedbackCheck, PullRequestFeedbackComment, PullRequestFeedbackDetails,
-  PullRequestFeedbackReview, PullRequestFeedbackThread,
+  GitHubRepository, PullRequestFeedbackAnnotation, PullRequestFeedbackCheck, PullRequestFeedbackComment, PullRequestFeedbackDetails,
+  PullRequestFeedbackReview, PullRequestFeedbackThread, PullRequestReplyDetails, PullRequestReplyInput,
 } 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.
+// Ids, times and the viewer let an agent reply to a thread and skip its own earlier replies.
 const FEEDBACK_QUERY = `query($owner: String!, $repo: String!, $number: Int!) {
+  viewer { login }
   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 } }
+      id number url headRefOid
+      reviewThreads(first: 100) { totalCount nodes { id isResolved isOutdated path line comments(first: 20) { nodes { id author { login } createdAt body url } } } }
+      reviews(last: 50) { nodes { id author { login } submittedAt state body url } }
+      comments(last: 50) { totalCount nodes { id author { login } createdAt body url } }
       commits(last: 1) { nodes { commit { statusCheckRollup { state contexts(first: 100) { totalCount nodes {
         __typename
-        ... on CheckRun { name conclusion databaseId detailsUrl }
+        ... on CheckRun { name conclusion databaseId detailsUrl annotations(first: 20) { nodes { path location { start { line } } annotationLevel message } } }
         ... on StatusContext { context state targetUrl }
       } } } } } }
     }
@@ -34,6 +37,8 @@ const FEEDBACK_QUERY = `query($owner: String!, $repo: String!, $number: Int!) {
 
 const FAILING_CHECK_CONCLUSIONS = new Set(["FAILURE", "TIMED_OUT", "STARTUP_FAILURE", "ACTION_REQUIRED", "CANCELLED"]);
 const FAILING_STATUS_STATES = new Set(["FAILURE", "ERROR"]);
+const REPORTED_ANNOTATION_LEVELS = new Set(["FAILURE", "WARNING"]);
+const ANNOTATION_MESSAGE_LIMIT_CHARS = 500;
 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;
@@ -53,16 +58,19 @@ function totalCount(connection: unknown): number {
   return isRecord(connection) && typeof connection.totalCount === "number" ? connection.totalCount : 0;
 }
 
-function parseComment(node: Record<string, unknown>, token: string): PullRequestFeedbackComment {
+function parseComment(viewer: string | null, token: string, node: Record<string, unknown>): PullRequestFeedbackComment {
   const author = isRecord(node.author) ? safeText(node.author.login, token, 100) : "";
   return {
+    id: safeText(node.id, token, 200),
     author: author || "ghost",
+    byViewer: viewer !== null && author === viewer,
+    createdAt: safeText(node.createdAt ?? node.submittedAt, token, 40),
     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"> {
+function parseThreads(connection: unknown, viewer: string | null, token: string): Pick<PullRequestFeedbackDetails, "unresolvedThreads" | "resolvedThreadCount" | "outdatedThreadCount"> {
   const unresolvedThreads: PullRequestFeedbackThread[] = [];
   let resolvedThreadCount = 0;
   let outdatedThreadCount = 0;
@@ -71,35 +79,55 @@ function parseThreads(connection: unknown, token: string): Pick<PullRequestFeedb
     else if (thread.isOutdated === true) outdatedThreadCount += 1;
     else {
       unresolvedThreads.push({
+        id: safeText(thread.id, token, 200),
         path: safeText(thread.path, token, 300),
         line: typeof thread.line === "number" ? thread.line : null,
-        comments: nodes(thread.comments).map((comment) => parseComment(comment, token)),
+        comments: nodes(thread.comments).map(parseComment.bind(undefined, viewer, token)),
       });
     }
   }
   return { unresolvedThreads, resolvedThreadCount, outdatedThreadCount };
 }
 
-function parseReviews(connection: unknown, token: string): PullRequestFeedbackReview[] {
+function parseReviews(connection: unknown, viewer: string | null, token: string): PullRequestFeedbackReview[] {
   return nodes(connection)
-    .map((review) => ({ ...parseComment(review, token), state: safeText(review.state, token, 40) }))
+    .map((review) => ({ ...parseComment(viewer, token, review), state: safeText(review.state, token, 40) }))
     .filter((review) => review.body !== "" || review.state === "CHANGES_REQUESTED");
 }
 
+function parseAnnotation(token: string, node: Record<string, unknown>): PullRequestFeedbackAnnotation | null {
+  const level = typeof node.annotationLevel === "string" ? node.annotationLevel : "";
+  if (!REPORTED_ANNOTATION_LEVELS.has(level)) return null;
+  const start = isRecord(node.location) && isRecord(node.location.start) ? node.location.start : null;
+  return {
+    path: safeText(node.path, token, 300),
+    line: typeof start?.line === "number" ? start.line : null,
+    level,
+    message: safeText(node.message, token, ANNOTATION_MESSAGE_LIMIT_CHARS),
+  };
+}
+
 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 annotations = nodes(node.annotations)
+      .map(parseAnnotation.bind(undefined, token))
+      .filter((annotation): annotation is PullRequestFeedbackAnnotation => annotation !== null);
+    return { name: safeText(node.name, token, 200), conclusion, url: detailsUrl, jobId: isActionsJob ? node.databaseId as number : null, annotations };
   }
   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 };
+  return { name: safeText(node.context, token, 200), conclusion: state, url: safeText(node.targetUrl, token, 300), jobId: null, annotations: [] };
 }
 
 async function postFeedbackQuery(repository: GitHubRepository, number: number, token: string, options: PullRequestFetchOptions): Promise<Record<string, unknown>> {
+  return postGraphQL(FEEDBACK_QUERY, { owner: repository.owner, repo: repository.repo, number }, token, options, "GitHub pull request feedback");
+}
+
+async function postGraphQL(query: string, variables: Record<string, unknown>, token: string, options: PullRequestFetchOptions, label: string): 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;
@@ -107,16 +135,16 @@ async function postFeedbackQuery(repository: GitHubRepository, number: number, t
     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 } }),
+      body: JSON.stringify({ query, variables }),
       signal,
-    }, "GitHub pull request feedback lookup failed", token);
-    if (!response.ok) throw new Error(`GitHub pull request feedback lookup returned HTTP ${response.status}.`);
+    }, `${label} lookup failed`, token);
+    if (!response.ok) throw new Error(`${label} 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 (body.truncated) throw new Error(`${label} exceeded the response byte limit.`);
+    const payload = requireGitHubResponseObject(parseGitHubJson(body.text, `${label} response`, token), label);
     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"}`);
+      throw new Error(`${label} query failed: ${messages.join("; ") || "unknown GraphQL error"}`);
     }
     return payload;
   } finally {
@@ -184,6 +212,7 @@ export async function getPullRequestFeedback(repository: GitHubRepository, numbe
   pullRequestNumberField(number);
   const payload = await postFeedbackQuery(repository, number, token, options);
   const data = isRecord(payload.data) ? payload.data : {};
+  const viewer = isRecord(data.viewer) ? safeText(data.viewer.login, token, 100) || null : null;
   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.");
@@ -201,12 +230,14 @@ export async function getPullRequestFeedback(repository: GitHubRepository, numbe
   return {
     repository,
     number,
+    id: safeText(pullRequest.id, token, 200),
+    viewer,
     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 !== ""),
+    ...parseThreads(pullRequest.reviewThreads, viewer, token),
+    reviews: parseReviews(pullRequest.reviews, viewer, token),
+    comments: commentNodes.map(parseComment.bind(undefined, viewer, token)).filter((comment) => comment.body !== ""),
     failingChecks,
     omitted: {
       threads: Math.max(0, totalCount(pullRequest.reviewThreads) - threadNodes.length),
@@ -220,13 +251,31 @@ function indent(text: string): string {
   return text.split("\n").map((line) => `    ${line}`).join("\n");
 }
 
+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.
+function byline(comment: PullRequestFeedbackComment): string {
+  return [`@${comment.author}`, comment.byViewer ? "(you)" : "", comment.createdAt].filter(Boolean).join(" ");
+}
+
+function idTag(kind: string, id: string): string {
+  return id ? `[${kind} ${id}] ` : "";
+}
+
 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");
+  return [
+    `- ${idTag("thread", thread.id)}${location(thread.path, thread.line)}`,
+    ...thread.comments.map((comment) => `  ${byline(comment)}: ${comment.body}`),
+  ].join("\n");
 }
 
 function formatCheck(check: PullRequestFeedbackCheck): string {
   const lines = [`- ${check.name}: ${check.conclusion} ${check.url}`.trimEnd()];
+  if (check.annotations.length > 0) {
+    lines.push("  Annotations:", ...check.annotations.map((item) => `    ${location(item.path, item.line)} ${item.level}: ${item.message}`));
+  }
   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");
@@ -238,15 +287,108 @@ export function formatPullRequestFeedback(details: PullRequestFeedbackDetails):
   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}`,
+    ...(details.viewer ? [`Token user: @${details.viewer}; comments marked (you) are its own earlier replies.`] : []),
     `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}`),
+    ...details.reviews.map((review) => `- ${byline(review)} ${review.state}: ${review.body}`),
     `Conversation comments: ${details.comments.length}${omittedComments}.`,
-    ...details.comments.map((comment) => `- @${comment.author}: ${comment.body}`),
+    ...details.comments.map((comment) => `- ${idTag("comment", comment.id)}${byline(comment)}: ${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]`;
 }
+
+const THREAD_OWNER_QUERY = `query($id: ID!) {
+  node(id: $id) { ... on PullRequestReviewThread { id isResolved pullRequest { number repository { name owner { login } } } } }
+}`;
+const PULL_REQUEST_EXISTS_QUERY = `query($owner: String!, $repo: String!, $number: Int!) {
+  repository(owner: $owner, name: $repo) { pullRequest(number: $number) { number } }
+}`;
+const THREAD_REPLY_MUTATION = `mutation($threadId: ID!, $body: String!) {
+  addPullRequestReviewThreadReply(input: { pullRequestReviewThreadId: $threadId, body: $body }) { comment { url } }
+}`;
+const RESOLVE_THREAD_MUTATION = `mutation($threadId: ID!) {
+  resolveReviewThread(input: { threadId: $threadId }) { thread { isResolved } }
+}`;
+
+function validateReplyInput(input: PullRequestReplyInput): string {
+  pullRequestNumberField(input.number);
+  const body = typeof input.body === "string" ? input.body.trim() : "";
+  if (body === "") throw new Error("body is required and cannot be blank.");
+  if (body.length > PULL_REQUEST_REPLY_BODY_LIMIT_CHARS) throw new Error(`body exceeds ${PULL_REQUEST_REPLY_BODY_LIMIT_CHARS} characters.`);
+  if (input.resolve === true && !input.threadId) throw new Error("resolve requires threadId; conversation comments cannot be resolved.");
+  return body;
+}
+
+// The thread must belong to this pull request of this repository before anything is posted.
+async function requireThreadOfPullRequest(repository: GitHubRepository, input: PullRequestReplyInput, token: string, options: PullRequestFetchOptions): Promise<boolean> {
+  const payload = await postGraphQL(THREAD_OWNER_QUERY, { id: input.threadId }, token, options, "GitHub review thread");
+  const node = isRecord(payload.data) && isRecord(payload.data.node) ? payload.data.node : null;
+  const pullRequest = node && isRecord(node.pullRequest) ? node.pullRequest : null;
+  const owner = pullRequest && isRecord(pullRequest.repository) ? pullRequest.repository : null;
+  const ownerLogin = owner && isRecord(owner.owner) ? owner.owner.login : null;
+  if (!node || node.id !== input.threadId || pullRequest?.number !== input.number ||
+      typeof ownerLogin !== "string" || ownerLogin.toLowerCase() !== repository.owner.toLowerCase() ||
+      typeof owner?.name !== "string" || owner.name.toLowerCase() !== repository.repo.toLowerCase()) {
+    throw new Error(`Review thread ${safeText(input.threadId, token, 200)} is not a thread of pull request #${input.number} in ${repository.owner}/${repository.repo}; nothing was posted.`);
+  }
+  return node.isResolved === true;
+}
+
+async function replyToThread(repository: GitHubRepository, input: PullRequestReplyInput, body: string, token: string, options: PullRequestFetchOptions): Promise<PullRequestReplyDetails> {
+  const alreadyResolved = await requireThreadOfPullRequest(repository, input, token, options);
+  const reply = await postGraphQL(THREAD_REPLY_MUTATION, { threadId: input.threadId, body }, token, options, "GitHub review thread reply");
+  const added = isRecord(reply.data) && isRecord(reply.data.addPullRequestReviewThreadReply) ? reply.data.addPullRequestReviewThreadReply : null;
+  const commentUrl = added && isRecord(added.comment) ? safeText(added.comment.url, token, 300) : "";
+  if (!commentUrl) throw new Error("GitHub did not confirm the review thread reply.");
+  let resolved: boolean | null = null;
+  if (input.resolve === true) {
+    resolved = alreadyResolved;
+    if (!alreadyResolved) {
+      const result = await postGraphQL(RESOLVE_THREAD_MUTATION, { threadId: input.threadId }, token, options, "GitHub review thread resolution");
+      const thread = isRecord(result.data) && isRecord(result.data.resolveReviewThread) && isRecord(result.data.resolveReviewThread.thread)
+        ? result.data.resolveReviewThread.thread : null;
+      resolved = thread?.isResolved === true;
+    }
+  }
+  return { action: "reply_pull_request_feedback", repository, number: input.number, threadId: input.threadId ?? null, commentUrl, resolved };
+}
+
+async function commentOnPullRequest(repository: GitHubRepository, input: PullRequestReplyInput, body: string, token: string, options: PullRequestFetchOptions): Promise<PullRequestReplyDetails> {
+  // Issues and pull requests share numbers; confirming a pull request first keeps the comment off an issue.
+  // GraphQL, not the REST status read: a pull request from a fork is still this repository's pull request.
+  const found = await postGraphQL(PULL_REQUEST_EXISTS_QUERY, { owner: repository.owner, repo: repository.repo, number: input.number }, token, options, "GitHub pull request");
+  const pullRequest = isRecord(found.data) && isRecord(found.data.repository) ? found.data.repository.pullRequest : null;
+  if (!isRecord(pullRequest) || pullRequest.number !== input.number) {
+    throw new Error(`Pull request #${input.number} was not found in ${repository.owner}/${repository.repo}; nothing was posted.`);
+  }
+  const url = `${GITHUB_API_BASE_URL}/repos/${encodePathSegment(repository.owner)}/${encodePathSegment(repository.repo)}/issues/${input.number}/comments`;
+  const response = await fetchGitHubResponse(requireFetchImplementation(options.fetchImpl ?? globalThis.fetch), url, {
+    method: "POST", headers: gitHubJsonHeaders(token), body: JSON.stringify({ body }), signal: options.signal,
+  }, "GitHub pull request comment failed", token);
+  if (!response.ok) throw new Error(`GitHub pull request comment returned HTTP ${response.status}.`);
+  const text = await readBoundedResponseText(response, options.signal, PULL_REQUEST_FEEDBACK_RESPONSE_LIMIT_BYTES);
+  const payload = requireGitHubResponseObject(parseGitHubJson(text.text, "GitHub pull request comment response", token), "Pull request comment");
+  const commentUrl = safeText(payload.html_url, token, 300);
+  if (!commentUrl) throw new Error("GitHub did not confirm the pull request comment.");
+  return { action: "reply_pull_request_feedback", repository, number: input.number, threadId: null, commentUrl, resolved: null };
+}
+
+/** Replies to one review thread (and optionally resolves it), or posts one conversation comment. */
+export async function replyPullRequestFeedback(repository: GitHubRepository, input: PullRequestReplyInput, token: string, options: PullRequestFetchOptions = {}): Promise<PullRequestReplyDetails> {
+  validateGitHubRepository(repository);
+  const body = validateReplyInput(input);
+  return input.threadId
+    ? replyToThread(repository, input, body, token, options)
+    : commentOnPullRequest(repository, input, body, token, options);
+}
+
+export function formatPullRequestReply(details: PullRequestReplyDetails): string {
+  if (details.threadId === null) return `Commented on PR #${details.number}: ${details.commentUrl}`;
+  let resolution = "";
+  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}`;
+}

package/src/tools/workflow-tools.ts

@@ -2,13 +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_FEEDBACK_TOOL_NAME, 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_REPLY_BODY_LIMIT_CHARS,
+  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, getPullRequestFeedback } from "../github-feedback.ts";
+import { formatPullRequestFeedback, formatPullRequestReply, getPullRequestFeedback, 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";
@@ -94,7 +94,7 @@ 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.",
+    description: "pull_request_feedback reads what a same-repository GitHub PR asks to be fixed: unresolved review threads (with thread ids) and their comments, review summaries, conversation comments (with ids), each with author and time and comments by the token's own user marked (you), and the head commit's failing checks with their file:line annotations and 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.",
@@ -121,6 +121,31 @@ export function registerWorkflowTools(pi: Pick<ExtensionAPI, "registerTool" | "e
       return { content: [{ type: "text", text: formatPullRequestFeedback(feedback) }], details: { action: "pull_request_feedback", feedback } };
     },
   });
+  pi.registerTool({
+    name: REPLY_PULL_REQUEST_FEEDBACK_TOOL_NAME,
+    label: "Reply To Pull Request Feedback",
+    description: "reply_pull_request_feedback posts one reply on a pull request of this GitHub repository (including one opened from a fork): with threadId it replies in that review thread and, with resolve: true, resolves the thread; without threadId it posts one conversation comment. Works on open, merged and closed PRs. The thread must belong to the PR; nothing else is changed.",
+    promptSnippet: "reply_pull_request_feedback: answer a PR review thread (optionally resolving it) or post a PR comment",
+    promptGuidelines: [
+      "Use reply_pull_request_feedback with the thread ids pull_request_feedback reports ([thread <id>]); one call per thread, the body states what was done or why not.",
+      "Pass reply_pull_request_feedback resolve: true only for a thread whose request is fixed or already addressed; leave a thread open when it needs a person's decision.",
+      "Without threadId, reply_pull_request_feedback posts one conversation comment on the PR; conversation comments cannot be resolved.",
+      "reply_pull_request_feedback never edits or deletes comments, approves, requests changes, merges, or closes a PR.",
+    ],
+    parameters: Type.Object({
+      number: Type.Integer({ minimum: 1, description: "PR number." }),
+      body: Type.String({ minLength: 1, maxLength: PULL_REQUEST_REPLY_BODY_LIMIT_CHARS, description: "Markdown reply." }),
+      threadId: Type.Optional(Type.String({ minLength: 1, description: "Review thread id from pull_request_feedback; omit for a conversation comment." })),
+      resolve: Type.Optional(Type.Boolean({ description: "Resolve the thread after replying; requires threadId." })),
+    }, { 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 replyPullRequestFeedback(repository, params, token, { fetchImpl: options.fetchImpl, signal });
+      return { content: [{ type: "text", text: formatPullRequestReply(details) }], details };
+    },
+  });
   pi.registerTool({
     name: UPDATE_FROM_BASE_TOOL_NAME,
     label: "Update From Base",

package/src/types.ts

@@ -602,12 +602,19 @@ export interface PullRequestStatusDetails extends PullRequestDetails {
 }
 
 export interface PullRequestFeedbackComment {
+  /** GraphQL node id; empty when GitHub did not return one. */
+  id: string;
   author: string;
+  /** True when the token's own user wrote it (Mission's earlier replies). */
+  byViewer: boolean;
+  createdAt: string;
   body: string;
   url: string;
 }
 
 export interface PullRequestFeedbackThread {
+  /** Review thread node id, the target for replies and resolution. */
+  id: string;
   path: string;
   line: number | null;
   comments: PullRequestFeedbackComment[];
@@ -622,13 +629,25 @@ export interface PullRequestFeedbackCheck {
   conclusion: string;
   url: string;
   jobId: number | null;
+  annotations: PullRequestFeedbackAnnotation[];
   logTail?: string;
   logError?: string;
 }
 
+export interface PullRequestFeedbackAnnotation {
+  path: string;
+  line: number | null;
+  level: string;
+  message: string;
+}
+
 export interface PullRequestFeedbackDetails {
   repository: GitHubRepository;
   number: number;
+  /** Pull request node id. */
+  id: string;
+  /** Login of the token's user; null when GitHub did not return it. */
+  viewer: string | null;
   url: string;
   headSha: string;
   checksState: string | null;
@@ -641,6 +660,23 @@ export interface PullRequestFeedbackDetails {
   omitted: { threads: number; comments: number; checks: number };
 }
 
+export interface PullRequestReplyInput {
+  number: number;
+  body: string;
+  threadId?: string;
+  resolve?: boolean;
+}
+
+export interface PullRequestReplyDetails {
+  action: "reply_pull_request_feedback";
+  repository: GitHubRepository;
+  number: number;
+  threadId: string | null;
+  commentUrl: string;
+  /** Thread state after the call; null when resolution was not requested or this was a conversation comment. */
+  resolved: boolean | null;
+}
+
 export interface PullRequestInput {
   headBranch: string;
   baseBranch: string;