fix(#2143): add pre-flight GitHub API connectivity check in sandbox

[fullsend-ai-coder]

Add a pre-flight connectivity check that runs inside the sandbox after bootstrap but before agent execution. The check sources the sandbox .env file and calls gh api /rate_limit to validate that api.github.com is reachable through the proxy.

When the proxy blocks the CONNECT tunnel (HTTP 403), the check fails fast with a clear diagnostic message instead of letting the agent burn its entire timeout on doomed API calls. The check is generic — it runs for all agents, not just retro — since any agent with GH_TOKEN needs GitHub API access.

The check gracefully skips when GH_TOKEN is not set or gh is not available in the sandbox, so agents that don't need GitHub API access are unaffected.

New files:

• internal/cli/preflight_github.go: connectivity check logic
• internal/cli/preflight_github_test.go: unit tests

Note: pre-commit could not run due to Go module cache permission issues in the sandbox (gitleaks hook failed to install). The post-script runs authoritative pre-commit on the runner.

---

Closes #2143

Post-script verification

• Branch is not main/master (agent/2143-preflight-github-api-check)
• Secret scan passed (gitleaks — a20c44f4d3f7f21c934cbd58bd255c1cf2420d24..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[github-actions]

Site preview

Preview: https://a6e11ee3-site.fullsend-ai.workers.dev

Commit: b252c40e289bc31a569339ea0f42f3d57ab6e57a

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:18 PM UTC · Completed 9:28 PM UTC
Commit: b252c40 · View workflow run →

[fullsend-ai-review]

Review

Findings

Medium

• [test-inadequate] internal/cli/preflight_github_test.go — Tests only verify struct field values and a timeout constant range. No tests exercise the actual checkSandboxGitHubConnectivity function — all sandbox.Exec interactions are untested. The function has multiple code paths (probe failure, NOTOKEN, NOGH, connectivity success, various error diagnoses for 403, DNS, connection refused) but none are tested through the function.
  Remediation: Add table-driven tests that mock or stub sandbox.Exec to cover each code path: probe failure, NOTOKEN, NOGH, successful connectivity, 403 error, DNS failure, connection refused, and generic failure.

• [missing-documentation] docs/guides/dev/cli-internals.md:313 — The Sandbox Lifecycle diagram does not document the new GitHub API connectivity pre-flight check introduced at step 9b-2. The diagram shows the flow going directly from "Security scan (input)" to "Exec() — Run agent in sandbox", but the PR adds a new checkSandboxGitHubConnectivity step that validates GitHub API reachability before agent execution.
  Remediation: Add a new step in the Sandbox Lifecycle diagram between the security scan and agent execution steps showing the GitHub API connectivity pre-flight check.

Low

• [data-exposure] internal/cli/preflight_github.go:82 — Error messages include raw gh api output which could contain token fragments, internal hostnames, or proxy configuration details. These error messages propagate to the caller and may be logged or displayed in CI output.

• [design-direction] internal/cli/preflight_github.go:23 — The function invokes gh api /rate_limit inside the sandbox via sandbox.Exec, which is a GitHub-specific operation in internal/cli/. While the forge abstraction rule (exec.Command("gh", ...) prohibition) targets host-side Go code and this runs inside the sandbox where agents use gh directly, a future forge-portable version would need to dispatch through the forge.Client interface. The current approach is pragmatic — the check must run from within the sandbox to validate the sandbox's network path — but worth noting for future forge portability work.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 2:26 PM UTC · Completed 2:31 PM UTC
Commit: b252c40 · View workflow run →

[fullsend-ai-retro]

Retro: PR #2144 — Pre-flight GitHub API connectivity check

Timeline

1. Issue Retro agent sandbox cannot reach GitHub API (proxy 403) #2143 filed by retro agent from PR fix(#2134): consolidate protected path lists into single source of truth #2136 — sandbox can't reach GitHub API (proxy 403)
2. Triage completed in ~4 minutes, classified as high-priority bug
3. Code agent produced PR fix(#2143): add pre-flight GitHub API connectivity check in sandbox #2144 in ~10 minutes with preflight_github.go and tests
4. Review agent flagged two medium findings: [test-inadequate] (tests only verify struct field values, no code paths exercised) and [missing-documentation] (sandbox lifecycle diagram not updated)
5. Fix agent dispatched but failed — the dispatch payload contained PR fix(#2017): unenroll repos during uninstall via repo-maintenance workflow #2020 instead of PR fix(#2143): add pre-flight GitHub API connectivity check in sandbox #2144 (run 27307666014). The eligibility gate rejected the mismatched PR and all downstream steps were skipped
6. Two humans approved and merged ~17 hours later with medium review findings unaddressed

Analysis

The core issue is a fix agent dispatch routing bug that sent the wrong PR number in the payload. Because the fix never ran and no notification was posted on the PR, the medium-severity findings (especially the shallow tests that only check struct values without exercising checkSandboxGitHubConnectivity) were silently dropped. The humans who approved may not have realized the fix agent never attempted remediation.

Existing coverage

All improvement opportunities identified are already covered by open issues:

• Fix dispatch passing wrong PR number to review workflow #1326 — Fix dispatch passing wrong PR number (exact bug observed here)
• Dispatch shim should post a reaction or comment when /fs-fix dispatch fails #1920 — Dispatch shim should post a reaction/comment when fix dispatch fails (would have made the failure visible)
• Code agent should write tests with values that exercise the logic under test #1851 — Code agent should write tests that exercise logic, not just struct fields (recurring pattern)
• Auto-file tracking issues for unresolved medium+ severity review findings #1956 — Auto-file tracking issues for unresolved medium+ review findings (would catch cases where findings are merged unaddressed)

No new proposals filed — all identified improvements already have open tracking issues.