@imdeadpool/guardex 5.0.3 → 5.0.5

package/README.md

@@ -107,6 +107,9 @@ gx protect remove release
 gx sync --check
 gx sync
 
+# continuously monitor open PRs targeting current branch and dispatch codex-agent review/merge tasks
+bash scripts/review-bot-watch.sh --interval 30
+
 # cleanup merged agent branches/worktrees
 gx cleanup
 
@@ -115,6 +118,23 @@ gx scan
 gx report scorecard --repo github.com/recodeecom/multiagent-safety
 ```
 
+### Continuous Codex PR monitor (local codex-auth session)
+
+Run this in your local shell to keep watching PRs targeting the current branch (or `--base <branch>`):
+
+```sh
+bash scripts/review-bot-watch.sh --interval 30
+```
+
+Useful flags:
+
+- `--base main` watch a specific base branch
+- `--only-pr 123` process only one PR
+- `--once` run one polling cycle and exit
+- `--retry-failed` retry failed PRs without waiting for a new head SHA
+
+Note: the monitor dispatches Codex through explicit `--task/--agent/--base` flags for compatibility with both older and newer `scripts/codex-agent.sh` argument parsing.
+
 ## Important behavior defaults
 
 - No command defaults to `gx status`.
@@ -123,6 +143,8 @@ gx report scorecard --repo github.com/recodeecom/multiagent-safety
 - `gx setup` checks GitHub CLI (`gh`) and prints install guidance if missing.
 - Interactive self-update prompt defaults to **No** (`[y/N]`).
 - In initialized repos, `setup`/`install`/`fix` block protected-base writes unless explicitly overridden.
+- In VS Code Source Control, manual (non-Codex) commits/pushes to protected branches are allowed by default.
+- Codex/agent sessions stay blocked on protected branches and must use `agent/*` branch + PR workflow.
 - On protected `main`, `gx doctor` auto-runs in a sandbox agent branch/worktree.
 - `scripts/agent-branch-start.sh` hydrates `scripts/codex-agent.sh` into new sandbox worktrees when missing, so auto-finish launcher flow stays available.
 
@@ -185,11 +207,13 @@ codex-auth current
 scripts/agent-branch-start.sh
 scripts/agent-branch-finish.sh
 scripts/codex-agent.sh
+scripts/review-bot-watch.sh
 scripts/agent-worktree-prune.sh
 scripts/agent-file-locks.py
 scripts/install-agent-git-hooks.sh
 scripts/openspec/init-plan-workspace.sh
 .githooks/pre-commit
+.githooks/pre-push
 .codex/skills/guardex/SKILL.md
 .claude/commands/guardex.md
 .omx/state/agent-file-locks.json
@@ -214,6 +238,14 @@ npm pack --dry-run
 
 ## Release notes
 
+### v5.0.5
+
+- Bumped package version from `5.0.4` to `5.0.5` so npm publish can proceed with the next patch release.
+
+### v5.0.4
+
+- Bumped package version from `5.0.3` to `5.0.4` to stay one patch ahead of the current npm published version.
+
 ### v5.0.3
 
 - Bumped package version from `5.0.2` to `5.0.3` for the next npm publish.

package/bin/multiagent-safety.js

@@ -19,6 +19,7 @@ const GH_BIN = process.env.MUSAFETY_GH_BIN || 'gh';
 const REQUIRED_SYSTEM_TOOLS = [
   {
     name: 'gh',
+    displayName: 'GitHub (gh)',
     command: GH_BIN,
     installHint: 'https://cli.github.com/',
   },
@@ -41,11 +42,13 @@ const TEMPLATE_FILES = [
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
   'scripts/codex-agent.sh',
+  'scripts/review-bot-watch.sh',
   'scripts/agent-worktree-prune.sh',
   'scripts/agent-file-locks.py',
   'scripts/install-agent-git-hooks.sh',
   'scripts/openspec/init-plan-workspace.sh',
   'githooks/pre-commit',
+  'githooks/pre-push',
   'codex/skills/guardex/SKILL.md',
   'claude/commands/guardex.md',
 ];
@@ -54,16 +57,19 @@ const EXECUTABLE_RELATIVE_PATHS = new Set([
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
   'scripts/codex-agent.sh',
+  'scripts/review-bot-watch.sh',
   'scripts/agent-worktree-prune.sh',
   'scripts/agent-file-locks.py',
   'scripts/install-agent-git-hooks.sh',
   'scripts/openspec/init-plan-workspace.sh',
   '.githooks/pre-commit',
+  '.githooks/pre-push',
 ]);
 
 const CRITICAL_GUARDRAIL_PATHS = new Set([
   'AGENTS.md',
   '.githooks/pre-commit',
+  '.githooks/pre-push',
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
   'scripts/agent-worktree-prune.sh',
@@ -79,11 +85,13 @@ const MANAGED_GITIGNORE_PATHS = [
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
   'scripts/codex-agent.sh',
+  'scripts/review-bot-watch.sh',
   'scripts/agent-worktree-prune.sh',
   'scripts/agent-file-locks.py',
   'scripts/install-agent-git-hooks.sh',
   'scripts/openspec/init-plan-workspace.sh',
   '.githooks/pre-commit',
+  '.githooks/pre-push',
   'oh-my-codex/',
   '.codex/skills/guardex/SKILL.md',
   '.claude/commands/guardex.md',
@@ -139,6 +147,10 @@ const CLI_COMMAND_DESCRIPTIONS = [
   ['help', 'Show this help output'],
   ['version', 'Print GuardeX version'],
 ];
+const AGENT_BOT_DESCRIPTIONS = [
+  ['review', 'Monitor open PRs targeting current branch and dispatch codex-agent review flow'],
+  ['start', 'bash scripts/review-bot-watch.sh --interval 30'],
+];
 
 const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-Rex for your repo) in this repository for Codex or Claude.
 
@@ -253,9 +265,20 @@ function commandCatalogLines(indent = '  ') {
   );
 }
 
+function agentBotCatalogLines(indent = '  ') {
+  const maxCommandLength = AGENT_BOT_DESCRIPTIONS.reduce(
+    (max, [command]) => Math.max(max, command.length),
+    0,
+  );
+  return AGENT_BOT_DESCRIPTIONS.map(
+    ([command, description]) => `${indent}${command.padEnd(maxCommandLength + 2)}${description}`,
+  );
+}
+
 function printToolLogsSummary() {
   const usageLine = `    $ ${SHORT_TOOL_NAME} <command> [options]`;
   const commandDetails = commandCatalogLines('    ');
+  const agentBotDetails = agentBotCatalogLines('    ');
 
   if (!supportsAnsiColors()) {
     console.log(`${TOOL_NAME}-tools logs:`);
@@ -265,12 +288,17 @@ function printToolLogsSummary() {
     for (const line of commandDetails) {
       console.log(line);
     }
+    console.log('  AGENT BOT');
+    for (const line of agentBotDetails) {
+      console.log(line);
+    }
     return;
   }
 
   const title = colorize(`${TOOL_NAME}-tools logs`, '1;36');
   const usageHeader = colorize('USAGE', '1');
   const commandsHeader = colorize('COMMANDS', '1');
+  const agentBotHeader = colorize('AGENT BOT', '1');
   const pipe = colorize('│', '90');
   const tee = colorize('├', '90');
   const corner = colorize('└', '90');
@@ -286,6 +314,14 @@ function printToolLogsSummary() {
     }
     console.log(`  ${pipe}${line.slice(2)}`);
   }
+  console.log(`  ${tee}─ ${agentBotHeader}`);
+  for (const line of agentBotDetails) {
+    if (!line) {
+      console.log(`  ${pipe}`);
+      continue;
+    }
+    console.log(`  ${pipe}${line.slice(2)}`);
+  }
   console.log(`  ${corner}─ ${colorize(`Try '${TOOL_NAME} doctor' for one-step repair + verification.`, '2')}`);
 }
 
@@ -303,6 +339,9 @@ USAGE
 COMMANDS
 ${commandCatalogLines().join('\n')}
 
+AGENT BOT
+${agentBotCatalogLines().join('\n')}
+
 NOTES
   - Running ${TOOL_NAME} with no command defaults to: ${SHORT_TOOL_NAME} status
   - Short alias: ${SHORT_TOOL_NAME}
@@ -527,6 +566,7 @@ function ensurePackageScripts(repoRoot, dryRun) {
 
   const wantedScripts = {
     'agent:codex': 'bash ./scripts/codex-agent.sh',
+    'agent:review:watch': 'bash ./scripts/review-bot-watch.sh',
     'agent:branch:start': 'bash ./scripts/agent-branch-start.sh',
     'agent:branch:finish': 'bash ./scripts/agent-branch-finish.sh',
     'agent:cleanup': `${SHORT_TOOL_NAME} cleanup`,
@@ -706,6 +746,7 @@ function hasGuardexBootstrapFiles(repoRoot) {
     'AGENTS.md',
     'scripts/agent-branch-start.sh',
     '.githooks/pre-commit',
+    '.githooks/pre-push',
     LOCK_FILE_RELATIVE,
   ];
   return required.every((relativePath) => fs.existsSync(path.join(repoRoot, relativePath)));
@@ -1489,6 +1530,88 @@ function uniquePreserveOrder(items) {
   return result;
 }
 
+function readConfiguredProtectedBranches(repoRoot) {
+  const result = gitRun(repoRoot, ['config', '--get', GIT_PROTECTED_BRANCHES_KEY], { allowFailure: true });
+  if (result.status !== 0) {
+    return null;
+  }
+  const parsed = uniquePreserveOrder(parseBranchList(result.stdout.trim()));
+  if (parsed.length === 0) {
+    return null;
+  }
+  return parsed;
+}
+
+function listLocalUserBranches(repoRoot) {
+  const result = gitRun(repoRoot, ['for-each-ref', '--format=%(refname:short)', 'refs/heads'], { allowFailure: true });
+  const branchNames = result.status === 0
+    ? uniquePreserveOrder(
+      String(result.stdout || '')
+        .split('\n')
+        .map((item) => item.trim())
+        .filter(Boolean),
+    )
+    : [];
+
+  const additionalUserBranches = branchNames.filter(
+    (branchName) =>
+      !branchName.startsWith('agent/') &&
+      !DEFAULT_PROTECTED_BRANCHES.includes(branchName),
+  );
+  if (additionalUserBranches.length > 0) {
+    return additionalUserBranches;
+  }
+
+  const current = gitRun(repoRoot, ['branch', '--show-current'], { allowFailure: true });
+  if (current.status !== 0) {
+    return [];
+  }
+
+  const branchName = String(current.stdout || '').trim();
+  if (
+    !branchName ||
+    branchName.startsWith('agent/') ||
+    DEFAULT_PROTECTED_BRANCHES.includes(branchName)
+  ) {
+    return [];
+  }
+
+  return [branchName];
+}
+
+function ensureSetupProtectedBranches(repoRoot, dryRun) {
+  const localUserBranches = listLocalUserBranches(repoRoot);
+  if (localUserBranches.length === 0) {
+    return {
+      status: 'unchanged',
+      file: `git config ${GIT_PROTECTED_BRANCHES_KEY}`,
+      note: 'no additional local user branches detected',
+    };
+  }
+
+  const configured = readConfiguredProtectedBranches(repoRoot);
+  const currentBranches = configured || [...DEFAULT_PROTECTED_BRANCHES];
+  const missingBranches = localUserBranches.filter((branchName) => !currentBranches.includes(branchName));
+  if (missingBranches.length === 0) {
+    return {
+      status: 'unchanged',
+      file: `git config ${GIT_PROTECTED_BRANCHES_KEY}`,
+      note: 'local user branches already protected',
+    };
+  }
+
+  const nextBranches = uniquePreserveOrder([...currentBranches, ...missingBranches]);
+  if (!dryRun) {
+    writeProtectedBranches(repoRoot, nextBranches);
+  }
+
+  return {
+    status: dryRun ? 'would-update' : 'updated',
+    file: `git config ${GIT_PROTECTED_BRANCHES_KEY}`,
+    note: `added local user branch(es): ${missingBranches.join(', ')}`,
+  };
+}
+
 function readProtectedBranches(repoRoot) {
   const result = gitRun(repoRoot, ['config', '--get', GIT_PROTECTED_BRANCHES_KEY], { allowFailure: true });
   if (result.status !== 0) {
@@ -2052,6 +2175,7 @@ function detectRequiredSystemTools() {
     const reason = rawReason.split('\n')[0] || '';
     services.push({
       name: tool.name,
+      displayName: tool.displayName || tool.name,
       command: tool.command,
       installHint: tool.installHint,
       status: active ? 'active' : 'inactive',
@@ -2404,6 +2528,7 @@ function status(rawArgs) {
     ...npmServices,
     ...requiredSystemTools.map((tool) => ({
       name: tool.name,
+      displayName: tool.displayName || tool.name,
       status: tool.status,
     })),
   ];
@@ -2452,11 +2577,14 @@ function status(rawArgs) {
 
   console.log(`[${TOOL_NAME}] Global services:`);
   for (const service of services) {
-    console.log(`  - ${statusDot(service.status)} ${service.name}: ${service.status}`);
+    const serviceLabel = service.displayName || service.name;
+    console.log(`  - ${statusDot(service.status)} ${serviceLabel}: ${service.status}`);
   }
   const missingSystemTools = requiredSystemTools.filter((tool) => tool.status !== 'active');
   if (missingSystemTools.length > 0) {
-    const tools = missingSystemTools.map((tool) => tool.name).join(', ');
+    const tools = missingSystemTools
+      .map((tool) => tool.displayName || tool.name)
+      .join(', ');
     console.log(`[${TOOL_NAME}] ⚠️ Missing required system tool(s): ${tools}`);
     for (const tool of missingSystemTools) {
       const reasonText = tool.reason ? ` (${tool.reason})` : '';
@@ -2474,6 +2602,16 @@ function status(rawArgs) {
 
   if (scanResult.errors === 0 && scanResult.warnings === 0) {
     console.log(`[${TOOL_NAME}] Repo safety service: ${statusDot('active')} active.`);
+  } else if (scanResult.errors === 0) {
+    console.log(
+      `[${TOOL_NAME}] Repo safety service: ${statusDot('degraded')} degraded (${scanResult.warnings} warning(s)).`,
+    );
+    console.log(`[${TOOL_NAME}] Run '${TOOL_NAME} scan' to review warning details.`);
+  } else if (scanResult.warnings === 0) {
+    console.log(
+      `[${TOOL_NAME}] Repo safety service: ${statusDot('degraded')} degraded (${scanResult.errors} error(s)).`,
+    );
+    console.log(`[${TOOL_NAME}] Run '${TOOL_NAME} scan' for detailed findings.`);
   } else {
     console.log(
       `[${TOOL_NAME}] Repo safety service: ${statusDot('degraded')} degraded (${scanResult.errors} error(s), ${scanResult.warnings} warning(s)).`,
@@ -2743,6 +2881,7 @@ function setup(rawArgs) {
 
   assertProtectedMainWriteAllowed(options, 'setup');
   const installPayload = runInstallInternal(options);
+  installPayload.operations.push(ensureSetupProtectedBranches(installPayload.repoRoot, Boolean(options.dryRun)));
   printOperations('Setup/install', installPayload, options.dryRun);
 
   const fixPayload = runFixInternal({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "5.0.3",
+  "version": "5.0.5",
   "description": "GuardeX: the Guardian T-Rex for your repo, with hardened multi-agent git guardrails.",
   "license": "MIT",
   "preferGlobal": true,

package/templates/githooks/pre-commit

@@ -23,6 +23,11 @@ if [[ -n "${CODEX_THREAD_ID:-}" || -n "${OMX_SESSION_ID:-}" || "${CODEX_CI:-0}"
   is_codex_session=1
 fi
 
+is_vscode_git_context=0
+if [[ -n "${VSCODE_GIT_IPC_HANDLE:-}" || -n "${VSCODE_GIT_ASKPASS_NODE:-}" || -n "${VSCODE_IPC_HOOK_CLI:-}" || "${TERM_PROGRAM:-}" == "vscode" ]]; then
+  is_vscode_git_context=1
+fi
+
 protected_branches_raw="${MUSAFETY_PROTECTED_BRANCHES:-$(git config --get multiagent.protectedBranches || true)}"
 if [[ -z "$protected_branches_raw" ]]; then
   protected_branches_raw="dev main master"
@@ -106,6 +111,10 @@ MSG
 fi
 
 if [[ "$is_protected_branch" == "1" ]]; then
+  if [[ "$is_codex_session" != "1" && "$is_vscode_git_context" == "1" ]]; then
+    exit 0
+  fi
+
   if [[ "$is_unborn_branch" == "1" && "$is_codex_session" != "1" ]]; then
     exit 0
   fi

package/templates/githooks/pre-push

@@ -10,8 +10,9 @@ if [[ -n "${VSCODE_GIT_IPC_HANDLE:-}" || -n "${VSCODE_GIT_ASKPASS_NODE:-}" || -n
   is_vscode_git_context=1
 fi
 
-if [[ "$is_vscode_git_context" == "1" ]]; then
-  exit 0
+is_codex_session=0
+if [[ -n "${CODEX_THREAD_ID:-}" || -n "${OMX_SESSION_ID:-}" || "${CODEX_CI:-0}" == "1" ]]; then
+  is_codex_session=1
 fi
 
 protected_branches_raw="${MUSAFETY_PROTECTED_BRANCHES:-$(git config --get multiagent.protectedBranches || true)}"
@@ -43,6 +44,22 @@ while IFS=' ' read -r local_ref local_sha remote_ref remote_sha; do
 done
 
 if [[ "${#blocked_refs[@]}" -gt 0 ]]; then
+  if [[ "$is_codex_session" == "1" ]]; then
+    {
+      echo "[guardex-preedit-guard] Codex push detected toward protected branch."
+      echo "[guardex-preedit-guard] Protected target(s): ${blocked_refs[*]}"
+      echo "[guardex-preedit-guard] Run Codex from an agent/* branch and merge via PR."
+      echo
+      echo "Temporary bypass (not recommended):"
+      echo "  ALLOW_PUSH_ON_PROTECTED_BRANCH=1 git push ..."
+    } >&2
+    exit 1
+  fi
+
+  if [[ "$is_vscode_git_context" == "1" ]]; then
+    exit 0
+  fi
+
   {
     echo "[agent-branch-guard] Push to protected branch blocked outside VS Code Git context."
     echo "[agent-branch-guard] Protected target(s): ${blocked_refs[*]}"

package/templates/scripts/agent-file-locks.py

@@ -26,6 +26,7 @@ LOCK_FILE_RELATIVE = Path('.omx/state/agent-file-locks.json')
 CRITICAL_GUARDRAIL_PATHS = {
     'AGENTS.md',
     '.githooks/pre-commit',
+    '.githooks/pre-push',
     'scripts/agent-branch-start.sh',
     'scripts/agent-branch-finish.sh',
     'scripts/agent-file-locks.py',

package/templates/scripts/review-bot-watch.sh

@@ -0,0 +1,330 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+INTERVAL_SECONDS="${MUSAFETY_REVIEW_BOT_INTERVAL_SECONDS:-30}"
+AGENT_NAME="${MUSAFETY_REVIEW_BOT_AGENT_NAME:-guardex-review-bot}"
+TASK_PREFIX="${MUSAFETY_REVIEW_BOT_TASK_PREFIX:-review-merge}"
+STATE_FILE="${MUSAFETY_REVIEW_BOT_STATE_FILE:-}"
+BASE_BRANCH="${MUSAFETY_REVIEW_BOT_BASE_BRANCH:-}"
+ONLY_PR="${MUSAFETY_REVIEW_BOT_ONLY_PR:-}"
+RETRY_FAILED_RAW="${MUSAFETY_REVIEW_BOT_RETRY_FAILED:-false}"
+INCLUDE_DRAFT_RAW="${MUSAFETY_REVIEW_BOT_INCLUDE_DRAFT:-false}"
+
+usage() {
+  cat <<'USAGE'
+Usage: bash scripts/review-bot-watch.sh [options]
+
+Continuously monitor GitHub pull requests targeting a base branch and dispatch
+one Codex-agent task per newly opened/updated PR.
+
+Options:
+  --base <branch>            Base branch to watch (default: current branch)
+  --interval <seconds>       Poll interval (default: 30)
+  --agent <name>             Agent name for codex-agent (default: guardex-review-bot)
+  --task-prefix <prefix>     Task prefix for codex-agent branches (default: review-merge)
+  --state-file <path>        State file path (default: .omx/state/review-bot-watch-<base>.tsv)
+  --only-pr <number>         Watch only one PR number
+  --include-draft            Include draft PRs
+  --retry-failed             Retry PRs that previously failed even when SHA is unchanged
+  --once                     Run one poll cycle and exit
+  -h, --help                 Show this help
+
+Environment overrides:
+  MUSAFETY_REVIEW_BOT_PROMPT_APPEND  Additional instructions appended to each Codex prompt
+USAGE
+}
+
+normalize_bool() {
+  local raw="${1:-}"
+  local fallback="${2:-0}"
+  case "$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')" in
+    1|true|yes|on) printf '1' ;;
+    0|false|no|off) printf '0' ;;
+    '') printf '%s' "$fallback" ;;
+    *) printf '%s' "$fallback" ;;
+  esac
+}
+
+ONCE=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --base)
+      BASE_BRANCH="${2:-}"
+      shift 2
+      ;;
+    --interval)
+      INTERVAL_SECONDS="${2:-}"
+      shift 2
+      ;;
+    --agent)
+      AGENT_NAME="${2:-}"
+      shift 2
+      ;;
+    --task-prefix)
+      TASK_PREFIX="${2:-}"
+      shift 2
+      ;;
+    --state-file)
+      STATE_FILE="${2:-}"
+      shift 2
+      ;;
+    --only-pr)
+      ONLY_PR="${2:-}"
+      shift 2
+      ;;
+    --retry-failed)
+      RETRY_FAILED_RAW="true"
+      shift
+      ;;
+    --include-draft)
+      INCLUDE_DRAFT_RAW="true"
+      shift
+      ;;
+    --once)
+      ONCE=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "[review-bot-watch] Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+RETRY_FAILED="$(normalize_bool "$RETRY_FAILED_RAW" "0")"
+INCLUDE_DRAFT="$(normalize_bool "$INCLUDE_DRAFT_RAW" "0")"
+
+if [[ ! "$INTERVAL_SECONDS" =~ ^[0-9]+$ ]] || [[ "$INTERVAL_SECONDS" -lt 5 ]]; then
+  echo "[review-bot-watch] --interval must be an integer >= 5 seconds." >&2
+  exit 1
+fi
+
+if [[ -n "$ONLY_PR" ]] && [[ ! "$ONLY_PR" =~ ^[0-9]+$ ]]; then
+  echo "[review-bot-watch] --only-pr must be a numeric PR id." >&2
+  exit 1
+fi
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "[review-bot-watch] Not inside a git repository." >&2
+  exit 1
+fi
+repo_root="$(git rev-parse --show-toplevel)"
+
+if [[ -z "$BASE_BRANCH" ]]; then
+  BASE_BRANCH="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+fi
+if [[ -z "$BASE_BRANCH" || "$BASE_BRANCH" == "HEAD" ]]; then
+  BASE_BRANCH="main"
+fi
+
+if ! command -v gh >/dev/null 2>&1; then
+  echo "[review-bot-watch] Missing GitHub CLI (gh)." >&2
+  echo "[review-bot-watch] Install gh and run: gh auth login" >&2
+  exit 127
+fi
+
+if ! command -v codex >/dev/null 2>&1; then
+  echo "[review-bot-watch] Missing Codex CLI command: codex" >&2
+  exit 127
+fi
+
+if [[ ! -x "$repo_root/scripts/codex-agent.sh" ]]; then
+  echo "[review-bot-watch] Missing scripts/codex-agent.sh. Run: gx setup" >&2
+  exit 1
+fi
+
+if ! gh auth status >/dev/null 2>&1; then
+  echo "[review-bot-watch] gh is not authenticated. Run: gh auth login" >&2
+  exit 1
+fi
+
+sanitize_slug() {
+  local raw="$1"
+  local fallback="$2"
+  local slug
+  slug="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
+  if [[ -z "$slug" ]]; then
+    slug="$fallback"
+  fi
+  printf '%s' "$slug"
+}
+
+base_slug="$(sanitize_slug "$BASE_BRANCH" "base")"
+if [[ -z "$STATE_FILE" ]]; then
+  STATE_FILE="$repo_root/.omx/state/review-bot-watch-${base_slug}.tsv"
+fi
+mkdir -p "$(dirname "$STATE_FILE")"
+
+declare -A LAST_SHA
+
+declare -A LAST_STATUS
+
+load_state() {
+  if [[ ! -f "$STATE_FILE" ]]; then
+    return 0
+  fi
+  while IFS=$'\t' read -r pr sha status updated_at; do
+    if [[ -z "${pr:-}" ]] || [[ "${pr:0:1}" == "#" ]]; then
+      continue
+    fi
+    LAST_SHA["$pr"]="$sha"
+    LAST_STATUS["$pr"]="$status"
+  done < "$STATE_FILE"
+}
+
+save_state() {
+  {
+    echo "# pr\thead_sha\tstatus\tupdated_at"
+    for pr in "${!LAST_SHA[@]}"; do
+      printf '%s\t%s\t%s\t%s\n' "${pr}" "${LAST_SHA[$pr]}" "${LAST_STATUS[$pr]:-unknown}" "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    done | sort -n
+  } > "$STATE_FILE"
+}
+
+build_prompt() {
+  local pr="$1"
+  local head_branch="$2"
+  local head_sha="$3"
+  local pr_title="$4"
+  local pr_url="$5"
+
+  cat <<PROMPT
+You are the continuous PR review+merge Codex agent.
+
+Target PR: #${pr}
+URL: ${pr_url}
+Title: ${pr_title}
+Base branch: ${BASE_BRANCH}
+Head branch: ${head_branch}
+Head SHA: ${head_sha}
+
+Strict task:
+1) Review ONLY this PR's changes using gh CLI context (gh pr view ${pr}, gh pr diff ${pr}).
+2) If fixes are needed, implement them in your sandbox branch, run verification (at minimum npm test when available), and push your sandbox branch.
+3) When the PR is ready and checks are green, merge this PR into ${BASE_BRANCH} with:
+   gh pr merge ${pr} --squash --delete-branch
+4) If merge is blocked, explain the blocker and exit non-zero.
+5) Do not touch unrelated PRs.
+PROMPT
+
+  if [[ -n "${MUSAFETY_REVIEW_BOT_PROMPT_APPEND:-}" ]]; then
+    printf '\n%s\n' "${MUSAFETY_REVIEW_BOT_PROMPT_APPEND}"
+  fi
+}
+
+list_open_prs() {
+  gh pr list \
+    --state open \
+    --base "$BASE_BRANCH" \
+    --json number,headRefName,headRefOid,isDraft,title,url \
+    --jq '.[] | "\(.number)\t\(.headRefName)\t\(.headRefOid)\t\(.isDraft)\t\(.title | gsub("\\t"; " "))\t\(.url)"'
+}
+
+should_process_pr() {
+  local pr="$1"
+  local sha="$2"
+
+  local prev_sha="${LAST_SHA[$pr]:-}"
+  local prev_status="${LAST_STATUS[$pr]:-}"
+
+  if [[ -z "$prev_sha" ]]; then
+    return 0
+  fi
+
+  if [[ "$prev_sha" != "$sha" ]]; then
+    return 0
+  fi
+
+  if [[ "$prev_status" == "failed" && "$RETRY_FAILED" == "1" ]]; then
+    return 0
+  fi
+
+  return 1
+}
+
+process_one_pr() {
+  local pr="$1"
+  local head_branch="$2"
+  local sha="$3"
+  local title="$4"
+  local url="$5"
+
+  local prompt
+  prompt="$(build_prompt "$pr" "$head_branch" "$sha" "$title" "$url")"
+
+  local task_name="${TASK_PREFIX}-pr-${pr}"
+
+  echo "[review-bot-watch] Dispatching Codex agent for PR #${pr} (${head_branch})"
+  set +e
+  bash "$repo_root/scripts/codex-agent.sh" \
+    --task "$task_name" \
+    --agent "$AGENT_NAME" \
+    --base "$BASE_BRANCH" \
+    -- exec "$prompt"
+  local exit_code="$?"
+  set -e
+
+  LAST_SHA["$pr"]="$sha"
+  if [[ "$exit_code" -eq 0 ]]; then
+    LAST_STATUS["$pr"]="success"
+    echo "[review-bot-watch] PR #${pr}: success"
+  else
+    LAST_STATUS["$pr"]="failed"
+    echo "[review-bot-watch] PR #${pr}: failed (exit=${exit_code})" >&2
+  fi
+
+  save_state
+}
+
+load_state
+
+echo "[review-bot-watch] Starting monitor"
+echo "[review-bot-watch] Base branch : ${BASE_BRANCH}"
+echo "[review-bot-watch] Interval    : ${INTERVAL_SECONDS}s"
+echo "[review-bot-watch] State file  : ${STATE_FILE}"
+if [[ -n "$ONLY_PR" ]]; then
+  echo "[review-bot-watch] Only PR      : #${ONLY_PR}"
+fi
+
+trap 'echo "[review-bot-watch] Stopped."; exit 0' INT TERM
+
+while true; do
+  found=0
+  while IFS=$'\t' read -r pr head_branch sha is_draft title url; do
+    if [[ -z "${pr:-}" ]]; then
+      continue
+    fi
+
+    found=1
+
+    if [[ -n "$ONLY_PR" && "$pr" != "$ONLY_PR" ]]; then
+      continue
+    fi
+
+    if [[ "$INCLUDE_DRAFT" != "1" && "$is_draft" == "true" ]]; then
+      continue
+    fi
+
+    if ! should_process_pr "$pr" "$sha"; then
+      continue
+    fi
+
+    process_one_pr "$pr" "$head_branch" "$sha" "$title" "$url"
+  done < <(list_open_prs || true)
+
+  if [[ "$found" -eq 0 ]]; then
+    echo "[review-bot-watch] No open PRs for base '${BASE_BRANCH}'."
+  fi
+
+  if [[ "$ONCE" -eq 1 ]]; then
+    break
+  fi
+
+  sleep "$INTERVAL_SECONDS"
+done