Background Watch Hook
Use vibe watch for a durable wait that resumes an Agent when an external event
arrives. The waiter detects events; the follow-up Agent verifies live state and
acts. A success candidate is not merge authorization.
Contract and lifecycle
| Waiter exit | Meaning |
|---|
0 | One new reportable event; summary on stdout |
75 (or configured retry code) | Still waiting; no Agent turn |
64 plus avibe-watch: no-event on stderr | Quiet completed cycle: retire once, re-arm forever |
124 or other terminal failure | Notify the Agent and stop |
A bare 64 is an error. Keep diagnostics on stderr. A once Watch waiting for its
first event uses a retry code, not 64. Forever waiters need durable cursors or
edge detection; a persistent true condition is not a new event. Avibe serializes
follow-ups, re-arms after they settle, and pauses rapid repeated events for repair.
- Read
vibe watch add --help before first use; inspect/update with
vibe watch <list|show|update|pause|resume|remove>.
--timeout bounds each cycle (default six hours); --lifetime-timeout bounds
the whole Watch. Use 0 for an intentionally unbounded PR delivery loop.- Remove the Watch at close-out. Do not use detached shells for durable waits.
Session targeting
- Inside an Avibe-injected Agent shell, omitting the target continues this conversation.
- Use
--session-id <id> only when resuming a different existing Agent Session.
- Use
--create-session --same-scope for one visible sibling Session; use
--create-session-per-run --same-scope for a separate visible Session per event.
- Use
--scope-id <scopes.id> instead of --same-scope for an explicit scope.
- If
--cwd is omitted, Avibe uses the command's current working directory.
Preferred PR + CI watch
Use --forever and one owner-specific state file for the whole loop. Seed and
arm before the watched push/review trigger; for a new PR, create it first, then
immediately seed/arm. Keep the same Watch and cursor across all later rounds.
wait_pr.py --workflow <actual-name> combines PR activity with exact-head CI;
repeat --workflow for every required workflow. Omit --sha to follow pushes.--coalesce-success: keep half-success quiet; report one same-head CI/review
success candidate. Findings, errors and unfamiliar results remain reportable.--actionable-only drops review triggers and empty envelopes; --settle 20
batches review bursts. New CI failures bypass settle. Final gates belong to
pr-delivery-loop, including the stricter qualification of Codex reactions.- Set
--timeout 0 on both sides of the -- command separator; six quiet hours
is not a PR failure. Verify workflow names: missing CI is never green.
- Never reseed or replace its state between rounds. Filters/reporting modes are
part of cursor ownership; enable them on the initial seed and armed command.
- Cursor corruption, ownership conflicts or write failures require repair with
evidence preserved, not a fresh baseline. Retryable GitHub failures keep waiting.
Run scripts from the loaded Skill directory, not a guessed installation path:
BACKGROUND_WATCH_HOOK_DIR="<directory containing the loaded SKILL.md>"
STATE_FILE="$HOME/.avibe/state/watch-cursors/pr-151-review.json"
BRANCH="$(gh pr view 151 --repo avibe-bot/avibe --json headRefName --jq .headRefName)"
uv run --no-project "$BACKGROUND_WATCH_HOOK_DIR/scripts/wait_pr.py" \
--repo avibe-bot/avibe --pr 151 --branch "$BRANCH" \
--workflow lint --coalesce-success --actionable-only \
--state-file "$STATE_FILE" --seed-state
vibe watch add \
--name "Watch PR 151 review and CI" --forever --timeout 0 \
--message "PR #151 has an event. Follow pr-delivery-loop; verify live gates, handle findings/errors, and keep half-success silent." \
-- \
uv run --no-project "$BACKGROUND_WATCH_HOOK_DIR/scripts/wait_pr.py" \
--repo avibe-bot/avibe --pr 151 --branch "$BRANCH" \
--workflow lint --coalesce-success --actionable-only \
--settle 20 --state-file "$STATE_FILE" --interval 60 --timeout 0
After confirming the seeded Watch is live, push or trigger review. Check exactly
one live Watch per owner/PR/concern at each round's end. The state file stages
reports until delivery acknowledgement, so an undelivered report may replay;
never discard it merely to avoid a duplicate.
Other waits and troubleshooting
Use wait_pr.py without CI arguments for PR-only activity; use wait_action.py
for standalone Actions and wait_issue.py for issues. Do not combine --new-prs
with CI options. --catch-up and explicit cursors deliberately replay history,
not routine re-arming. Keep Watch messages short and action-oriented; reference
loaded policy rather than restating it on every fire.
Detailed waiter reference covers alternative commands,
filters, replay, authentication, and cursor/settle internals. Read it only for
those tasks or a concrete failure, not for routine PR monitoring.