feat: human-in-the-loop review gate (hax approval before posting)

[AbirAbbas]

Summary

Adds an optional human-in-the-loop (HITL) approval gate before PR-AF posts a review, mirroring the plan-phase approval SWE-AF already uses. When the hax env vars are configured, PR-AF no longer posts directly: it summarizes the review, sends a hax form to a workspace member, and pauses until they decide. With the env vars unset, behavior is unchanged (direct post).

Motivation: running PR-AF on a public repo where every PR triggers a review risks spammy/over-aggressive output. The gate lets a maintainer curate before anything lands on the PR.

Reviewer experience

The hax form shows a short blurb of the PR's intent plus every finding as a checkbox. The reviewer can:

• Post selected — only the checked findings get posted (e.g. "post these 3, drop the 2 nitpicky ones");
• Re-review with instructions — full pipeline re-runs with the feedback injected (e.g. "too aggressive, tone it down"), capped at 2 revisions;
• Reject — nothing is posted.

First responder wins (a single hax callback resolves the pause).

How it works (reuses existing primitives)

• app.pause() / ApprovalResult from the agentfield SDK (same primitive SWE-AF's plan gate uses).
• hax-sdk's generic form-builder request type + FormBuilder — no new hax frontend template needed.
• Watchdog-safe create_request wrapper (asyncio.wait_for over a worker thread), porting SWE-AF's pause-watchdog lesson so a wedged hax-sdk fails fast instead of burning the reasoner budget.

Env vars (consistent with SWE-AF — no new names)

Reads only what SWE-AF's HITL path already reads: HAX_API_KEY (on/off switch), HAX_SDK_URL, AGENTFIELD_SERVER, AGENTFIELD_APPROVAL_USER_ID. Expiry (72h) and max re-review revisions (2) are plain config defaults matching SWE-AF's BuildConfig, not new env vars.

Changes

• src/pr_af/hitl/ — new module (hax client, watchdog-safe create wrapper, form builder, decision parsing, the gate).
• src/pr_af/config.py — HITLConfig.
• src/pr_af/orchestrator.py — run() restructured into a revision loop; gate before posting; _generate_output gains a post_to_github flag.
• src/pr_af/reasoners/harnesses.py — reviewer_feedback threaded into the 3 meta lenses + review_dimension so re-runs respect the guidance.
• Dockerfile / pyproject.toml — add hax-sdk>=0.2.4, pin agentfield>=0.1.84 (also in the Dockerfile's explicit pip list, which uses --no-deps).

Test plan

• ruff check src/ scripts/ clean
• docker build succeeds; image ships hax 0.2.4 + agentfield, pr_af.hitl imports
• Unit + orchestrator tests (18) pass: form shape, decision parsing for every action/terminal outcome, watchdog fast-fail, and run() control flow (HITL off direct-posts; approve-subset posts only selected; rerun threads feedback then posts; reject/cap post nothing)
• Manual sanity check against the real hax FormBuilder + real agentfield ApprovalResult for all five decision paths
• Live end-to-end with hax env vars set (request surfaces in workspace, run enters waiting)
• Confirm a long pause on pr-af.review does not trip the caller's parent agent_call_timeout (same cross-reasoner pause propagation that already covers SWE-AF's plan gate)

🤖 Generated with Claude Code