The merge write, readback and remote verification run in Go #871

Problem

The second half of squash-merge.sh and the post-merge functions of merge-agent.sh (together about 220 lines) do the one write that cannot be undone: re-read and re-gate the pull request, retarget dependent pull requests, copy the stamped message bytes, run gh pr merge --squash --match-head-commit, then read the result back once. A successful gh exit may only have queued the merge, and an error may follow a completed merge, so the result decides the outcome, never the exit code. Unattended mode then checks the remote commit message against the reviewed one and prints the report, and any hold or uncertain write reports without changing its status. It is under the shell freeze in #588.

Part of #324, within #588. Child 11 in #324's Children list. Replaces the merge write, retargeting, verification, report and hold-reporting code in squash-merge.sh and merge-agent.sh.

Acceptance criteria

1. AC1: Given a confirmed merge in unattended mode, when same-repository pull requests target the head branch, then each is retargeted to the base after an identity check; given the returned list holds 500 pull requests or more, then the command refuses before retargeting any (a list of 499 is retargeted); given a cross-repository pull request, then it is skipped.
2. AC2: Given the state may have changed during retargeting or readiness, when the write is about to happen, then the live state, stamp and gates are read and judged again, with the final pass reusing pinned required checks.
3. AC3: Given the draft changed after the review, when its bytes are copied for the merge, then the digest is compared with the stamp's and a difference refuses; given a message with a subject and no body, then it refuses.
4. AC4: Given the checks pass, when the merge is written, then the squash is pinned to the reviewed head with the draft's subject and body, and no second write is attempted whatever gh returns.
5. AC5: Given the readback reports MERGED with the reviewed head and a merge commit, when the command finishes, then it prints MERGED: #<n> at <sha>, records the result file and exits 0 only if the required remote verification (AC7, unattended mode) succeeded or was not required; a later cleanup failure does not change this status (the nonfatal outcome is defined in child 12).
6. AC6: Given the readback reports OPEN after exit 0, OPEN after a failure, CLOSED, another state, a head other than the reviewed one, MERGED without a merge commit, or a failed readback, when the command finishes, then it prints the queued, FAILED or UNKNOWN line accordingly, keeps the drafts and stamps, and exits 75 for the queued case and 1 otherwise.
7. AC7: Given unattended mode, when the merge is MERGED, then the merge commit is fetched with the live base, must be an ancestor of it, and its message must equal the reviewed message after whitespace normalization; given a commit that is not an ancestor or a differing message, then it exits 1 with merged-not-as-reviewed and keeps all evidence; given the fetch of the merge commit fails, then the status and streams are those the frozen verifier gives for a failed fetch, which is not the merged-not-as-reviewed diagnostic.
8. AC8: Given unattended mode, when the merge is verified, then the report names the number, merge commit, owner override and owner rule, is written to the result file and goes to the agent report channel under the contract of refactor(agents): port unattended review bounds and reporting to Go #770.
9. AC9: Given any non-zero exit in unattended mode, when the command stops, then it reports the held workflow on the blocker channel under the contract of refactor(agents): port unattended review bounds and reporting to Go #770, or prints the report on stderr if the channel fails, and keeps the original status.
10. AC10: Non-functional: the merge command is invoked at most once per run, and the code runs against a fake gh on macOS, Linux and Windows in CI.

Scope and non-goals

Scope: the write, readback, verification, retargeting, report and hold-reporting parts of agentrepo merge run, ported from workflow.bats, lifecycle.bats and merge-workflow.bats cases.

Non-goal: cleanup of drafts, stamps and branches (child 12), so a MERGED result here leaves cleanup as the next step of the same command. Non-goal: a retry of an uncertain write. Non-goal: editing the shell script before child 14.

Approach

Meet AC1 to AC10 with failing cases first: a fake gh scripted per readback state, comparing statuses, streams, kept files and the count of merge invocations with the shell script on the same fixtures. Mechanism is the implementer's choice.

Dependencies

Blocked by: #864, #869, #870, #333, #770.

Prerequisites: #770 (agent report and blocker channels), #321 and #333. The remote squash commit's ancestry and message check is this child's own; #764 verifies a locally created commit and is not a dependency.

Size

M. One pull request.

Verify plan

• AC1: fake-gh lists of 499 and 500 pull requests, plus same-repository and cross-repository cases, recording each write.
• AC2, AC3: fake-gh state tables recording each write.
• AC4, AC10: a counter on the fake gh pr merge; the CI matrix run.
• AC5, AC6: readback table covering every state in the criteria, asserting streams, kept files and exit status.
• AC7: a scratch repository with three fixtures: a matching remote message on the live base's ancestry, asserting success (exit 0, no merged-not-as-reviewed); a differing message and a non-ancestor commit, each asserting exit 1 and merged-not-as-reviewed; and a failed fetch asserting the frozen verifier's status and streams.
• AC8, AC9: report-channel stubs, including one that fails.
• Definition of done: D1 each AC is verified at the merged head, with the commands and results cited in the pull request's Verification. D2 an independent review approves the exact merged head, and every finding has a recorded disposition. D3 required checks pass with no gate loosened. D4 the leak scans the repository specifies are clean, and every post made for this work passes the per-post leak review before it is posted. D5 every commit is signed. D6 the documentation matches the change or the Verification says why there is no impact. D7 every commit has an Assisted-by trailer and the pull request has the provenance:agent-assisted label. D8 the pull request stays within the size limits. D9 follow-ups are filed as issues and listed under Related. D10 the merge closes the issue through a closing reference, the board shows Done, and the final Status: comment names the merge commit.

Risks

A second write after an uncertain first one could merge twice or merge a different message, and a cleanup that runs on an unconfirmed merge would destroy the evidence. AC4 and AC6 hold both. Undo: revert; the shell script is untouched.

Operator authority

None. The Go files are new, and nothing in this area edits an owner-tier path: deleting merge-agent.sh and merge-policy.py is the single cutover under #588.