Ca Watch

$ca-watch — PR CI babysitter

Watch a pull request's checks to completion without babysitting them by hand. The

wait happens server-side, so it costs nothing while CI runs; arbiter wakes once, on

the verdict — diagnoses a red, or offers you the merge on a green. Arbiter never

pulls the merge trigger.

Precondition

Requires the GitHub CLI authenticated (gh auth status). If gh is absent or

unauthenticated, report the precondition failure naming gh and STOP — do not start

a phantom watcher.

Flow

• Resolve the PR from $ARGUMENTS (number, URL, or branch; default to the

current branch's PR).

• Watch to completion — run the watch as a detached background task built on

the server-side block:

   gh pr checks <PR> --watch

This blocks until every check finishes and then exits non-zero on failure. It is

NOT a polling loop — there is no interval-based wake-up. Arbiter is re-invoked once

when the watch process exits.

• On red — retrieve the failing job's logs (gh run view --log-failed /

gh pr checks) and act at the configured depth. Resolve that depth with the

canonical resolver rather than reading the env var by hand (so the accepted

values can't drift):

   python3 "${CLAUDE_PLUGIN_ROOT}/hooks/babysit.py" --root "<project-root>" || python "${CLAUDE_PLUGIN_ROOT}/hooks/babysit.py" --root "<project-root>"

It prints one JSON line; act at its on_red value (CODEARBITER_BABYSIT_ONRED,

default propose):

• propose — name the likely cause and propose a concrete fix. Do NOT edit

any tracked file; applying the fix routes through $ca-fix or $ca-feature.

• branch — additionally open a spike/fix-* branch carrying the proposed

change for review. That branch is a spike: it can never PR or merge. The default

branch is left untouched.

• On green — notify the user and present a merge offer (the gh pr merge

command, ready to run). The watcher itself NEVER merges. If the PR targets the

default branch, the merge routes through the merge-to-default hard gate — the offer

cannot bypass it.

On/off

A global flag, CODEARBITER_BABYSIT (default off, mirrors CODEARBITER_PRUNE),

governs auto-attachment: when on, $ca-pr auto-attaches a watcher to the PR it

opens. $ca-watch <PR> works ad-hoc regardless of the flag. The flag is never set on

the user's behalf — enabling it is the user's explicit choice. Both the command and

the flag are dormant in a repo without arbiter: enabled.

When NOT to use

• Open the PR first → $ca-pr.
• Apply a fix for a diagnosed red → $ca-fix (or $ca-feature).
• Review a diff without watching CI → $ca-review.

Hard gate

• MUST NOT auto-merge. Green → notify + offer only; the watcher never invokes

gh pr merge.

• A merge into the default branch MUST route through the merge-to-default hard gate —

the green offer cannot and does not bypass it.

• MUST NOT implement a polling loop that re-invokes the model on a timer — the watch

is the server-side gh pr checks --watch block.

• MUST surface a missing/unauthenticated gh as a precondition failure, not a silent

no-op.

• At depth propose MUST NOT edit any tracked file; at depth branch the proposed

change lands only on an unmergeable spike/fix-* branch.