Add bounded PR detail fill command

[TurboTheTurtle]

Closes #83.

Adds a bounded fill-pr-details command that selects pull requests missing detail rows, hydrates them in batches, reports progress/results for retryable backfills, and ignores expired or stale shared rate-limit cache entries before enforcing --reserve-rate-limit.

Behavior proof:

{"event":"batch_done","repository":"openclaw/gitcrawl","batch":1,"numbers":[89],"filled":1}
{"repository":"openclaw/gitcrawl","selected":1,"filled":1,"remaining":0,"numbers":[89],"order":"newest-first","limit":1,"batch_size":1}

The proof run used a throwaway local archive where openclaw/gitcrawl#89 was first synced with pr_details_synced: 0, then hydrated by gitcrawl fill-pr-details openclaw/gitcrawl --limit 1 --batch-size 1 --json-progress --json.

[clawsweeper]

Codex review: found issues before merge. Reviewed July 10, 2026, 2:13 PM ET / 18:13 UTC.

Summary
The PR adds a fill-pr-details CLI command that selects missing pull-request detail rows and hydrates them in ordered batches with JSON progress, optional comments, and rate-limit reserve controls.

Reproducibility: yes. from source inspection: begin with remaining quota slightly above the reserve and hydrate a PR whose detail sync makes multiple API calls; no reserve check runs again until the whole batch finishes.

Review metrics: 3 noteworthy metrics.

• Changed surface: 4 files, 573 additions, 0 deletions. The patch is focused but establishes a new production CLI and JSON contract.
• Quota granularity: 1 reserve check per batch. A batch performs multiple GitHub requests, so one pre-batch snapshot cannot guarantee the configured reserve.
• Reserve coverage: 1 below-threshold test, 0 crossing tests. Current coverage does not exercise the unsafe transition from above the reserve to below it during hydration.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #83
Summary: This PR is the direct implementation candidate for the canonical bounded PR-detail fill request.

Members:

• canonical: Add bounded PR-detail fill #83 - The PR uses closing syntax and implements the issue's requested bounded hydration workflow.
• partial_overlap: Track initial local maintainer-archive use friction #81 - The parent archive-friction tracker includes long PR-detail hydration among several distinct follow-up problems.
• adjacent_distinct: Add archive coverage reporting #82 - Coverage reporting identifies missing detail rows but does not perform the hydration implemented here.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦞 diamond lobster
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P2] Fix or explicitly narrow the reserve-rate-limit contract and add a threshold-crossing regression test.

Risk before merge

• [P1] A batch can consume GitHub API quota below the configured reserve, leaving less capacity than an operator deliberately retained for other tools or follow-up work.
• [P1] Changing the option from strict reserve enforcement to best-effort pre-batch stopping is a public CLI contract decision requiring explicit maintainer intent.

Maintainer options:

1. Make quota behavior truthful (recommended)
   Implement strict in-batch reserve enforcement or explicitly narrow the flag to best-effort semantics, then add a threshold-crossing regression test.
2. Accept possible quota overshoot
   Merge only if maintainers explicitly accept and document that each batch may spend below the configured threshold.
3. Pause quota-aware fill
   Pause the PR if the sync layer cannot yet support a clear and safe quota contract.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Ensure the quota option cannot promise a preserved reserve that a started batch can consume through; either add strict in-batch request-budget enforcement or rename and document best-effort semantics, and add a regression test starting just above the threshold.

Next step before merge

• [P2] A maintainer must choose strict reserve enforcement versus explicitly best-effort semantics before the mechanical repair path is unambiguous.

Maintainer decision needed

• Question: Must --reserve-rate-limit strictly preserve the configured remaining quota, or should it be an explicitly best-effort pre-batch threshold that may overshoot?
• Rationale: The current flag name implies a stronger guarantee than the implementation provides, and choosing strict enforcement versus weaker documented semantics is a public product-contract decision.
• Likely owner: steipete — He introduced both the PR-detail hydration and shared rate-limit mechanisms whose contract this feature combines.
• Options:
  • Strictly preserve the reserve (recommended): Add request-budget or in-batch stopping support so hydration cannot consume below the configured quota reserve.
  • Document best-effort behavior: Rename and document the option so users understand that a started batch may consume below the threshold.
  • Remove the reserve option: Land bounded selection and progress without quota-reserve behavior until the sync layer supports a clear guarantee.

Security
Cleared: The Go-only CLI and store diff introduces no dependency, workflow, permission, secret, download, package-resolution, or artifact-execution concern.

Review findings

• [P1] Preserve the requested rate-limit reserve within each batch — internal/cli/app.go:2908-2914

Review details

Best possible solution:

Make the quota contract truthful: preferably enforce a request budget during hydration so the configured reserve is preserved, or explicitly rename and document the option as a best-effort pre-batch threshold, with a regression test that starts just above the threshold and crosses it during work.

Do we have a high-confidence way to reproduce the issue?

Yes from source inspection: begin with remaining quota slightly above the reserve and hydrate a PR whose detail sync makes multiple API calls; no reserve check runs again until the whole batch finishes.

Is this the best way to solve the issue?

No in its current form; the bounded command is a reasonable solution, but its reserve option must either enforce the stated guarantee or accurately describe weaker best-effort behavior.

Full review comments:

• [P1] Preserve the requested rate-limit reserve within each batch — internal/cli/app.go:2908-2914
  The reserve check runs only before a batch. Starting at reserve+1 can still launch several PR-detail API calls and consume well below the quota the operator asked to preserve. Add an in-batch budget or stop mechanism, use safely budgeted work units, or rename the option to explicitly best-effort semantics and cover the crossing case. This was equally visible on the earlier reviewed head and is a late discovery.
  Confidence: 0.98
  Late finding: first raised on code an earlier review cycle already covered.

Overall correctness: patch is incorrect
Overall confidence: 0.97

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 808b4dabeaa4.

Label changes

Label changes:

• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (live_output): The PR body shows after-fix live JSON output from a throwaway archive where one missing PR-detail row was selected and hydrated; the proof does not cover quota crossing during a batch.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.
• remove status: 👀 ready for maintainer look: Current PR status label is status: ⏳ waiting on author.

Label justifications:

• P3: This is a low-urgency additive maintainer workflow feature, although its quota semantics should be corrected before merge.
• merge-risk: 🚨 other: Merging can consume API quota that operators explicitly attempted to preserve, a risk not resolved by ordinary CI.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (live_output): The PR body shows after-fix live JSON output from a throwaway archive where one missing PR-detail row was selected and hydrated; the proof does not cover quota crossing during a batch.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body shows after-fix live JSON output from a throwaway archive where one missing PR-detail row was selected and hydrated; the proof does not cover quota crossing during a batch.

Evidence reviewed

Acceptance criteria:

• [P1] GOWORK=off go test ./internal/cli ./internal/store.

What I checked:

• Reserve checked only before batch: The loop compares cached remaining quota to the reserve once before starting each batch, then runs the complete targeted PR-detail sync without another reserve guard. (internal/cli/app.go:2908, b1ee4a2c1c66)
• Each batch can consume multiple requests: A selected batch is passed to the existing sync service with PR details enabled; that hydration fetches several PR-detail resources, so starting slightly above the reserve can finish below it. (internal/cli/app.go:2929, 7222fef197b4)
• Crossing case lacks coverage: The reserve test verifies stopping when cached quota is already below the threshold, but does not begin above it and simulate a batch consuming through the reserve. (internal/cli/app_test.go:3922, b1ee4a2c1c66)
• Prior merge blocker resolved: The July 10 head merges current main and GitHub reports the PR mergeable, so the earlier dirty-base concern no longer blocks review. (internal/cli/app.go:164, b1ee4a2c1c66)
• Late-finding continuity: The reserve implementation was already present on the earlier reviewed SHA and is materially unchanged on the current head; this concern was equally visible during the prior cycle. (internal/cli/app.go:2908, e0621ab1cb09)
• Real behavior proof: The PR body includes live JSON output from a throwaway archive showing one missing detail row selected and successfully hydrated; it does not exercise reserve crossing. (b1ee4a2c1c66)

Likely related people:

• steipete: Peter Steinberger introduced the cached PR-detail hydration path and shared rate-limit behavior reused by this command, making him the strongest contract owner for their composition. (role: feature owner; confidence: high; commits: 7222fef197b4, 7598e3bcc54f, 300090ef7a62; files: internal/cli/app.go, internal/cli/gh_rate_limit.go, internal/github/client.go)
• vincentkoc: Vincent Koc has the largest sampled commit count across the central CLI and GitHub-client files, making him a useful adjacent reviewer for command and output behavior. (role: recent CLI area contributor; confidence: medium; files: internal/cli/app.go, internal/cli/gh_rate_limit.go, internal/github/client.go)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (2 earlier review cycles)

• reviewed 2026-07-01T20:10:59.960Z sha e0621ab :: needs maintainer review before merge. :: none
• reviewed 2026-07-09T19:19:35.428Z sha e0621ab :: needs maintainer review before merge. :: none

[TurboTheTurtle]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[TurboTheTurtle]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.