fix: fetch current PR head for review diffs

[kunchenguid]

Intent

Machinery-over-memory fix for Firstmate review diffs: make bin/fm-review-diff.sh FETCH the actual PR head (refs/pull//head) by DEFAULT whenever task meta records pr=, so reviews always compare the true remote PR tip and never a stale local checkout or a stale recorded pr_head=.

This class of bug has bitten reviewers multiple times (holding a merge over a "missing" fix that had already landed on the PR because the review looked at lagging local objects after no-mistakes fix rounds pushed).

Deliberate design choices:

• Always attempt git fetch of refs/pull//head first when a PR URL or number is in meta; do not prefer a reachable recorded pr_head= even if present (recorded SHAs go stale when pr-check does not refresh them).
• Store the fetched tip under refs/fm-review/pull//head so a later base-branch fetch cannot clobber the compare tip via FETCH_HEAD.
• Offline/unreachable fallback order: recorded pr_head= if the object exists, else local branch with a warning. Without pr=, keep local-branch compare unchanged.
• Add a regression test that sets local+recorded SHA to old content, remote pull head to newer content, and asserts the review shows the fetched tip (must fail under pre-fix prefer-recorded behavior).
• Docs (architecture.md, scripts.md) updated to match the new precedence.

What Changed

• Fetch PR heads into a dedicated refs/fm-review/pull/<n>/head ref before generating review diffs, ensuring the remote tip takes precedence over recorded metadata.
• Retain recorded pr_head and local-branch fallbacks when the PR head cannot be fetched, while preserving local-branch comparisons for tasks without a PR.
• Add stale-recorded-head coverage, isolate session-start nudge tests from gate state, and update review-diff documentation.

Risk Assessment

✅ Low: The change is tightly scoped and implements the required fresh PR-head fetch with the specified isolated ref and fallback order; surrounding call paths and updated regression coverage are consistent.

Testing

The prior baseline was successful; focused regression coverage, a direct end-to-end CLI review transcript, and the complete test suite all passed (FULL_SUITE_EXIT=0).

Evidence: End-to-end PR-head review transcript

Scenario: PR metadata still records a reachable stale SHA while the remote pull head has the newer fix.
recorded pr_head: 3cfb7793d7915f2653a3cce92be15bc56792936c
remote PR head:  9830ce48278639e89897ede2dcf216d13c45a449

$ fm-review-diff.sh task-x1
diff base: origin/main
 feature.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/feature.txt b/feature.txt
index df967b9..da34a17 100644
--- a/feature.txt
+++ b/feature.txt
@@ -1 +1 @@
-base
+pr-fixed

$ git rev-parse refs/fm-review/pull/42/head
9830ce48278639e89897ede2dcf216d13c45a449

Assertions: reviewer output contains +pr-fixed, omits stale-local, and private fetched ref equals remote PR head.
PASS: private fetched ref matches the remote PR tip.
PASS: review surfaced only the newer PR-tip content.

- Outcome: 🔧 1 issue found → auto-fixed ✅ across 2 runs (1h51m30s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

🔧 **Test** - 1 issue found → auto-fixed ✅

• 🚨 tests failed with exit code 1
• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"

🔧 Fix: Isolate session-start nudge tests from gate state
✅ Re-checked - no issues remain.

• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• Baseline configured suite reported successful before this run.
• bash tests/fm-review-diff.test.sh
• Isolated bin/fm-review-diff.sh task-x1 scenario with stale pr_head= and newer remote refs/pull/42/head
• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; echo "FULL_SUITE_EXIT=$rc"; exit "$rc"

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.