feat(approval): rebase HITL plan-approval gate (supersedes #50)

[AbirAbbas]

Summary

Rebases the human-in-the-loop plan-approval gate from #50 onto current main. PR #50 was 34 commits behind and conflicting; rather than try to resolve those conflicts mechanically, this re-applies just the HITL bits cleanly on a fresh branch.

When HAX_API_KEY is set on the SWE-AF service, every build() pauses between Phase 1 (plan + git_init) and Phase 2 (execute) and posts the plan to hax-sdk for human review. Reviewer can approve, request changes (re-runs Architect → Tech Lead → Sprint Planner with the feedback, bounded by cfg.max_plan_revision_iterations), or reject. Without HAX_API_KEY, behavior is unchanged.

What's different from #50

• Cleanly rebased on main — preserves _run_ci_gate, permission_mode, env-driven runtime defaults, build-id workspace scoping, and all post-PR CI / resolve() machinery that landed after feat: HITL SDK integration #50 was cut.
• Drops swe_af/approval.py (467 lines of dead POC code that wasn't imported anywhere — superseded by the inline app.pause() integration).
• Keeps agentfield>=0.1.77 (don't downgrade — the HITL block depends on app.pause() which arrived in 0.1.77+).
• Splits into 4 focused commits instead of three POC commits.

Architecture

• Workspace-broadcast by default. Omitting userId on create_request sends to all active workspace members (existing hax-sdk behavior). AGENTFIELD_APPROVAL_USER_ID overrides to a specific Hub user.
• Resume via control plane, not in-process callback. SWE-AF calls client.create_request(webhook_url=<CP>/api/v1/webhooks/approval-response) and then await app.pause(...). The CP transitions the execution to waiting, and when hax-sdk fires the webhook it resumes the paused future. No aiohttp callback server in the agent process — this means the agent stays stateless and the resume path survives container restarts.
• State persistence. .artifacts/approval_state.json records the current decision/feedback/request_id/revision, so a crashed-and-restarted agent can be reasoned about externally.
• Auto-enabled via env. No new flag — set HAX_API_KEY to engage, leave unset to skip the gate. Matches feat: HITL SDK integration #50's UX.

Known follow-ups (not in this PR)

1. plan-review-v2 template not in hax-sdk yet. hax-sdk strictly validates type against its template registry and currently has no renderer for plan-review-v2. A SWE-AF build with HAX_API_KEY set will fail at client.create_request until that template ships in hax-sdk. Tracked separately.
2. First-responder-wins claim semantics. Workspace broadcast already works, but two reviewers can race a response. Adding atomic claimed_by/claimed_at to hax-sdk is a separate PR there.
3. github-buddy issue-comment polish. Surfacing the hax review URL on the originating GitHub issue while waiting is a small follow-up in github-buddy.

Test plan

• python3 -c 'from swe_af import app' — module loads without error
• Local: HAX_API_KEY= unset, run a build, confirm Phase 1.5 logs HAX_API_KEY=NOT SET and skips the gate
• Local: with HAX_API_KEY set and hax-sdk's plan-review-v2 template available, run a build, confirm app.pause suspends the execution and the request shows up in the hub
• Local: approve via hub, confirm execution resumes into Phase 2
• Local: request_changes, confirm Architect → Tech Lead → Sprint Planner re-run and a new approval request is posted
• Local: reject, confirm BuildResult comes back with success=False and summary carries the rejection reason
• Railway end-to-end on the test deployment

🤖 Generated with Claude Code