frayui 0.1.0

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

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// @ts-check
+// SessionStart hook (fray-worker) — SEEDS a fray-ui WORKER session's context. Run directly with
+// node (zero deps, max Node compat), mirroring cc's hook idiom.
+//
+// A fray-ui worker is a top-level interactive `claude` the UI spawns per effort; the slug arrives in
+// env FRAY_UI_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 PERSISTS
+// through a scratchpad. This hook injects, on every session start (startup/resume/clear/compact):
+//   1. `core` — a runtime re-grounding + pointer, NOT a second 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 scratchpad PATH + an essential
+//      signal-at-rest anchor + a pointer to the system-prompt contract.
+//   2. the SCRATCHPAD PATH — `.fray/threads/<session_id>/scratch.md`, the worker's compaction-proof memory.
+//   3. on `compact` — a short re-grounding (compaction drops the deep model + the scratchpad reminder).
+//
+// GATE: everything is gated on FRAY_UI_THREAD being set, so the plugin is completely inert when
+// loaded outside a fray-ui 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 `fray on`, so such a cc is already dormant; we write cc's own per-session
+// `off` sentinel anyway via the shared config API (cc/scripts/fray 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/fray/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 fray-ui worker session.
+const thread = (process.env.FRAY_UI_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 scratchpad (`.fray/threads/<session_id>/scratch.md`).
+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
+  ? '.fray/threads/' + sid + '/scratch.md'
+  : '.fray/threads/<session-id>/scratch.md';
+
+// A RUNTIME re-grounding + pointer, NOT a second copy of the contract. The full worker contract
+// (signal fences, scratchpad rules, sub-agent rules, the settings-toggled runtime release gate) lives
+// ONCE in the system prompt fray-ui injects at spawn (workerPrompt.ts / loadWorkerPrompt) — which is
+// re-applied on every resume and survives compaction. This hook adds only what a static system prompt
+// CANNOT carry: the runtime-derived scratchpad PATH, an essential signal-at-rest anchor, and (below)
+// the compaction re-read nudge, gh guidance, and the defensive cc-orchestrator off-sentinel.
+const core =
+  '⟦fray worker contract⟧ You are a fray-ui WORKER driving EXACTLY ONE effort. Your FULL operating contract — the end-of-turn signal fences, scratchpad rules, sub-agent rules, and the runtime release gate — lives in your SYSTEM PROMPT; follow it there (this is a runtime re-grounding, not a second copy). The human + the fray-ui app are the ORCHESTRATOR; you drive ONE effort and never scan the board or touch other efforts. There is no orchestrator mode and no fleet to run: doing the work yourself is the default, and you dispatch a sub-agent only when the work genuinely decomposes into independent prongs.\n' +
+  'SCRATCHPAD: `' + scratch + '` — the CANONICAL record of this thread, your compaction-survival mechanism, and your sub-agents\' shared blackboard. Write your task list, the approach and what you rejected, and anything that must outlive your context there AS YOU GO; re-read it after any compaction or resume, and pass its PATH into every sub-agent prompt.\n' +
+  'SIGNAL AT REST through your FINAL MESSAGE, per the fence rules in your system prompt: bare rest is the ordinary handoff and queues for the human; ```done only when the effort\'s real work is COMPLETE (code LANDED on the mainline — an open PR is NOT done, park it on ```awaiting until it MERGES) and is a DISMISSAL (its card files the thread away where nobody looks again), so if the thread points at future work AT ALL — a pre-fix investigation, a live code-change discussion — bare rest instead, and uncertain is not done; the ONE exception is a planning session whose plan file is fully written and persisted, because that artifact outlives the thread; ```awaiting parks only a human:/timer:/pr-watch: gate, never CI/releases/merge progression (those stay ACTIVE); ```question is the operator ask. Load `fray:handoff` for the full fence reference.\n' +
+  'DECIDE rather than ask: anything derivable from the code, the conventions, or ordinary engineering judgment is YOURS to settle — asking permission to do the work you were dispatched to do is not a question, it is the job. Reserve the operator for the irreversible and the genuinely human-owned.';
+
+const grounding =
+  '⟦fray worker re-grounding (post-compaction)⟧ Context was just compacted. You are still the fray-ui worker for effort `' + thread + '` — re-read your scratchpad `' + 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. Signal at rest through your FINAL MESSAGE: bare rest queues an ordinary handoff; ```done queues a checked completion until Archive and is a DISMISSAL — completed work only, and never when the thread still points at future work (a pre-fix investigation, a live code-change discussion); use a question or bare rest; ```awaiting parks only a human:/timer: gate (or a pr-watch: PR watcher, which wakes on any new review/comment, bot or human); ```question is the explicit higher-priority operator ask. CI/releases/merge progression stay active through Monitor/background Bash.';
+
+// 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' +
+  '• TOON: pipe LARGE, FLAT `gh … --json` output through `toon` when `command -v toon` finds it. Skip it when unavailable, for tiny payloads, or for deeply-nested output — the savings are noise and nesting defeats tabularization.\n' +
+  'Load the `fray: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/fray/agent-bindings.mjs

@@ -0,0 +1,9 @@
+// @ts-check
+/**
+ * THIN SHIM — re-exports cc's `scripts/fray/agent-bindings.mjs` so the worker's PostToolUse
+ * `agent-bind` hook writes `.fray/.agent-bindings.jsonl` records in the EXACT format cc's 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 fray-ui board's per-thread liveness.
+ * Never fork this — the record shape is a cross-plugin contract.
+ */
+export * from '../../../cc/scripts/fray/agent-bindings.mjs';

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

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

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

@@ -0,0 +1,132 @@
+---
+name: gh
+description: The gh-CLI playbook for a fray-ui worker signed into GitHub (invoke as fray: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), optional toon use for large JSON, 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.1
+metadata:
+  internal: true
+---
+
+# fray:gh — the gh-CLI playbook
+
+You are a **fray-ui 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**, optional **toon** use for large JSON, 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 ` ```question ` block ("A. Post this review to the PR / B. Keep it in-session only", Recommendation), then rest. When the destructive edge is real (a force-merge, a close), that's a ` ```question danger ` gate.
+- 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.
+
+## toon — pipe LARGE, FLAT gh JSON through the shim
+
+`toon` (Token-Oriented Object Notation) losslessly re-encodes JSON ~30–40% smaller for LLM context. Use it only when a `gh … --json` result you're reading into YOUR context is **large and flat** (a list page: `gh issue list`, `gh pr list`, `gh search`, `gh api` list endpoints) and `command -v toon` succeeds. It is optional: do not install it or assume a home-directory-specific location.
+
+```bash
+if command -v toon >/dev/null 2>&1; then
+  gh issue list -R OWNER/REPO --json number,title,url,updatedAt --limit 50 | toon
+else
+  gh issue list -R OWNER/REPO --json number,title,url,updatedAt --limit 50
+fi
+```
+
+**Skip toon** for tiny payloads (a handful of fields, one item) and for **deeply-nested** JSON (`reactionGroups`, review threads, nested files) — nesting defeats tabularization, so the savings collapse to noise and you add a parse tax for yourself. A single `gh pr view N --json …` is small — read it raw.
+
+## 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 — pipe through toon only if HUGE and you just need shape
+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.
+
+**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" | { command -v toon >/dev/null 2>&1 && toon || cat; }
+```
+
+## 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 Fray 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
+Fray's canonical `monitors/` source and require only Node plus logged-in `gh`. Their stdout is
+`fray.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, park with a durable `timer:` fence. If a specific external human reviewer/approver is the
+only remaining gate, park with `human: <actor + exact action>`. For a GitHub PR, pair it with
+`pr-watch: OWNER/REPO#NUMBER`: fray-ui baselines current reviews/comments and wakes on ANY new
+activity after the fence — bot or human — durably across restarts. Otherwise optionally pair a timer for
+a scheduled recheck. The dashboard operator's own go/no-go remains a ` ```question ` block. `pr:` / `ci:` /
+`session:` awaiting hints are legacy compatibility only — do not emit them for new automated waits.
+
+## 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 = "fray.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} seconds`))
+    }, 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
+})