Add roborev wait command to block until a review job completes

[jeremyjordan]

Summary

Fixes #226

When an external coding agent runs a review-fix refinement loop with roborev, the agent needs to know when a review finishes. Today the only option is roborev review --wait, which enqueues a new review and blocks. But in the common flow -- where a post-commit hook already triggers the review -- the agent just needs to wait for the result without submitting a duplicate job. This forces agents to poll roborev list or parse roborev show output, wasting tokens on repeated CLI invocations and output parsing.

roborev wait provides a token-efficient primitive for this: a single blocking call that exits with a machine-readable exit code. The agent commits, the hook enqueues the review, and the agent calls roborev wait to block until the verdict is ready.

This is convenient because it allows the user to fully control the editor agent - it can be launched in a special sandboxed environment if needed and it maintains the full context history of user interactions. The review agent provides "fresh eyes" through a new context window managed by roborev to complete the review and provide feedback.

Architecture

Agent commits code
       |
       v
Post-commit hook ──> roborev review ──> daemon enqueues job
       |
       v
Agent calls: roborev wait
       |
       v
CLI resolves HEAD ──> GET /api/jobs?git_ref=<sha>&repo=<path>&limit=1
       |                                   (existing daemon API, no changes)
       v
CLI polls: GET /api/jobs?id=<job_id>
       |        (reuses existing waitForJob with exponential backoff)
       v
Job completes ──> GET /api/review?job_id=<id>
       |
       v
Exit code signals verdict to agent:
  0 = PASS    1 = FAIL

No daemon, API, or storage changes are required. The command is purely a CLI-side consumer of existing endpoints.

Usage

roborev wait                   # Wait for most recent job for HEAD
roborev wait abc123            # Wait for most recent job for commit
roborev wait 42                # Job ID (if "42" is not a valid git ref)
roborev wait --job 42          # Force as job ID
roborev wait --sha HEAD~1      # Wait for job matching HEAD~1
roborev wait --quiet           # Suppress output (for hooks/agents)

Argument resolution: git ref first (handles ambiguous numeric SHAs like 123456), then numeric job ID fallback. --sha and --job flags disambiguate when needed. Worktrees are handled correctly -- refs resolve from the worktree HEAD while job lookups scope to the main repo path.

Design questions

• It seems like there are two different approaches we could take. roborev review --wait uses waitForJob() which I'm reusing here. But I see that roborev refine uses client.WaitForReview() which has some slightly different logic and returns the actual review from the job.

Example

Here's a snippet of a Claude Code session where I'm using a dev build of roborev which implements the wait command

⏺ All clean. Let me commit.                             
                                                                                          
⏺ Bash(git add cmd/roborev/main.go cmd/roborev/wait_test.go && git diff --cached --stat)  
  ⎿   cmd/roborev/main.go      |  7 +++++--                                               
      cmd/roborev/wait_test.go | 42 ++++++++++++++++++++++++++++++++++++++++++            
      2 files changed, 47 insertions(+), 2 deletions(-)                                   
                                                        
⏺ Bash(git commit -m "Validate wait command inputs: reject invalid refs and non-positive  
      job IDs…)                                                                           
  ⎿  [add-wait-command 5299820] Validate wait command inputs: reject invalid refs and     
      non-positive job IDs                                                                
      2 files changed, 47 insertions(+), 2 deletions(-)                                   
                                                                                        
⏺ Now let me wait for the post-commit review.                                             
                                                                                    
⏺ Bash(export PATH=~/go-sdk/go/bin:$PATH && roborev wait --sha HEAD --timeout 300)        
  ⎿  Error: Exit code 1                                                                 
     Waiting for review to complete... done!                                              
                                                                                          
     Review (by codex)                                                                    
     ------------------------------------------------------------                         
     Reviewing commit `5299820` now against the surrounding `wait` command flow so I can  
     validate behavior changes, not just the patch hunk. I’ll inspect the touched         
     functions and nearby error-handling paths, then report concrete findings with        
     severities and line references.                                                      
     I’ve finished checking the main code path and found one functional hole tied to this 
     change: non-positive IDs are only rejected for `--job`, not for numeric positional
     IDs. I’ll grab exact line references and finalize the review in the format you       
     requested.                                                                           
     I’m running the affected wait-command tests to confirm the behavior and validate     
     whether the uncovered positional-ID case is currently untested in execution as well  
     as in static inspection.                                                             
     1. **Summary**
     This commit tightens `wait` input validation by:
     … +20 lines (ctrl+o to see all)

⏺ Fair point — the positional numeric fallback also needs the <= 0 check. Let me fix that.

---

Disclaimer: this is my first time writing in Go, and I used coding assistants to help craft this feature. I have walked through the changes line by line (having the agent both explain the logic and show how it matches existing logic in the codebase) and made an effort to mirror the style and choices already established in the repo.

[roborev-ci]

roborev: Combined Review

Verdict: No Medium/High/Critical findings; the reviewed wait command changes appear clean.

All four review passes (security + default across both agents) reported no issues, and there were no deduplicated findings at Medium severity or above to include.

---

Synthesized from 4 reviews (agents: codex, gemini | types: default, security)

[roborev-ci]

roborev: Combined Review

Verdict: All reviewers agree this PR is clean with no Medium/High/Critical findings.

Consolidated Findings (Medium+)

No Medium, High, or Critical issues were identified across the four review outputs (security and default reviews).

---

Synthesized from 4 reviews (agents: codex, gemini | types: security, default)