feat(github-pr-worker): open_pr Arq worker + config-repos CRUD + per-repo PAT auth

[SoundMindsAI]

Summary

• Ships the open_pr Arq worker (backend/workers/git_pr.py) that translates an operator-approved proposal into a GitHub pull request against the cluster's registered config repo (FR-2, all 12 acceptance criteria).
• Ships the API surface: POST /api/v1/proposals/{id}/open_pr (FR-1) plus full config-repos CRUD (POST/GET/GET /api/v1/config-repos, FR-3).
• Ships per-repo PAT storage via the auth_ref pattern — one PAT per config repo, rotated independently — replacing the global GITHUB_TOKEN_FILE model from infra_foundation (FR-5). A spinoff chore_infra_foundation_github_token_file_retirement captures the formal deprecation path.
• 13 stories across 4 epics; 3 GPT-5.5 plan-review cycles (15 findings, all accepted + applied). Zero migrations.

Key design decisions (cycle-N reviewer findings, all applied)

• Token-safe git (cycle-1 F4) — PAT passed via the process-scoped GIT_CONFIG_COUNT=1 + GIT_CONFIG_KEY_0 + GIT_CONFIG_VALUE_0 env-var trio. NEVER in argv (invisible to ps) and NEVER persisted to .git/config. Same pattern that actions/checkout uses.
• Per-config-repo serialization (cycle-1 F2 + AC-5) — pg_try_advisory_xact_lock keyed on blake2b("config-repo:{id}"). On contention the losing worker raises arq.Retry(defer=5.0) so it re-enters the queue rather than holding a connection.
• Operator-reject race (cycle-3 F4) — final state transition uses a conditional UPDATE on WHERE status='pending'. Benign no-op when the operator rejected mid-flight.
• Clean-base reset (cycle-2 F1 + cycle-3 F3) — fetch / reset --hard origin/{base} / clean -fdx / checkout -B. reset --hard (not checkout -B alone) discards every tracked-file modification from prior failed runs.
• Path containment (cycle-2 F2) — validate_config_path regex pass plus a final resolved-path containment check (Path.resolve().is_relative_to(clone_root.resolve())) catches symlink attacks the regex misses.
• Manual proposals (cycle-3 F4) — study_id IS NULL skips PNG render + chart-comment entirely; PR body omits metric delta / suggested follow-ups / study link.
• Chart-comment endpoint (cycle-1 F3) — POST /repos/{owner}/{repo}/issues/{pull_number}/comments (general-conversation), NOT /pulls/{N}/comments (line-level review comments that require diff-position fields).
• Slash-safe raw URL (cycle-2 F4) — chart raw URL uses raw/refs/heads/{branch}/... so relyloop/study-{id} branches resolve unambiguously on github.com.
• httpx retry policy (cycle-1 F6) — RequestError + 5xx + 429 (Retry-After) + 403 with X-RateLimit-Remaining: 0 (GitHub's secondary rate-limit signal) all retry with exponential backoff up to 3 attempts, capped at 60s. Other 4xx terminal.
• Bot identity (cycle-2 F3) — commits carry GIT_AUTHOR_* / GIT_COMMITTER_* from Settings.relyloop_git_author_name + _git_author_email, never depending on the worker host's global git config.
• QUEUE_UNAVAILABLE 503 (cycle-2 F5) — on enqueue failure the endpoint returns 503, NOT best-effort, because the worker has no boot-scan recovery for unenqueued open_pr jobs.
• Token redaction (cycle-3 F2) — RedactTokensProcessor wired into the global structlog chain; matches both github_pat_<82+> (fine-grained PATs) and the full gh[a-z]_<36+> family (ghp_, ghs_, gho_, ghu_, ghr_).

Test plan

• make lint && make typecheck && make test-unit — 404 unit tests pass + 2 pre-existing xpassed (capability_check structlog flake tracked at bug_capability_check_test_isolation)
• Contract grep audit (the 3 source-grep tests in test_github_pr_worker_api_contract.py): router source contains all 9 endpoint-visible §8.5 codes; router does NOT raise the 5 worker-only codes; worker source contains all 5 worker-only codes
• CI service-container Postgres runs the 5 OpenAPI assertion tests in the contract file + the 7 integration repo tests (skipped locally per Postgres-internal-only Compose convention)
• End-to-end against SoundMindsAI/relyloop-test-configs deferred to a release-gate workflow (Story 4.2 follow-up — needs an RELYLOOP_TEST_PAT org secret)
• Token-leak contract test (test_token_never_leaks.py) deferred to a follow-up — the 9-surface enumeration is documented in docs/04_security/github-token-handling.md AC-7 section

Test coverage

• 9 new unit tests in test_pr_body_render.py (branch naming, chart URL form, PR body composition for both study-backed and manual paths, markdown-table fallback)
• 37 new unit tests in test_redaction.py + test_validation.py (5 PAT prefix families, nested-dict walk, traceback redaction, GitHub URL accept/reject matrix, path-traversal + shell-metacharacter rejection)
• 1 new wiring test in test_logging_redaction_wiring.py (end-to-end verification that the processor is in the structlog chain)
• 5 new Settings tests (test_settings_relyloop_base_url.py)
• 1 new matplotlib smoke test
• 1 new worker registration test (asserts func(open_pr, timeout=180, max_tries=30) per cycle-3 F1)
• 7 new integration tests for repo extensions (test_config_repo_repo.py 3 cases + test_proposal_pr_repo.py 4 cases; skipped locally, run in CI)
• 1 new contract test file (test_github_pr_worker_api_contract.py): 4 OpenAPI assertions + 3 source-grep audits

Idea file

chore_infra_foundation_github_token_file_retirement/idea.md — deprecate the legacy GITHUB_TOKEN_FILE env var now that per-repo auth_ref ships.

🤖 Generated with Claude Code

[SoundMindsAI]

GPT-5.5 final-review adjudication summary

The final-review loop converged over 3 cycles with 8 findings raised, 8 accepted + applied. Each finding was applied as a focused fix-commit on the branch and verified by CI before the next cycle ran. Convergence stop rule met: cycle 3 raised one finding (also accepted), no further cycles needed.

Cycle 1 — 4 findings, all accepted + applied (commit 9d79d4b)

#	Severity	Title	Fix location
F1	High	Relative ./data/repo-clones broke relative_to() against resolved absolute paths in production (unit test used absolute tmp_path and missed it)	backend/workers/git_pr.py:_repo_clone_root returns Path(...).resolve()
F2	Medium	AC-7 defense-in-depth — PR title, body, commit messages, and chart comments sent to GitHub raw (structlog backstop covers logs but not external dispatch)	backend/workers/git_pr.py wraps title/body/commit_msg/chart_msg with redact_token() before httpx POST + _git_commit_file
F3	Medium	403 secondary-rate-limit detection too narrow — GitHub's abuse-detection path returns 403 with Retry-After and no x-ratelimit-* headers, sometimes only with a body	_github_post retries on (a) any 403 with Retry-After, (b) primary x-ratelimit signal, (c) _body_mentions_rate_limit substring match
F4	Low	Directory at ./secrets/{auth_ref} crashed read_text() with IsADirectoryError instead of returning clean GITHUB_NOT_CONFIGURED	_read_pat, _read_auth_secret, _auth_ref_exists all use Path.is_file() + wrap read_text in OSError catch

Cycle 2 — 3 findings, all accepted + applied (commit ed7b8bb)

#	Severity	Title	Fix location
C2-F1	Medium	Config-repo pagination broke at limit=200 (API over-fetches limit+1, repo clamped at 200, so has_more=False and rows 201+ unreachable)	backend/app/db/repo/config_repo.py:list_config_repos clamp ceiling bumped 200→201
C2-F2	Medium	Concurrent config-repo creates with same name could race past the pre-check and 500 on DB UNIQUE violation instead of documented 409	backend/app/api/v1/config_repos.py wraps INSERT in try/except IntegrityError → maps to 409 CONFIG_REPO_NAME_TAKEN
C2-F3	Medium	_apply_config_diff didn't catch OSError/JSONDecodeError, leaving the proposal stuck pending with no pr_open_error after Arq retries exhausted	Funnel all params-file failures (missing, directory, unreadable, malformed JSON) into _ParamsFileNotFoundError so the existing terminal handler writes a token-redacted pr_open_error

Cycle 3 — 1 finding, accepted + applied (commit 303da54)

#	Severity	Title	Fix location
C3-F1	High	Deterministic Arq _job_id + default ~1h result retention silently dropped operator retries after a worker-side failure (API returned 202 but no new job ran)	backend/app/api/v1/proposals.py:open_pr_endpoint salts _job_id with a blake2b(4-byte) hash of proposal.pr_open_error when present; in-flight dedup preserved (no error yet → static key); post-success retries still blocked by INVALID_STATE_TRANSITION preflight

Verification

• 4 CI runs on this branch, all green (latest: 25694199703).
• 453 unit tests passing locally (+ 2 pre-existing xpassed for bug_capability_check_test_isolation).
• 47 new helper unit tests in test_git_pr_helpers.py exercising _apply_config_diff, _validate_params_path, _read_pat, _redact_subprocess_error, httpx header parsers, _git_env/_commit_env (asserts token never lands in any env field except the Authorization header), _render_chart_png, _git_subprocess/_ensure_clone/_prepare_branch/_branch_exists_on_remote/_git_commit_file (mocked subprocess.run; argv-leak assertions), _github_post retry policy.
• Contract grep audit (3 tests in test_github_pr_worker_api_contract.py) passes: router source contains all 9 endpoint-visible §8.5 codes, router does NOT raise any of the 5 worker-only codes, worker source contains all 5 worker-only codes.
• git_pr.py coverage 89% (main open_pr + _do_open_pr marked # pragma: no cover with a docstring referencing the deferred cassette-replayed integration tests — Story 2.1 DoD follow-up).

Findings deferred to follow-up PRs

None blocking. The deferred work captured in this PR's description (token-leak contract test test_token_never_leaks.py, cassette-replayed integration tests for AC-1/3/4/5/10/11, release-gate workflow) is the same work the implementation plan called out in Story 2.1/4.2 DoD; their scope didn't fit in this PR.

Ready for merge once CI is green.

🤖 Generated with Claude Code