frizz-server 0.13.0

package/runtime/cc-worker/hooks/session-seed.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// @ts-check
+// SessionStart hook (frizz-worker) — SEEDS a frizz WORKER session's context. Run directly with
+// node (zero deps, max Node compat), mirroring cc's hook idiom.
+//
+// A frizz worker is a top-level interactive `claude` the UI spawns per effort; the slug arrives in
+// env FRIZZ_THREAD (and a `THREAD:` line in the first prompt). There are NO thread files, no
+// frontmatter, no status field — a worker SIGNALS through its final message (fences), and anything that
+// must outlive its context window is an arrangement it makes for itself. This hook injects, on every
+// session start (startup/resume/clear/compact):
+//   1. `core` — a runtime POINTER, not a copy of the contract: the full worker contract lives ONCE in
+//      the system prompt (workerPrompt.ts) the server injects at spawn. This carries only what a
+//      static system prompt can't: the runtime scratch-directory PATH, and a one-line pointer.
+//   2. the SCRATCH DIRECTORY — `.frizz/threads/<session_id>/`, a folder the worker may use as it likes.
+//   3. on `compact` — a short re-grounding (compaction drops the deep model + this orientation).
+//
+// GATE: everything is gated on FRIZZ_THREAD being set, so the plugin is completely inert when
+// loaded outside a frizz worker (e.g. a plain `claude --plugin-dir cc-worker` smoke run).
+//
+// STALE-INSTALL DEFENSE: the `cc` orchestrator plugin is retired — the marketplace ships only this
+// worker plugin, and cc's hooks/skills/agents are gone. But a machine can still carry a CACHED cc
+// install from before the retirement, whose hooks fire in every repo gated on cc's opt-IN sentinel.
+// A fresh worker never runs `frizz on`, so such a cc is already dormant; we write cc's own per-session
+// `off` sentinel anyway via the shared config API (board survives as cc-worker's board
+// implementation) so a stale install is guaranteed inert. Cheap belt-and-suspenders. See DECISIONS.md.
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { setSessionOverride, currentSessionId } from '../scripts/frizz/config.mjs';
+
+/** @type {{ agent_id?: unknown, agentId?: unknown, source?: string, session_id?: string }} */
+let input = {};
+try {
+  input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  /* no stdin / not JSON → input stays {} → proceed (fail-open to inject) */
+}
+// Skip inside sub-agent contexts (they carry agent_id) — the seed is for the top-level worker.
+if (input.agent_id ?? input.agentId) process.exit(0);
+
+// WORKER GATE — inert unless this is a frizz worker session.
+const thread = (process.env.FRIZZ_THREAD ?? '').trim();
+if (!thread) process.exit(0);
+
+const dir = process.env.CLAUDE_PROJECT_DIR ?? '.';
+
+// Neutralize the orchestrator cc plugin for THIS session (defensive; see header + DECISIONS.md).
+// The session id also names the worker's scratch directory (`.frizz/threads/<session_id>/`).
+let sid = null;
+try {
+  sid = currentSessionId(input.session_id);
+  if (sid) setSessionOverride(dir, sid, 'off');
+} catch {
+  /* best-effort — a failed sentinel write just leaves cc at its dormant default */
+}
+const scratch = sid
+  ? '.frizz/threads/' + sid + '/'
+  : '.frizz/threads/<session-id>/';
+
+// A RUNTIME pointer, NOT a copy of the contract. The full worker contract (signal fences,
+// scratch-directory rules, sub-agent rules, the question handback, the stop criterion) lives ONCE in
+// the system prompt frizz injects at spawn (workerPrompt.ts / loadWorkerPrompt) — re-applied on every
+// resume, and it survives compaction. This hook adds only what a static system prompt CANNOT carry:
+// the runtime-derived scratch-directory PATH, plus (below) the compaction re-read nudge and the
+// auth-gated gh guidance.
+//
+// It used to restate the fence protocol, the stop criterion and the autonomy rule in full — ~4.4 KB
+// (~1,100 tokens) on every startup, resume, clear AND compact, all of it already in the 42 KB system
+// prompt. Trimmed 2026-08-26 (maintainer: "Definitely trim the session seed hook if it's fully
+// repetitive") as part of cutting the per-session token overhead Frizz adds over a plain TUI session.
+const core =
+  '⟦frizz worker contract⟧ You are a frizz WORKER driving EXACTLY ONE effort. Your FULL operating contract — the end-of-turn signal fences (```done / ```awaiting — a question is a registered row, `mcp__frizz__ask`, and the only ```question fence is the EMPTY placement marker naming its id), the scratch-directory rules, the sub-agent rules, the question handback and the stop criterion — lives in your SYSTEM PROMPT; follow it there. ALWAYS SIGN OFF — a fence OR a registration (`ask`, `watch`, `done`); an open question is one, so rest normally and write no question fence for it.\n' +
+  'SCRATCH DIRECTORY (OPTIONAL): `' + scratch + '` — a folder kept FOR YOU, nothing in it read automatically, never a substitute for doing the work. Give each sub-agent its OWN file rather than a shared one.';
+
+const grounding =
+  '⟦frizz worker re-grounding (post-compaction)⟧ Context was just compacted. You are still the frizz worker for effort `' + thread + '` — read whatever you left yourself in `' + scratch + '` NOW to recover your working state and to-do list before asserting anything, and re-read any code before claiming how it is structured. Your system prompt still carries the full contract; sign off as it says.';
+
+// AUTH-GATED gh guidance — teach the worker to use `gh` well, but ONLY when signed in.
+// Shell `gh auth status --active`: exit 0 = an active gh account is authenticated. The whole gate is
+// wrapped so it can NEVER throw into SessionStart, and it fails CLOSED — no gh binary, not authed, a
+// stall past the timeout, or any other error → we inject NOTHING (guidance is absent, not stale/wrong).
+// It re-evaluates on every start/resume/clear/compact, so a later `gh auth login` starts injecting on
+// the next turn boundary (and a `gh auth logout` stops it). See DECISIONS.md / plan §8.
+const ghBlock =
+  '⟦gh available⟧ You are signed into the `gh` CLI and in a GitHub repo. Use `gh` EAGERLY and well — it is the fastest path to issue/PR/CI/release context, and you should reach for it before guessing:\n' +
+  '• READ freely: `gh issue view N -R OWNER/REPO --comments`, `gh pr view N`, `gh pr diff N`, `gh pr checks N`, `gh run list`/`gh run view`, `gh api repos/OWNER/REPO/…`. Prefer `--json <fields>` over scraping human text.\n' +
+  '• SEARCH across the repo (and GitHub) with `gh search issues`/`gh search prs` when hunting related work, duplicates, or prior art.\n' +
+  '• READ-ONLY BOUNDARY: never comment, label, assign, close, review, approve, or merge — no mutation of any kind — UNLESS the human explicitly asks in this session. Default to producing your findings/review as your final message, not as a GitHub post.\n' +
+  'Load the `frizz:gh` skill for the full playbook (recipes + explicit project-local monitor selection + native Monitor/background-Bash CI/PR watches).';
+
+let ghAuthed = false;
+try {
+  execFileSync('gh', ['auth', 'status', '--active'], { stdio: 'ignore', timeout: 4000 });
+  ghAuthed = true;
+} catch {
+  /* no gh / not authed / stalled → fail CLOSED: leave ghAuthed false, inject nothing */
+}
+
+const parts = [core];
+if (input.source === 'compact') parts.push(grounding);
+if (ghAuthed) parts.push(ghBlock);
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: parts.join('\n\n') },
+  }),
+);
+process.exit(0);

package/runtime/cc-worker/scripts/frizz/agent-bindings.mjs

@@ -0,0 +1,9 @@
+// @ts-check
+/**
+ * THIN SHIM — re-exports `board/agent-bindings.mjs` so the worker's PostToolUse
+ * `agent-bind` hook writes `.frizz/.agent-bindings.jsonl` records in the EXACT format the board
+ * (`bindingsByThread`) + Stop-hook liveness consume. Keeping the writer shared is what lets a
+ * worker's own THREAD-tagged sub-agent show up on the frizz board's per-thread liveness.
+ * Never fork this — the record shape is a cross-plugin contract.
+ */
+export * from '../../../board/agent-bindings.mjs';

package/runtime/cc-worker/scripts/frizz/config.mjs

@@ -0,0 +1,12 @@
+// @ts-check
+/**
+ * THIN SHIM — do NOT fork config logic. cc-worker shares the repo board's single source of truth
+ * for the activation gate, config schema, status vocab, and the per-session sentinel/heartbeat
+ * helpers. This re-exports `board/config.mjs` verbatim so cc-worker hooks can `import ... from
+ * '../scripts/frizz/config.mjs'` at the plugin-local path while the real code lives in ONE place.
+ *
+ * Coupling note: cc-worker assumes `board/` is a SIBLING dir (`../../board/` from the plugin root) —
+ * the same assumption frizz's server makes (see ARCHITECTURE.md: it imports the board logic from
+ * `../../board/*.mjs`). If that layout changes, this one path changes with it.
+ */
+export * from '../../../board/config.mjs';

package/runtime/cc-worker/skills/gh/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: gh
+description: The gh-CLI playbook for a frizz worker signed into GitHub (invoke as frizz:gh). Load this whenever your effort touches GitHub — reading or triaging an issue or PR, reviewing a diff, checking CI/release status, or searching issues/PRs — to use `gh` eagerly and correctly: the read-vs-write boundary (never comment/label/close/merge unless the human asks), concrete read recipes, and active Monitor/background-Bash CI/PR watches. Only meaningful when you are signed in (`gh auth status --active` exit 0); the session-seed hook injects a pointer here when you are.
+version: 0.1.2
+metadata:
+  internal: true
+---
+
+# frizz:gh — the gh-CLI playbook
+
+You are a **frizz worker** and you are **signed into the `gh` CLI in a GitHub repo** (the session-seed hook confirmed `gh auth status --active` before pointing you here). `gh` is the fastest path to issue / PR / CI / release context — reach for it before guessing, and prefer it over scraping the web UI or reasoning from memory.
+
+This skill is the full playbook the injected `⟦gh available⟧` block summarizes: the **read-vs-write boundary**, concrete **read recipes**, and how to keep a **CI/PR watch** active until the next actionable event.
+
+## The one hard rule — READ freely, WRITE only when asked
+
+`gh` can mutate the repo, and your token has the scopes to do it. **Do not.** Unless the human **explicitly asks in this session**, you are strictly read-only:
+
+- **NEVER** comment, review, approve, request-changes, label, assign, milestone, edit, close, reopen, merge, or push — no state change of any kind on GitHub.
+- Your deliverable is your **final message** (a findings write-up, a review, a recommendation) — NOT a GitHub post. Producing the review in-session is the job; posting it is a separate action the human authorizes.
+- If posting would genuinely help, don't just do it — **ask** with a two-option `mcp__frizz__ask` question ("Post this review to the PR" / "Keep it in-session only", the recommended one first), then rest. When the destructive edge is real (a force-merge, a close), that's the same question with `danger` set. Never a ` ```question ` fence — that fence is retired (2026-09-11), and a question in a fence body is plain prose.
+- When the human HAS asked you to write, do exactly the scoped thing and report the resulting URL — nothing extra.
+
+There is no server-side enforcement of this; the boundary is yours to hold.
+
+## Read recipes
+
+Always scope with `-R OWNER/REPO` so a command is dir-independent, and prefer `--json <fields>` (+ `-q <jq>`) so you pull exactly what you need.
+
+**Issues**
+```bash
+gh issue view N -R OWNER/REPO --comments                          # full thread, human-readable
+gh issue view N -R OWNER/REPO --json title,body,labels,state,url  # structured
+gh issue list -R OWNER/REPO --search "sort:updated-desc" --json number,title,url,updatedAt --limit 30
+gh issue list -R OWNER/REPO --search "sort:reactions-desc is:open" --json number,title,url --limit 30
+```
+
+**PRs + diffs**
+```bash
+gh pr view N -R OWNER/REPO --json title,body,state,labels,files,additions,deletions,url
+gh pr diff N -R OWNER/REPO                # the unified diff
+gh pr checks N -R OWNER/REPO              # CI check rollup for the PR
+gh pr view N -R OWNER/REPO --comments     # review threads + conversation
+```
+Read the changed files **in context**, not just the hunks — `gh pr diff` shows what changed, but correctness lives in the surrounding code.
+
+**Reading ONE review (what a `watch_pr` wake hands you)**
+
+A wake permalink ending `#pullrequestreview-<id>` is a **review**, and a review's `body` is routinely
+**empty** — review apps (pullfrog, coderabbit) and humans doing an inline pass put every word in the
+review's *inline comments*. Reading the body and concluding the review is empty is the wrong turn here.
+One endpoint answers it in one call:
+
+```bash
+gh api --paginate repos/OWNER/REPO/pulls/N/reviews/REVIEW_ID/comments \
+  --jq '.[] | "\(.path):\(.line // .original_line // "file")\n\(.body)\n"'
+```
+
+Do **not** sweep `…/pulls/N/comments` and filter by `pull_request_review_id` — it pulls the whole PR's
+history to find a handful of lines. Add the review's own body only if you need it
+(`gh api repos/OWNER/REPO/pulls/N/reviews/REVIEW_ID --jq .body`). A `#issuecomment-<id>` permalink is
+the other shape and *does* carry its substance in its body:
+`gh api repos/OWNER/REPO/issues/comments/ID --jq .body`.
+
+**`--paginate` is the default for any list endpoint.** `gh api` returns **30** items per page and caps
+`per_page` at **100**, silently — a truncated page reads exactly like "that's all there is," so a
+missing `--paginate` becomes a wrong answer rather than an error.
+
+**CI / runs / releases**
+```bash
+gh run list -R OWNER/REPO --branch BRANCH --limit 10
+gh run view RUN_ID -R OWNER/REPO --log-failed        # just the failing step logs
+gh release view -R OWNER/REPO                         # latest release
+```
+
+**Search (across issues/PRs)**
+```bash
+gh search issues -R OWNER/REPO "crash on startup" --state open --json number,title,url --limit 30
+gh search prs --repo OWNER/REPO "author:@me" --json number,title,url --limit 30
+```
+Use search to find duplicates, related work, and prior art before you conclude something is novel.
+
+**Raw API** for anything the porcelain doesn't cover:
+```bash
+gh api repos/OWNER/REPO/commits/SHA/check-runs --jq '.check_runs[] | {name, conclusion}'
+gh api "repos/OWNER/REPO/issues?state=open&labels=bug&per_page=50" --jq '.[] | {number, title, html_url}'
+```
+
+## Keep GitHub automation active
+
+CI, automated review, releases, merge queues, and already-authorized merge progression are work you
+can observe with `gh`; they do not earn an `awaiting` fence. Keep a live operation attached to the
+thread and continue when it reports.
+
+### Select monitor tooling explicitly
+
+Before launching any CI/review monitor, inspect project-local `AGENTS.md`, active skills, repository
+docs, `package.json` scripts, and declared monitor tooling. Prefer an explicit project-local monitor
+only if it documents terminal semantics for this gate. Validate its absolute command and terminal
+event/exit contract before launch. If declared tooling is missing, invalid, or has no terminal
+semantics, stop and report that configuration error; never silently shadow it with a Frizz script, and
+never execute a monitor merely because its filename looks plausible.
+
+When no project monitor is declared, the bundled fallback scripts are
+`<this-skill-dir>/scripts/ci-watch.mjs` and `review-watch.mjs`. They are generated byte-for-byte from
+Frizz's canonical `monitors/` source and require only Node plus logged-in `gh`. Their stdout is
+`frizz.github-monitor/v1` NDJSON: `status` means keep waiting; `terminal` is a verdict. They join
+exact-head workflow runs with PR checks, keeping `ACTION_REQUIRED` pending, and baseline every review
+and comment so any new one wakes — bot or human, with no actor
+filter. A GitHub/auth error is terminal exit 3; SIGINT/SIGTERM produces terminal
+`cancelled` and exit 130. A `--once` pending/baseline snapshot is deliberately non-terminal exit 0.
+For CI, retries are collapsed only within the same workflow name and event; distinct exact-head events
+such as `push` and `pull_request` both contribute to the aggregate verdict.
+
+- One-shot completion: launch `Bash` with `run_in_background: true`, for example
+  `gh run watch RUN_ID -R OWNER/REPO --exit-status` or a repo watcher that exits when all PR checks
+  settle. The completion task-notification re-invokes you. Diagnose/fix on red; continue the authorized
+  release/merge path on green.
+- State transitions: use native `Monitor` with a quiet loop that prints only changes or the terminal
+  event. It is the Claude adapter for the selected script; do not make a sub-agent the monitor
+  abstraction.
+  Finite monitors run up to one hour; `persistent: true` runs until `TaskStop` or the Claude session
+  ends. Stop a watch once its gate is obsolete.
+- A background Bash launch exposes an output-file path. Use `Read` on that path only for diagnostics;
+  `TaskOutput` is deprecated. Do not fake waiting with `echo waiting` or sleep-only Bash calls.
+
+Both mechanisms are session-bound. If the next check deliberately belongs at a named wall-clock
+instant, set a durable timer with `mcp__frizz__timer` and park with its id in your fence's `timers:`
+list. If a specific external human reviewer/approver is the only remaining gate, that is a
+registered question (`mcp__frizz__ask`) — waiting on a person is never a park. For a GitHub PR, register it with
+`mcp__frizz__watch_pr` and name it in the fence's `prs:` list (`prs: [OWNER/REPO#NUMBER]`): frizz
+baselines current reviews/comments and wakes on ANY new activity after registration — bot or human —
+durably across restarts. The registration creates the wait; the fence only declares it. The dashboard
+operator's own go/no-go remains a registered question.
+
+## Fitting gh work into your thread type
+
+- **Investigating an issue** (a research thread): reproduce → trace to `file:line` (cite every load-bearing claim) → recommend the smallest correct fix; read the full thread and linked issues/PRs with `gh` for context. Don't implement — stop at the recommendation. Handback = findings in your final message.
+- **Reviewing a PR** (an audit thread): read the diff AND the files in context, verify correctness/edges/tests, check CI (`gh pr checks`), then produce a review (blocking issues vs nits, each citing `file:line`) as your final message. Approve/merge only if explicitly asked.
+
+In both cases: read-only on GitHub unless told otherwise, and the review/findings live in your session, not in a GitHub post.

package/runtime/cc-worker/skills/gh/scripts/ci-watch.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { classifyChecks, gh, latestWorkflowRuns, parseArgs, report, sleep } from "./github-watch.mjs"
+
+const usage = "Usage: ci-watch.mjs --repo OWNER/REPO --pr NUMBER [--interval SECONDS] [--once]"
+
+async function main() {
+  let options
+  try { options = parseArgs(process.argv.slice(2), usage) } catch (error) {
+    process.stderr.write(`ci-watch: ${error instanceof Error ? error.message : String(error)}\n`)
+    report("terminal", { kind: "ci", state: "error", error: error instanceof Error ? error.message : String(error) })
+    process.exitCode = 3
+    return
+  }
+  if (options.help) return console.log(usage)
+  let emittedTerminal = false
+  const terminal = (state, exitCode) => {
+    if (emittedTerminal) return
+    emittedTerminal = true
+    report("terminal", { kind: "ci", repo: options.repo, pr: options.pr, state })
+    process.exitCode = exitCode
+  }
+  const cancelled = () => { terminal("cancelled", 130); process.exit(130) }
+  process.once("SIGINT", cancelled)
+  process.once("SIGTERM", cancelled)
+  let previous
+  for (;;) {
+    try {
+      const pr = JSON.parse(await gh(["pr", "view", String(options.pr), "--repo", options.repo, "--json", "headRefOid"]))
+      const checks = JSON.parse(await gh(["pr", "checks", String(options.pr), "--repo", options.repo, "--json", "name,state,bucket,workflow,link"]))
+      const runs = pr.headRefOid ? JSON.parse(await gh(["run", "list", "--repo", options.repo, "--commit", pr.headRefOid, "--limit", "100", "--json", "name,workflowName,status,conclusion,databaseId,event,createdAt"])) : []
+      const workflows = latestWorkflowRuns(runs).map((run) => ({
+        name: run.name,
+        state: String(run.status).toUpperCase() === "COMPLETED" ? run.conclusion : run.status,
+        workflow: run.event,
+        link: run.databaseId ? `https://github.com/${options.repo}/actions/runs/${run.databaseId}` : undefined,
+      }))
+      const result = classifyChecks([...checks, ...workflows])
+      const signature = JSON.stringify(result)
+      if (signature !== previous) {
+        if (result.state === "pending") report("status", { kind: "ci", repo: options.repo, pr: options.pr, ...result })
+        else { emittedTerminal = true; report("terminal", { kind: "ci", repo: options.repo, pr: options.pr, ...result }) }
+      }
+      previous = signature
+      if (result.state === "passed") process.exitCode = 0
+      if (result.state === "failed") process.exitCode = 2
+      if (result.state !== "pending" || options.once) return
+    } catch (error) {
+      process.stderr.write(`ci-watch: ${error instanceof Error ? error.message : String(error)}\n`)
+      terminal("error", 3)
+      return
+    }
+    await sleep(options.interval * 1000)
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`ci-watch: ${error instanceof Error ? error.message : String(error)}\n`)
+  report("terminal", { kind: "ci", state: "error", error: error instanceof Error ? error.message : String(error) })
+  process.exitCode = 3
+})

package/runtime/cc-worker/skills/gh/scripts/github-watch.mjs

@@ -0,0 +1,130 @@
+import { spawn } from "node:child_process"
+
+export const PROTOCOL = "frizz.github-monitor/v1"
+const SUCCESS = new Set(["SUCCESS", "SKIPPED", "NEUTRAL"])
+const FAILURE = new Set(["FAILURE", "ERROR", "CANCELLED", "TIMED_OUT", "STARTUP_FAILURE"])
+export const GH_TIMEOUT_MS = 30_000
+const GH_ATTEMPTS = 3
+
+export function classifyChecks(checks) {
+  if (!Array.isArray(checks) || checks.length === 0) return { state: "pending", checks: [] }
+  let failed = false
+  let pending = false
+  for (const check of checks) {
+    const state = String(check?.state ?? check?.bucket ?? "").toUpperCase()
+    // A fork-gated workflow is reported as ACTION_REQUIRED after its skipped run completes. It is
+    // not CI success: continue watching for an approved replacement run instead of waking green.
+    if (state.includes("ACTION_REQUIRED") || state === "PENDING" || state === "QUEUED" || state === "IN_PROGRESS" || state === "WAITING") pending = true
+    else if (FAILURE.has(state) || state.includes("FAIL")) failed = true
+    else if (!SUCCESS.has(state) && state !== "PASS") pending = true
+  }
+  return { state: failed ? "failed" : pending ? "pending" : "passed", checks }
+}
+
+// Every review and comment counts, whoever filed it. Most PR review now arrives from an app —
+// Pullfrog, Copilot, CodeRabbit, Greptile — and the reviewers that post their findings as a
+// conversation comment are exactly what an actor-type filter used to throw away.
+export function reviewActivity(raw) {
+  const pr = raw?.data?.repository?.pullRequest
+  const nodes = [...(pr?.reviews?.nodes ?? []), ...(pr?.comments?.nodes ?? [])]
+  return new Set(nodes.map((node) => String(node?.id ?? "")).filter(Boolean))
+}
+
+export function latestWorkflowRuns(runs) {
+  const latest = new Map()
+  for (const run of runs ?? []) {
+    const key = `${run.workflowName ?? run.name ?? "unknown"}\u0000${run.event ?? ""}`
+    const old = latest.get(key)
+    const stamp = String(run.createdAt ?? "")
+    const oldStamp = String(old?.createdAt ?? "")
+    const id = Number(run.databaseId ?? 0)
+    const oldId = Number(old?.databaseId ?? 0)
+    if (!old || stamp > oldStamp || (stamp === oldStamp && id > oldId)) latest.set(key, run)
+  }
+  return [...latest.values()]
+}
+
+function ghOnce(args, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let settled = false
+    const child = spawn("gh", args, {
+      env: { ...process.env, GH_PAGER: "cat", GH_PROMPT_DISABLED: "1" },
+      stdio: ["ignore", "pipe", "pipe"],
+      // A separate process group lets POSIX hosts terminate a hung credential helper too. Windows
+      // uses ChildProcess.kill below; both paths remain Node-only and need no `timeout` utility.
+      detached: process.platform !== "win32",
+    })
+    let stdout = ""
+    let stderr = ""
+    const fail = (error) => {
+      if (settled) return
+      settled = true
+      reject(error)
+    }
+    const kill = (signal) => {
+      if (process.platform !== "win32" && child.pid) {
+        try { process.kill(-child.pid, signal); return } catch { /* child may already be gone */ }
+      }
+      child.kill(signal)
+    }
+    const timeout = setTimeout(() => {
+      kill("SIGTERM")
+      // Some broken credential helpers ignore SIGTERM. Do not let one wedged gh process hold a
+      // monitor forever; a second, portable child-process kill keeps the watch bounded.
+      setTimeout(() => kill("SIGKILL"), 1_000).unref()
+      fail(new Error(`gh timed out after ${timeoutMs / 1000}s`))
+    }, timeoutMs)
+    child.stdout.on("data", (chunk) => { stdout += chunk })
+    child.stderr.on("data", (chunk) => { stderr += chunk })
+    child.once("error", (error) => { clearTimeout(timeout); fail(error) })
+    child.once("close", (status) => {
+      clearTimeout(timeout)
+      if (settled) return
+      settled = true
+      if (status !== 0) reject(new Error(stderr.trim() || `gh exited ${status ?? "without a status"}`))
+      else resolve(stdout)
+    })
+  })
+}
+
+export async function gh(args, { attempts = GH_ATTEMPTS, timeoutMs = GH_TIMEOUT_MS } = {}) {
+  if (!Number.isInteger(attempts) || attempts < 1) throw new Error("gh attempts must be a positive integer")
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 1) throw new Error("gh timeout must be positive")
+  let lastError
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try { return await ghOnce(args, timeoutMs) } catch (error) { lastError = error }
+    // A short bounded backoff covers transient GitHub and credential-helper failures. The final
+    // failure remains a terminal monitor error rather than an unbounded retry loop.
+    if (attempt + 1 < attempts) await sleep(250 * 2 ** attempt)
+  }
+  throw lastError
+}
+
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+export function parseArgs(argv, usage) {
+  const out = { interval: 60, once: false }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === "--help") return { help: true }
+    if (arg === "--once") out.once = true
+    else if (arg === "--repo" || arg === "--pr" || arg === "--interval") out[arg.slice(2)] = argv[++i]
+    else throw new Error(`Unknown argument: ${arg}\n${usage}`)
+  }
+  if (!out.repo || !out.pr) throw new Error(usage)
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(out.repo)) throw new Error("--repo must be OWNER/REPO")
+  if (!/^\d+$/.test(String(out.pr)) || Number(out.pr) < 1) throw new Error("--pr must be a positive number")
+  out.interval = Number(out.interval)
+  if (!Number.isFinite(out.interval) || out.interval < 5) throw new Error("--interval must be at least 5 seconds")
+  return out
+}
+
+// Every stdout line is one schema-versioned NDJSON event. A monitor may emit many status events
+// but exactly one terminal event when it reaches a terminal verdict. Exit codes: passed/new activity
+// 0, CI failure 2, invocation/GitHub error 3. `--once` may end after a non-terminal snapshot with 0.
+export function report(type, value) {
+  if (type !== "status" && type !== "terminal") throw new Error(`invalid monitor event type: ${type}`)
+  process.stdout.write(`${JSON.stringify({ protocol: PROTOCOL, type, at: new Date().toISOString(), ...value })}\n`)
+}

package/runtime/cc-worker/skills/gh/scripts/review-watch.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { gh, parseArgs, report, reviewActivity, sleep } from "./github-watch.mjs"
+
+const usage = "Usage: review-watch.mjs --repo OWNER/REPO --pr NUMBER [--interval SECONDS] [--once]"
+const QUERY = `query($owner:String!,$repo:String!,$number:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$number){reviews(last:50){nodes{id}} comments(last:50){nodes{id}}}}}`
+
+async function main() {
+  let options
+  try { options = parseArgs(process.argv.slice(2), usage) } catch (error) {
+    process.stderr.write(`review-watch: ${error instanceof Error ? error.message : String(error)}\n`)
+    report("terminal", { kind: "review", state: "error", error: error instanceof Error ? error.message : String(error) })
+    process.exitCode = 3
+    return
+  }
+  if (options.help) return console.log(usage)
+  const [owner, repo] = options.repo.split("/")
+  if (!owner || !repo) throw new Error("--repo must be OWNER/REPO")
+  let emittedTerminal = false
+  const terminal = (state, exitCode, extra = {}) => {
+    if (emittedTerminal) return
+    emittedTerminal = true
+    report("terminal", { kind: "review", repo: options.repo, pr: options.pr, state, ...extra })
+    process.exitCode = exitCode
+  }
+  const cancelled = () => { terminal("cancelled", 130); process.exit(130) }
+  process.once("SIGINT", cancelled)
+  process.once("SIGTERM", cancelled)
+  let baseline
+  for (;;) {
+    try {
+      const raw = JSON.parse(await gh(["api", "graphql", "-f", `query=${QUERY}`, "-F", `owner=${owner}`, "-F", `repo=${repo}`, "-F", `number=${options.pr}`]))
+      const current = reviewActivity(raw)
+      if (!baseline) {
+        baseline = current
+        report("status", { kind: "review", repo: options.repo, pr: options.pr, state: "armed", seen: current.size })
+      } else {
+        const added = [...current].filter((id) => !baseline.has(id))
+        if (added.length) { terminal("new-activity", 0, { ids: added }); return }
+      }
+      if (options.once) return
+    } catch (error) {
+      process.stderr.write(`review-watch: ${error instanceof Error ? error.message : String(error)}\n`)
+      terminal("error", 3)
+      return
+    }
+    await sleep(options.interval * 1000)
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`review-watch: ${error instanceof Error ? error.message : String(error)}\n`)
+  report("terminal", { kind: "review", state: "error", error: error instanceof Error ? error.message : String(error) })
+  process.exitCode = 3
+})