feat(local-review): offline committed-range branch review on Commit Sweeper

[anagnorisis2peripeteia]

What

local-review: an offline, pre-PR review of the current branch's committed range, built on Commit Sweeper. This replaces the closed #253 / #274 — rebuilt from scratch on current main to address every point in the #253 closure.

It reviews merge-base(<base>, HEAD)..HEAD as a single unit via the existing Commit Sweeper engine (runCodexProcess), reusing its codex worker, report writer, and classifier — no faked PR object.

clawsweeper local-review --base main
# reviews your whole branch locally, writes ~/.clawsweeper-local-reviews/run-*/local-review.md

How it addresses the #253 closure

• Committed-range review built on Commit Sweeper — calls the existing engine over base..HEAD.
• Requires a clean checkout — refuses a dirty working tree.
• Unique temporary directory — per-run run-<sha>-<ts>-<pid>/; no shared item-0 / result-path collision.
• Passes no GitHub token — withholds token env vars, skips the gh-api metadata hydration in offline mode, and points GH_CONFIG_DIR at an empty dir so the spawned reviewer can't fall back to cached gh auth.
• Rejects unsupported repositories — errors rather than falling back to a foreign profile.
• Current Codex infra — fresh off main, uses runCodexProcess (the branch no longer predates it).

Proof — it reviewed its own PR

Ran local-review on this branch against origin/main:

1. It flagged a real offline leak — commitMetadata still shelled out to gh api. Fixed (skip gh in offline mode).
2. Re-run flagged the deeper version — the spawned reviewer could still reach gh via the review prompt. Fixed (isolate GH_CONFIG_DIR).
3. Final run: clean (result: nothing_found, high confidence).

Both offline fixes in this PR were found by the tool reviewing itself.

Tests / not tested

• Added a hermetic test for the offline-metadata contract (commitMetadata(..., offline=true) reads only local git, never calls gh).
• Local: build + lint (type-aware, -D correctness) + oxfmt + targeted tests pass.
• Not covered yet: localReviewCommand's guard paths (clean-checkout / no-commits / reject-unsupported) — they process.exit / spawn codex. Happy to add a CLI-level fixture test before un-drafting.
• Did not run the full suite locally (integration tests need services); relying on CI.

Direction check

This is the Commit-Sweeper-based replacement described in the #253 closure. Opening as draft to confirm the approach and scope match what you intended before I polish coverage — does this look right?

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 15, 2026, 4:36 PM ET / 20:36 UTC.

Summary
Adds a local-review Commit Sweeper subcommand, package script, docs, and tests for offline review of the current branch's committed merge-base-to-HEAD range.

Reproducibility: not applicable. this is a feature PR, not a current-main bug report. Source inspection confirms current main and v0.2.0 lack the requested local-review command and still document branch review as out of scope.

Review metrics: 3 noteworthy metrics.

• Changed Surface: 4 files, +269/-11. The patch is compact but touches runtime command code, package scripts, docs, and tests.
• Command Surface: 1 subcommand, 1 package script. A new contributor-facing local entrypoint changes how ClawSweeper can be invoked before a PR exists.
• Offline Guard Coverage: 5 tests added. The tests cover the credential boundary and early-exit guards that matter most for this feature.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

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

Rank-up moves:

• none.

Risk before merge

• [P1] Merging this intentionally expands Commit Sweeper from hosted main-only commit reports to a contributor-run local committed-range branch review lane.
• [P1] The offline/no-GitHub-auth boundary is security-sensitive; the patch strips token env vars and isolates GH_CONFIG_DIR, but maintainers should explicitly accept that policy before merge.

Maintainer options:

1. Accept Local Review Boundary
   Maintainers can merge after normal review if they are comfortable supporting a local-only Commit Sweeper branch review command that withholds GitHub auth.
2. Pause Scope Decision
   If maintainers are not ready to support contributor-run local branch review, keep this PR open for direction or close it as out of scope.

Next step before merge

• [P2] The remaining action is maintainer acceptance of the new local-review product boundary and offline-auth policy, not a narrow automated repair.

Security
Cleared: No concrete security regression remains visible in the latest diff; the offline path skips GitHub metadata hydration, isolates GH_CONFIG_DIR, and scrubs GitHub token env vars before spawning Codex.

Review details

Best possible solution:

Land the local-review lane if maintainers accept the feature scope, preserving local-only report output, clean-checkout enforcement, and the no-GitHub-auth boundary.

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

Not applicable: this is a feature PR, not a current-main bug report. Source inspection confirms current main and v0.2.0 lack the requested local-review command and still document branch review as out of scope.

Is this the best way to solve the issue?

Yes, if maintainers want the feature: reusing the existing Commit Sweeper engine for a clean committed range is a narrow implementation path. The remaining question is whether the local branch review and offline-auth policy belong in core.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P2: This is a useful local automation feature with limited blast radius but a merge-sensitive credential boundary.
• merge-risk: 🚨 automation: The PR adds a new Commit Sweeper command that invokes Codex over a local committed branch range.
• merge-risk: 🚨 security-boundary: The PR defines a no-GitHub-auth local review boundary and changes which credentials reach the spawned reviewer process.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. Offline committed-range review could give contributors pre-PR feedback while reusing the existing Commit Sweeper engine instead of adding a separate review stack.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body provides after-fix local-review self-review proof, including two offline leaks found and fixed before a final clean result.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body provides after-fix local-review self-review proof, including two offline leaks found and fixed before a final clean result.

Evidence reviewed

What I checked:

• AGENTS.md policy read: Repository policy was read fully and applied because this PR changes ClawSweeper automation, docs, and security-sensitive subprocess behavior. (AGENTS.md:1, b00e25933977)
• Current main lacks the command: Current main dispatches review, classify, publish-check, reports, copy-artifacts, and dispatch-findings, with no local-review command branch. (src/commit-sweeper.ts:788, b00e25933977)
• Current docs keep branch review out of scope: Current main still documents Commit Sweeper as main-only and says PR or branch review is deliberately out of scope for that lane. (docs/commit-sweeper.md:254, b00e25933977)
• Latest release also lacks the feature: The latest release tag v0.2.0 still contains the main-only branch-review-out-of-scope wording, so the requested feature is not shipped. (docs/commit-sweeper.md:248, 5c4e4dcbe287)
• PR head implements the local lane: PR head adds LOCAL_REVIEW_SCRUBBED_TOKEN_ENV, localReviewCommand, clean-tree checks, range selection, unique report directories, empty GH_CONFIG_DIR, and read-only Codex invocation. (src/commit-sweeper.ts:390, c22dd1ea81cc)
• Focused tests cover the offline contract and guards: The new test file covers offline commit metadata, dirty-tree refusal, unsupported repo rejection, no-commits-beyond-base handling, and the GitHub token scrub list. (test/local-review.test.ts:43, c22dd1ea81cc)

Likely related people:

• steipete: Recent main history shows substantial work on Codex subprocess hardening and adjacent automation paths used by Commit Sweeper. (role: recent Codex subprocess and automation contributor; confidence: high; commits: 499e86783b2a, 86d0ca37755b, f6721ebce2f4; files: src/codex-process.ts, src/codex-spawn.ts, src/commit-sweeper.ts)
• anagnorisis2peripeteia: Current main includes this contributor's local Codex OAuth and Windows launcher work in the same local-run surface, beyond authoring this PR. (role: recent adjacent local Codex contributor; confidence: high; commits: b00e25933977, f6721ebce2f4; files: src/commit-sweeper.ts, src/codex-env.ts, src/codex-spawn.ts)
• joshavant: Recent history shows worker-default and automation documentation updates near the Commit Sweeper documentation surface touched by this PR. (role: recent adjacent automation docs contributor; confidence: medium; commits: be65dd0db8a3, 2e4282b3acfc; files: docs/commit-sweeper.md, package.json)

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.

[anagnorisis2peripeteia]

@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.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27571044226
• Updated: 2026-06-15T19:34:37.446Z

[anagnorisis2peripeteia]

@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.

Re-review progress:

• State: Superseded
• Detail: A newer re-review for this item started before this run finished, so GitHub cancelled this older run. Check the latest ClawSweeper run for the current result.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27572099292
• Updated: 2026-06-15T19:53:30.301Z

[anagnorisis2peripeteia]

@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.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27572834488
• Updated: 2026-06-15T20:08:59.928Z

[steipete]

Landed in d877d4e.

Verification:

• focused local-review build and tests passed, including offline metadata, dirty-tree rejection, generic-fallback rejection, token scrubbing, and web-search/network denial
• autoreview clean after enforcing disabled Codex web search and configured-profile-only lookup
• GitHub pnpm check, Windows launcher, and CodeQL passed