fix(git-sync): validate push access where GitHub enforces it (#2107)

[dolho]

Summary

Nothing checked that an agent's git credential can write. A fine-grained PAT with Contents: read-only passed every check and then failed every auto-sync for the agent's whole life (64 in the reported case, remote: Write access to repository not granted.):

• git ls-remote talks to upload-pack, so it only proves read access.

• The REST permissions.push field reports the user's role on the repo, not what a fine-grained token was granted.

• git_service.probe_push_access(repo, pat) asks the side GitHub enforces: a git push --dry-run --porcelain <url> HEAD:refs/heads/__trinity_write_probe from an empty scratch repo on the backend host. The PAT rides git_auth_env (an http.extraHeader in the child's env), never argv. The dry run negotiates auth and permission and creates nothing. Result: ok / denied (with GitHub's own line) / transient.

• Creation: agents that will auto-push (the _git_auto_sync_baked predicate: working-branch mode or fork-to-own, with a PAT) are probed. denied → 400 naming GitHub's reason and the fix (fine-grained: Contents: Read and write; classic: repo; or source mode), before any branch is reserved or container is created. transient → logged, non-blocking (the PAT path's existing policy). Source-mode (pull-only) agents aren't probed.

• Sync health: when the error is a refused push (git_service.is_push_denied), the sync_failing item is titled "Git token can't push", says it won't recover on its own, and carries context.cause = "push_denied" plus a remediation. Other failures keep the generic item.

Not in this PR

• The issue's "never once succeeded vs failing for one cycle" signal needs a persisted last-successful-push timestamp. trinity-enterprise#706 owns that ("dirty count + last successful push persisted"), and fix(git-sync): auto-sync heartbeat fetches and rebases before push; refuses on a shared source-mode branch (#3011) #3016 (bug(git-sync): the auto-sync heartbeat pushes without fetch or rebase — on a shared branch it fails non-fast-forward forever after the first foreign push #3011) already adds the agent-side last_successful_push_at.
• A compatibility-panel catalogue check (the issue lists it as optional). The creation-time 400 and the named sync alert cover the two places the failure used to hide.
• Re-probing when a per-agent PAT is changed later (PUT .../github-pat). That could be a follow-up; the named sync_failing item catches it within three cycles.

Changes

• src/backend/services/git_service/provisioning.py: probe_push_access, is_push_denied, _PUSH_DENIED_PATTERNS (re-exported from the package)
• src/backend/services/agent_service/crud.py: _validate_push_access, plus the will_push gate at the create call site
• src/backend/services/sync_health_service.py: the named sync_failing item
• Tests:
  • tests/unit/test_2107_push_access_probe.py (17, new): real git against a local fake smart-HTTP server; covers the 403 with GitHub's text, a valid receive-pack advertisement (nothing POSTed), 5xx and unreachable. It also asserts the token arrives as an Authorization header and is absent from git's argv, and covers the classifier table.
  • test_1484_create_agent_characterization.py: +4 through the full create_agent_internal. A refused push gives a 400 with no container and no branch reserved; a transient failure doesn't block; source mode is never probed. The harness's _git_auto_sync_baked is now the faithful predicate instead of a truthy MagicMock.
  • test_sync_health_service.py: +2 on the real DB harness (named push-denied item; ordinary failure unchanged).
• Docs: github-sync.md (probe section + error table), git-sync-health.md (alert branch)

Test Plan

• New and touched suites green with random ordering (2107 17, 1484 49, sync_health_service 47, 1028 package surface, ent123, fork_to_own, 1595_sync_health_signals, ent109_repo_binding)
• Mutation: with the fix reverted, 20 of the 23 new tests fail. The 3 that stay green are behaviour-preserving (transient doesn't block, source mode isn't probed, ordinary failure unchanged).
• Against real GitHub, using a token (user repo scope) that can write one repo and not another:
  • octocat/Hello-World → ('denied', 'remote: Permission to octocat/Hello-World.git denied to <user>.')
  • Abilityai/trinity → ('ok', '')
  • ls-remote afterwards shows no __trinity_write_probe ref, so the dry run created nothing.
  • The fine-grained read-only text (Write access to repository not granted.) comes from the issue's observed data. It's covered by the fake-server test; I had no such token to reproduce it live.
• lint_sys_modules, lint_root_test_placement clean

Fixes #2107

🤖 Generated with Claude Code

[vybe]

merge-train: batch validated on train/20260925-1608 (#3027, full suite green).