/watch

name: watch
description: >
  Start (or stop) the nyann CI sentinel for the current repo, OR manage a
  multi-repo watch-list and poll all watched repos at once. The sentinel
  polls open PRs for state transitions (CI failure, approval, merge,
  branch staleness) and emits notifications the session-start hook
  surfaces on your next prompt.
  TRIGGER when the user says "watch this PR", "watch my PRs", "ping me
  when CI passes", "tell me when CI fails", "background watch",
  "keep watching after I close this", "run the sentinel in the background",
  "daemonize the watcher", "watch in the background",
  "/nyann:watch", "/nyann:watch --pr <N>", "/nyann:watch --daemon",
  "stop watching", "/nyann:watch --stop".
  ALSO TRIGGER for multi-repo aggregation: "watch all my repos", "watch
  across repos", "add a repo to my watch list", "add <owner/repo> to watch",
  "remove <owner/repo> from watch", "list watched repos", "what's new across
  all my repos", "poll every repo I'm watching", "/nyann:watch --add",
  "/nyann:watch --remove", "/nyann:watch --list".
  Do NOT trigger on "wait for checks" — that is `/nyann:wait-for-pr-checks`
  (blocking poll). watch is fire-and-forget; wait-for-pr-checks blocks.

watch

> **Plugin root:** `<plugin_root>/skills/watch/SKILL.md` — scripts live > at `<plugin_root>/bin/ci-sentinel.sh`, `bin/sentinel-daemon.sh`, > `bin/sentinel-aggregate.sh`, and `bin/read-notifications.sh`.

Two modes:

• **Single repo** (Steps 1–3): poll the current repo's PRs directly —

one-shot, or as a supervised background daemon (`--daemon`).

• **Multi-repo** (Step 4): keep a watch-list of repos and poll them all

under one rate-limit-aware scheduler. Use this when the user watches PRs across several repos and wants one merged view.

Step 1: Resolve repo

Use `gh repo view --json nameWithOwner --jq .nameWithOwner` to get the `<owner>/<repo>` slug for the current directory. If `gh` is missing or the repo has no GitHub remote, tell the user to set one up and stop.

Step 2: Start, stop, or list

If the user said "stop" / `--stop`, stop BOTH a one-shot poll and any backgrounded daemon (the daemon stop tears down the supervisor unit too):

bash <plugin_root>/bin/sentinel-daemon.sh stop --repo <owner/repo>

For a single foreground poll cycle (default — fire-and-forget):

bash <plugin_root>/bin/ci-sentinel.sh --repo <owner/repo> [--pr <N>]

The sentinel is one-shot per invocation — each run polls the named PR(s) once and writes notification entries to `~/.claude/nyann/notifications/<repo-hash>.jsonl`.

Backgrounded daemon (`--daemon`) — opt-in

Only when the user explicitly asks to keep watching after the session ends (`--daemon`, "background watch", "keep watching after I close this"), offer the supervised daemon. **Do not start it implicitly** — a long-running background process is opt-in, mirroring the session-triage hook-install precedent. Confirm first, then:

bash <plugin_root>/bin/sentinel-daemon.sh start --repo <owner/repo> [--pr <N>]

This launches `ci-sentinel.sh --daemon-loop` under a platform supervisor (launchd on macOS, a systemd user unit on Linux, `nohup` fallback otherwise) so it survives the terminal closing. It polls every interval, backs off on `gh` failures, and self-terminates at `--max-runtime` (default 8h) as an orphan backstop. Starting is idempotent — a daemon already running for the repo is left alone.

> **Delivery secrets under a supervisor:** if a notification delivery > channel is configured, `start` hands its secret to the launchd/systemd > session so the supervised daemon can reach it. While the daemon runs the > secret is visible to your other same-user processes in that session; it is > cleared on `stop`. (The `nohup` fallback inherits your shell env directly > and exposes nothing extra.)

Report status (pid + supervisor + watched PRs; flags a stale daemon) with:

bash <plugin_root>/bin/sentinel-daemon.sh status --repo <owner/repo>

`doctor` also surfaces any running/stale sentinel so it's never invisible.

Step 3: Show outstanding notifications

After polling (or whenever the user asks "what's new on my PRs?"):

bash <plugin_root>/bin/read-notifications.sh --repo <owner/repo>

This reads all queued notifications and truncates the file. Use `--peek` if you want to leave the queue intact.

Render the result as a short list:

[nyann] 2 notifications since last check:
  - PR #42: CI failed (2h ago)
  - PR #43: approved (15m ago)

Step 4: Multi-repo watch-list (aggregation)

When the user watches PRs across several repos, manage a watch-list and poll them all at once instead of running the single-repo flow per repo. The watch-list lives at `~/.claude/nyann/watch-list.json` (an array of `{repo, prs?}`); manage it via `bin/sentinel-aggregate.sh`, because one scheduler must own the GitHub rate budget for all repos.

Add / remove / list watched repos:

bash <plugin_root>/bin/sentinel-aggregate.sh --add <owner/repo> [--pr <N>]
bash <plugin_root>/bin/sentinel-aggregate.sh --remove <owner/repo>
bash <plugin_root>/bin/sentinel-aggregate.sh --list

`--add` is idempotent (re-adding never duplicates; `--pr` merges into the repo's PR set), so you can run it freely. Malformed slugs are rejected.

Poll every watched repo in one cycle:

bash <plugin_root>/bin/sentinel-aggregate.sh --poll

This runs `ci-sentinel.sh` once per repo, but a single scheduler tracks the GitHub core rate budget and backs off **globally** (adaptive interval, all repos) when the budget runs low — because N repos × M PRs would otherwise blow the 5000/hr ceiling. It prints a scheduler-summary JSON (`current_interval` tells a supervising daemon how long to sleep next).

To keep the whole watch-list polling **in the background** after the session ends (same opt-in confirm as the single-repo daemon — a long-running process is never started implicitly), supervise the aggregate loop via the daemon manager:

bash <plugin_root>/bin/se