feat(bin): fm-coderabbit-poll.sh — hourly host-cron CodeRabbit review babysitter

[depohmel]

Adds a host-cron poller that watches a captain-maintained queue of GitHub PRs, detects new CodeRabbit reviews, and dispatches a scoped one-shot crewmate per new actionable review.

Motivation

CodeRabbit free-tier's rate limit is 1 review per hour for the whole org. Existing supervision has no hook for "new external bot review posted on my PR"; a captain either polls manually or leaves reviews unaddressed. Session-based bin/fm-spawn.sh babysitters (tried on this fleet earlier this week) proved brittle for long-idle polling — the model wandered, hallucinated findings, or falsely declared clean without waiting for CodeRabbit to actually review.

Host-cron sidesteps both problems: strict hourly cadence, no live firstmate needed, and each fire spawns a one-shot crewmate with a scoped brief containing the exact review body.

What's here

• bin/fm-coderabbit-poll.sh — the poll. flock-guarded, per-PR watermarks in state/coderabbit-watermarks.tsv, spawns via existing bin/fm-spawn.sh.
• docs/coderabbit-poll.md — setup, cadence, files, watermark semantics, crontab example.
• docs/examples/coderabbit-queue.txt — commented example queue.

Design decisions worth review

• Host cron over CronCreate: doesn't depend on firstmate being live. Simpler failure mode (cron log tells you).
• One-shot crewmate per new review, not a persistent babysitter: previous per-session babysitter attempts wedged on idle polling. A crewmate spawned with the exact review body already in hand can't hallucinate findings; it either acts on the concrete body or declines with a comment.
• Watermark = review submitted_at timestamp, not id: naturally matches CodeRabbit's re-review flow; a fresh review with a newer timestamp triggers dispatch.
• Watermark advances on spawn success, not on crewmate done: if a crewmate wedges the operator handles it manually; the poll doesn't re-spawn a duplicate on the next fire. If spawn itself fails, watermark stays; next fire retries.
• Explicit crewmate scope hard rules in the brief: no merges, no force-push, docs and minor fixes only, decline destructive/scope-creep in a PR comment rather than escalating. Escalation reserved for hard blockers only.
• Actionable-count parsing from CodeRabbit body: Actionable comments posted: N marker; N=0 advances watermark without spawn. If CodeRabbit changes this format, the poll would need an update — this is the load-bearing external contract.

Tests

Smoke-tested locally against:

• Missing queue file → silent exit 0 (resting state).
• Empty queue → poll cycle complete, exit 0.
• Comment-only queue → poll cycle complete, exit 0.
• Malformed URL → warning + poll cycle complete, exit 0.

Not exercised end-to-end against a live CodeRabbit review here (would double-dispatch on the fleet's own in-flight PRs).

Not in this PR

• No AGENTS.md updates. If the feature ships, a follow-up should add the three new files (data/coderabbit-queue.txt, state/coderabbit-watermarks.tsv, state/coderabbit-poll.lock) to section 2's layout list.
• No unit tests under a tests/ dir. The script is mostly shell glue over gh api + fm-spawn.sh; a full test harness would need to mock the GitHub API.
• No CronCreate variant. Deferred until there's a concrete need for firstmate-driven scheduling.

🤖 Written by Claude Code

Pipeline

Updates from git push no-mistakes

Note: the no-mistakes pipeline was driven manually on this PR — axi run completed intent/rebase/review/test/document/lint successfully; the auto-stamp step failed only because the scratch worktree had HTTPS origin without push credentials. The review pass emitted one actionable finding (the hardcoded LiteLLM tier name in bin/fm-coderabbit-poll.sh), which is fixed by commit 2bb32a9 on this branch (env-var-driven, no hardcoded operator-private tier names).