fix(agent-actions): pin a staged approve to its reviewed head SHA

[JSONbored]

What

decidePendingAgentAction's supersede check only fires when pending.params.expectedHeadSha is truthy, but planAgentMaintenanceActions set expectedHeadSha on a planned merge action and never on a planned approve action — so for every staged approve, stagedHead was undefined and the pre-check was a silent no-op.

The underlying consequence is more significant than a mislabeled audit row: unlike merge, approve had no head-SHA pin anywhere in the executor chain, and createPullRequestReview's APPROVE call had no commit_id parameter pinning it to a specific commit. A force-push between staging and accept meant the maintainer's accept would silently approve the NEW, unreviewed commit rather than being denied or superseded.

Failure scenario: a repo runs approve at auto_with_approval; gittensory stages an approve, the contributor force-pushes, and the maintainer taps Accept believing they're approving what was originally staged. The approve executes against GitHub's current (unreviewed) head, since there's no SHA pin anywhere in the approve path to detect or prevent this.

Fix

• Set expectedHeadSha on the planned approve action the same way merge already does (src/settings/agent-actions.ts), so it's persisted into the pending row's params via the existing (already action-class-agnostic) actionParams()/supersede-check machinery — no changes needed there, since the check itself was always correct, just never fed a value for approve.
• Add an optional commitId parameter to createPullRequestReview (src/github/pr-actions.ts), sent as GitHub's commit_id when provided.
• Pass the pinned head through from the executor's approve case (src/services/agent-action-executor.ts), mirroring the merge case's identical action.expectedHeadSha ?? ctx.headSha fallback pattern, so a live sweep (no staging) still pins to the current head and a staged replay pins to the reviewed one.

Tests

• createPullRequestReview sends commit_id when a commitId is provided, and omits it when not.
• Executor: a pinned approve action targets the reviewed head over the context head; falls back to an empty review body when unset.
• Approval queue: accept executes a staged approve pinned to the reviewed SHA when the head is unchanged; accept supersedes (denies) a staged approve when the live head moved after staging — the core regression this issue asks for, mirroring the existing merge force-push test exactly.

Full unsharded test:coverage green (5604 passed); typecheck green; npm audit clean.

Advances #1936. Closes #2262.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.84%. Comparing base (4389690) to head (6c8b30f).
⚠️ Report is 3 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2377   +/-   ##
=======================================
  Coverage   95.84%   95.84%           
=======================================
  Files         224      224           
  Lines       25048    25055    +7     
  Branches     9106     9109    +3     
=======================================
+ Hits        24007    24014    +7     
  Misses        427      427           
  Partials      614      614           

Files with missing lines	Coverage Δ
src/github/pr-actions.ts	98.93% <100.00%> (+0.01%)	⬆️
src/services/agent-action-executor.ts	89.90% <100.00%> (+0.09%)	⬆️
src/services/agent-approval-queue.ts	100.00% <100.00%> (ø)
src/settings/agent-actions.ts	92.79% <100.00%> (+0.06%)	⬆️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-01 22:09:47 UTC}

7 files · 1 AI reviewer · no blockers · readiness 93/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review

Review summary
The change correctly threads a reviewed-head pin through planned approve actions, queued approval acceptance, executor actuation, and the GitHub reviews API. The new unpinned-staged-approve rejection closes the legacy-row gap without blocking stale-approval retractions, and the tests cover the live pin, staged replay pin, moved-head rejection, and commit_id serialization paths. I do not see a reachable correctness break in the provided diff.

Nits — 6 non-blocking

• nit: src/services/agent-approval-queue.ts:78 relies on a long explanatory comment where the core invariant is simple enough to state briefly; the detailed force-push rationale is already covered by the tests and PR body.
• nit: src/services/agent-action-executor.ts:260 says GitHub's commit_id targeting keeps the approve from landing on a new commit, but the queue/freshness guards are the actual fail-closed protection for staged actions; tighten the comment so it does not overstate the API backstop.
• src/services/agent-action-executor.ts:260: reword the approve comment to say commit_id records the reviewed commit while the accept-time/head-freshness checks prevent stale staged approvals from executing.
• src/services/agent-approval-queue.ts:78: shorten the legacy-unpinned comment and keep the durable rule visible: unpinned approve grants are rejected, dismissStaleApproval retractions are exempt.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2262
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (size label size:M; 1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 65 registered-repo PR(s), 55 merged, 572 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 65 PR(s), 572 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: Python, TypeScript, JavaScript, Ruby, Go, Kotlin, MDX, Shell
• Official Gittensor activity: 65 PR(s), 572 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Triage stale or unlinked PRs.
• No action.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gittensory-ui	6c8b30f	Commit Preview URL Branch Preview URL	Jul 01 2026, 10:11 PM