Gh Monitor PR

Live-root validation boundary

Validation against a live root is limited to probe-only, read-only protocol calls. Never pipe synthetic events or user prompts into a live root. Run notification and event-delivery simulations only against an isolated fake server or a disposable, projectless test thread unambiguously owned by the test. Never fabricate text claiming that the user instructed a pause, stop, or mutation, and never stop or steer shared roots, workers, or the daemon. If isolated cleanup is unsupported, fail closed and report the limitation.

Monitor a GitHub PR

Start the detached monitor, report the handoff, and end the turn. Never poll, sleep, or use a tool-based wait in the launching Codex turn.

App Server wakeups use the native managed Codex App Server daemon through the portable codex app-server proxy --sock transport. The monitor keeps its own local delivery receipts: it persists a delivering attempt before invoking the native notifier, and a restart never replays an unknown acceptance result.

Set up the App Server

Use the managed local App Server daemon. Never spawn a competing App Server and never set CODEX_APP_SERVER_WS_URL.

For every command below, resolve skill_dir to the absolute directory containing this SKILL.md; do not assume the skill lives in ${CODEX_HOME:-$HOME/.codex}/skills.

Treat Desktop and CLI setup as separate surfaces. If the launching root is a CLI, use only the explicit cli setup below. Never run the no-argument Desktop setup merely to support a CLI monitor: it changes the GUI launchctl environment and installs a persistent Desktop launcher, neither of which is needed for CLI monitoring. Do not install a periodic launcher that invokes codex app-server daemon start for a CLI root. Start the managed daemon on demand during CLI bootstrap instead.

For Codex Desktop, preserve the no-argument setup:

skill_dir='<absolute path to this gh-monitor-pr skill directory>'
node "${skill_dir}/scripts/setup-app-server.mjs"

This configures GUI applications to join the managed daemon. When requested, tell the user to quit ChatGPT completely and reopen it once. End the turn there; register the monitor after restart.

For CLI roots, first probe the existing daemon without changing setup:

skill_dir='<absolute path to this gh-monitor-pr skill directory>'
node "${skill_dir}/scripts/setup-app-server.mjs" \
  probe --surface cli --thread-id "$CODEX_THREAD_ID"

If that returns threadStatus: active, skip CLI setup and start the monitor. Only bootstrap when the probe fails because the daemon, socket, or exact thread is unavailable. Bootstrap also probes the exact root:

skill_dir='<absolute path to this gh-monitor-pr skill directory>'
node "${skill_dir}/scripts/setup-app-server.mjs" \
  cli --thread-id "$CODEX_THREAD_ID"

CLI setup and probe do not modify the Desktop launchctl environment. They fail unless the exact thread is readable through the portable codex app-server proxy --sock transport. Desktop registration also prefers that transport, but may fall back to a direct native Unix-socket App Server connection without ChatGPT-specific Node modules.

The managed daemon is shared infrastructure, not part of one monitor's process tree. A monitor must never stop or restart it. Starting or stopping one monitor must not interrupt another monitor, an App Server worker, or a wakeup turn.

Every connection negotiates experimentalApi, reads the exact thread, and does not resume it during registration. Notification steers an active turn directly; only idle or not-loaded threads are resumed before a new turn starts. State races are re-read and retried.

Start monitoring

1. Require a full GitHub pull-request URL and authenticated gh CLI.

2. Read the exact launching thread from CODEX_THREAD_ID. Never guess a recent thread. In CLI tool shells, CODEX_THREAD_ID may be available for shell expansion even when env does not print it; verify with printf '%s\n' "$CODEX_THREAD_ID" if needed.

3. Convert the delay to whole seconds. Default to 60; require at least 10.

4. Select owner metadata:

   • Desktop defaults to desktop generation 0, preserving old invocations.
   • CLI registration must pass --owner-surface cli and the current ownership lease generation via --owner-generation. For an ordinary ad-hoc CLI monitor in the launching root, use --owner-generation 1; higher generations are for transfers, recoveries, and sweep-owned roots.

5. By default, resolve the active login with gh api user for the PR host and exclude inline comments authored by that exact login from wake events. This avoids waking a worker for its own review-thread replies. The monitor still records every observed comment id. Add --include-self-comments only when the user explicitly wants their own inline comments monitored; comments from bots and every other login remain material either way.

6. Run one of:

   # Backward-compatible Desktop registration
   skill_dir='<absolute path to this gh-monitor-pr skill directory>'
   node "${skill_dir}/scripts/monitor-pr.mjs" \
     start '<pr-url>' --thread-id "$CODEX_THREAD_ID" --cwd "$PWD" --interval <seconds>
   
   # CLI-root registration
   node "${skill_dir}/scripts/monitor-pr.mjs" \
     start '<pr-url>' --thread-id "$CODEX_THREAD_ID" --cwd "$PWD" --interval <seconds> \
     --owner-surface cli --owner-generation <generation>

   Add --stall-after <seconds> (at least 60) to wake once when an open, unqueued PR makes no observable progress for that long. Add the boolean --include-self-comments switch to either command for the explicit opt-in. Do not pass a value and do not introduce an environment variable for this policy.

7. Confirm the returned PR URL, owner surface/generation, comment-monitoring policy, transport, interval, PID, state file, and log file.

8. Send a final response immediately. State that the monitor is detached and the turn is ending. For a CLI-owned monitor, also state that the shared App Server remains running after registration and should be stopped only after the last monitor and App Server worker has finished.

Registration verifies that the exact launching thread is active in the selected managed daemon before taking the inline-comment baseline. A CLI owner fails closed when the portable proxy cannot be verified; it never silently depends on Desktop. A live monitor for the same PR/thread but a different owner surface or generation is an ownership conflict and must not be replaced automatically.

Transfer a monitor

For a deliberate Desktop/CLI owner cutover:

1. Stop the old monitor and require verifiedStopped: true from the result.

2. Independently verify its durable state and exact process identity:

   skill_dir='<absolute path to this gh-monitor-pr skill directory>'
   node "${skill_dir}/scripts/monitor-pr.mjs" \
     verify-stopped --state-file '<old-state-path>'

3. Register the new owner with exactly the prior generation plus one and the stopped state:

   node "${skill_dir}/scripts/monitor-pr.mjs" \
     start '<pr-url>' --thread-id "$CODEX_THREAD_ID" --cwd "$PWD" --interval <seconds> \
     --owner-surface cli --owner-generation <new-generation> \
     --previous-state-file '<old-state-path>'

--previous-state-file requires the captured PID/start-token/command identity to be absent, durable stopped state, the same canonical PR identity, and the exact same root thread. Its prior owner surface and generation must be valid. Replacement accepts only the next consecutive generation (N+1); equal, stale, and skipped generations fail before daemon or GitHub access. Before persisting the replacement baseline, registration compares live PR state against the old monitor's latest snapshot. Inspect registrationDelta: if detected is true, route its changes and new inline comments to the new owner as the first material event before normal work. This preserves events that arrived while no monitor owned the transfer window. The replacement also carries undelivered event envelopes and delivered-event receipts, and claims the transfer receipt idempotently by prior-state digest. A different target for the same claim fails closed. Version-3 states remain readable as Desktop generation 0; replacement from legacy state must still match PR/thread and advance to generation 1. Version-5 and older monitor states retain their historical include-all comment behavior while already running. A replacement or same-owner recovery writes a version-6 state, resolves the current authenticated login, and applies the new default. An earlier explicit self-comment opt-in is inherited across transfer and recovery; passing --include-self-comments can also opt in during either registration path.

Repair one historical same-root generation tag

Do not use normal transfer to correct a stopped monitor that was historically registered one generation above its unchanged owning sweep root. That case is not an ownership transfer. Use the dedicated repair only when the monitor and root have the same exact thread, cwd, and owner surface, the monitor records generation N+1, and the active root authority records generation N:

skill_dir='<absolute path to this gh-monitor-pr skill directory>'
node "${skill_dir}/scripts/monitor-pr.mjs" \
  repair-legacy-binding '<pr-url>' \
  --state-file '<canonical-stopped-monitor-state>' \
  --expected-thread-id "$CODEX_THREAD_ID" --expected-cwd "$PWD" \
  --expected-prior-owner-surface cli --expected-prior-owner-generation <N+1> \
  --target-owner-surface cli --target-owner-generation <N> \
  --root-authority-file '<sweep-root>/authority.json' \
  --root-state-base '<canonical-cl-sweep-state-base>'

--root-state-base is required whenever an indexed migrated root keeps its authority directory outside the canonical project-keyed state base. It may be omitted only when exactly one registry is provably present in the normal one- or two-ancestor layout. Never search broader filesystem locations or infer a state base from another sweep.

The command takes the canonical cl-sweep registry lock and verifies the current UID-owned mode-0700 state base/root, UID-owned mode-0600 registry and root receipts, hash-chained current registry record, active root authority, persistent root lease, canonical monitor path, exact absent process identity, durable stopped state, and settled delivery history before changing ownership metadata. It permits only the same-surface N+1 -> N correction. It retains the byte-exact original monitor state in a mode-0400 audit file, embeds an idempotent repair receipt, and changes no PR, thread, cwd, event, snapshot, or delivery receipt. A reconciled ambiguous delivery retains its receipt and is rebound only to the proven parent generation.

After the repair, register the state with sweep-root-state.mjs register-monitor, then use recover-same-owner with the exact current head. Never run start, transfer to another generation, or delete/recreate the state to bypass a binding mismatch. Any live process, pending/unreconciled event, authority mismatch, noncanonical path, different surface, or generation gap fails closed.

The sole exception to the same-root rule is a prepared project-keyed cl-sweep root adoption. After the old monitor is stopped and independently verified, pass the private transfer receipt:

skill_dir='<absolute path to this gh-monitor-pr skill directory>'
node "${skill_dir}/scripts/monitor-pr.mjs" \
  start '<pr-url>' --thread-id '<new-root-thread>' --cwd '<exact-root-cwd>' \
  --interval <seconds> --owner-surface <desktop-or-cli> \
  --owner-generation <old-generation-plus-one> \
  --previous-state-file '<old-state-path>' \
  --root-transfer-file '<CL_SWEEP_ROOT_TRANSFER-v1-receipt>'

The receipt must be mode 0600 and exactly bind the old/new thread, cwd, surface, and consecutive generation. This transfers monitor ownership; it does not permit overlapping monitors or relax the stopped-state, PR identity, registration-delta, or App Server target verification gates. An incomplete root transfer remains a cl-sweep ownership conflict.