@imdeadpool/guardex 5.0.5 → 5.0.8

package/bin/multiagent-safety.js

@@ -79,9 +79,11 @@ const CRITICAL_GUARDRAIL_PATHS = new Set([
 
 const LOCK_FILE_RELATIVE = '.omx/state/agent-file-locks.json';
 const AGENTS_MARKER_START = '<!-- multiagent-safety:START -->';
+const AGENTS_MARKER_END = '<!-- multiagent-safety:END -->';
 const GITIGNORE_MARKER_START = '# multiagent-safety:START';
 const GITIGNORE_MARKER_END = '# multiagent-safety:END';
 const MANAGED_GITIGNORE_PATHS = [
+  '.omx/',
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
   'scripts/codex-agent.sh',
@@ -97,6 +99,17 @@ const MANAGED_GITIGNORE_PATHS = [
   '.claude/commands/guardex.md',
   LOCK_FILE_RELATIVE,
 ];
+const OMX_SCAFFOLD_DIRECTORIES = [
+  '.omx',
+  '.omx/state',
+  '.omx/logs',
+  '.omx/plans',
+  '.omx/agent-worktrees',
+];
+const OMX_SCAFFOLD_FILES = new Map([
+  ['.omx/notepad.md', '\n\n## WORKING MEMORY\n'],
+  ['.omx/project-memory.json', '{}\n'],
+]);
 const COMMAND_TYPO_ALIASES = new Map([
   ['relaese', 'release'],
   ['realaese', 'release'],
@@ -114,6 +127,7 @@ const SUGGESTIBLE_COMMANDS = [
   'setup',
   'init',
   'doctor',
+  'review',
   'report',
   'copy-prompt',
   'copy-commands',
@@ -148,8 +162,7 @@ const CLI_COMMAND_DESCRIPTIONS = [
   ['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'],
+  ['review', 'Start PR monitor + codex-agent review flow (default interval: 30s)'],
 ];
 
 const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-Rex for your repo) in this repository for Codex or Claude.
@@ -171,7 +184,10 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
 3) If setup reports warnings/errors, repair + re-check:
    gx doctor
 
-4) Confirm next safe agent workflow commands:
+4) Optional: start continuous PR monitor from this repo:
+   gx review --interval 30
+
+5) Confirm next safe agent workflow commands:
    bash scripts/codex-agent.sh "task" "agent-name"
    bash scripts/agent-branch-start.sh "task" "agent-name"
    python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
@@ -183,17 +199,17 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
      Remove them explicitly when done:
      gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
 
-5) Optional: create OpenSpec planning workspace:
+6) Optional: create OpenSpec planning workspace:
    bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
 
-6) Optional: protect extra branches:
+7) Optional: protect extra branches:
    gx protect add release staging
 
-7) Optional: sync your current agent branch with latest base branch:
+8) Optional: sync your current agent branch with latest base branch:
    gx sync --check
    gx sync
 
-8) Optional (GitHub remote cleanup): enable:
+9) Optional (GitHub remote cleanup): enable:
    Settings -> General -> Pull Requests -> Automatically delete head branches
 `;
 
@@ -201,6 +217,7 @@ const AI_SETUP_COMMANDS = `npm i -g @imdeadpool/guardex
 gh --version
 gx setup
 gx doctor
+gx review --interval 30
 bash scripts/codex-agent.sh "task" "agent-name"
 bash scripts/agent-branch-start.sh "task" "agent-name"
 python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
@@ -348,7 +365,9 @@ NOTES
   - ${SHORT_TOOL_NAME} init is an alias of ${SHORT_TOOL_NAME} setup
   - ${TOOL_NAME} setup asks for Y/N approval before global installs
   - ${TOOL_NAME} setup checks GitHub CLI (gh) and prints install guidance if missing
+  - For other repos: ${SHORT_TOOL_NAME} setup --target <repo-path> then ${SHORT_TOOL_NAME} doctor --target <repo-path>
   - In initialized repos, setup/install/fix block in-place writes on protected main by default
+  - setup/doctor auto-finish clean pending agent/* branches via PR flow into the current local base branch
   - doctor auto-runs in a sandbox agent branch/worktree on protected main and tries auto-finish PR flow
   - agent-branch-finish merges by default and keeps agent branches/worktrees until explicit cleanup
   - use '${SHORT_TOOL_NAME} cleanup' to remove merged agent branches/worktrees (optionally remote refs too)
@@ -358,7 +377,8 @@ NOTES
     console.log(`
 [${TOOL_NAME}] No git repository detected in current directory.
 [${TOOL_NAME}] Start from a repo root, or pass an explicit target:
-  ${TOOL_NAME} setup --target <path-to-git-repo>`);
+  ${TOOL_NAME} setup --target <path-to-git-repo>
+  ${TOOL_NAME} doctor --target <path-to-git-repo>`);
   }
 }
 
@@ -501,6 +521,45 @@ function lockFilePath(repoRoot) {
   return path.join(repoRoot, LOCK_FILE_RELATIVE);
 }
 
+function ensureOmxScaffold(repoRoot, dryRun) {
+  const operations = [];
+
+  for (const relativeDir of OMX_SCAFFOLD_DIRECTORIES) {
+    const absoluteDir = path.join(repoRoot, relativeDir);
+    if (fs.existsSync(absoluteDir)) {
+      if (!fs.statSync(absoluteDir).isDirectory()) {
+        throw new Error(`Expected directory at ${relativeDir} but found a file.`);
+      }
+      operations.push({ status: 'unchanged', file: relativeDir });
+      continue;
+    }
+
+    if (!dryRun) {
+      fs.mkdirSync(absoluteDir, { recursive: true });
+    }
+    operations.push({ status: 'created', file: relativeDir });
+  }
+
+  for (const [relativeFile, defaultContent] of OMX_SCAFFOLD_FILES.entries()) {
+    const absoluteFile = path.join(repoRoot, relativeFile);
+    if (fs.existsSync(absoluteFile)) {
+      if (!fs.statSync(absoluteFile).isFile()) {
+        throw new Error(`Expected file at ${relativeFile} but found a directory.`);
+      }
+      operations.push({ status: 'unchanged', file: relativeFile });
+      continue;
+    }
+
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(absoluteFile), { recursive: true });
+      fs.writeFileSync(absoluteFile, defaultContent, 'utf8');
+    }
+    operations.push({ status: 'created', file: relativeFile });
+  }
+
+  return operations;
+}
+
 function ensureLockRegistry(repoRoot, dryRun) {
   const absolutePath = lockFilePath(repoRoot);
   if (fs.existsSync(absolutePath)) {
@@ -608,6 +667,10 @@ function ensurePackageScripts(repoRoot, dryRun) {
 function ensureAgentsSnippet(repoRoot, dryRun) {
   const agentsPath = path.join(repoRoot, 'AGENTS.md');
   const snippet = fs.readFileSync(path.join(TEMPLATE_ROOT, 'AGENTS.multiagent-safety.md'), 'utf8').trimEnd();
+  const managedRegex = new RegExp(
+    `${AGENTS_MARKER_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${AGENTS_MARKER_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
+    'm',
+  );
 
   if (!fs.existsSync(agentsPath)) {
     if (!dryRun) {
@@ -617,8 +680,19 @@ function ensureAgentsSnippet(repoRoot, dryRun) {
   }
 
   const existing = fs.readFileSync(agentsPath, 'utf8');
+  if (managedRegex.test(existing)) {
+    const next = existing.replace(managedRegex, snippet);
+    if (next === existing) {
+      return { status: 'unchanged', file: 'AGENTS.md' };
+    }
+    if (!dryRun) {
+      fs.writeFileSync(agentsPath, next, 'utf8');
+    }
+    return { status: 'updated', file: 'AGENTS.md', note: 'refreshed guardex-managed block' };
+  }
+
   if (existing.includes(AGENTS_MARKER_START)) {
-    return { status: 'unchanged', file: 'AGENTS.md' };
+    return { status: 'unchanged', file: 'AGENTS.md', note: 'existing marker found without managed end marker' };
   }
 
   const separator = existing.endsWith('\n') ? '\n' : '\n\n';
@@ -828,6 +902,33 @@ function isSpawnFailure(result) {
   return Boolean(result?.error) && typeof result?.status !== 'number';
 }
 
+function ensureRepoBranch(repoRoot, branch) {
+  const current = currentBranchName(repoRoot);
+  if (current === branch) {
+    return { ok: true, changed: false };
+  }
+
+  const checkoutResult = run('git', ['-C', repoRoot, 'checkout', branch], { timeout: 20_000 });
+  if (isSpawnFailure(checkoutResult)) {
+    return {
+      ok: false,
+      changed: false,
+      stdout: checkoutResult.stdout || '',
+      stderr: checkoutResult.stderr || '',
+    };
+  }
+  if (checkoutResult.status !== 0) {
+    return {
+      ok: false,
+      changed: false,
+      stdout: checkoutResult.stdout || '',
+      stderr: checkoutResult.stderr || '',
+    };
+  }
+
+  return { ok: true, changed: true };
+}
+
 function doctorSandboxBranchPrefix() {
   const now = new Date();
   const stamp = [
@@ -929,12 +1030,26 @@ function startDoctorSandbox(blocked) {
     throw startResult.error;
   }
   if (startResult.status !== 0) {
-    throw new Error((startResult.stderr || startResult.stdout || 'failed to start doctor sandbox').trim());
+    return startDoctorSandboxFallback(blocked);
   }
 
   const metadata = extractAgentBranchStartMetadata(startResult.stdout);
-  if (!metadata.worktreePath) {
-    throw new Error(`Failed to parse sandbox worktree from agent-branch-start output:\n${startResult.stdout}`);
+  const currentBranch = currentBranchName(blocked.repoRoot);
+  const worktreePath = metadata.worktreePath ? path.resolve(metadata.worktreePath) : '';
+  const repoRootPath = path.resolve(blocked.repoRoot);
+  const hasSafeWorktree = Boolean(worktreePath) && worktreePath !== repoRootPath;
+  const branchChanged = Boolean(currentBranch) && currentBranch !== blocked.branch;
+
+  if (!hasSafeWorktree || branchChanged) {
+    const restoreResult = ensureRepoBranch(blocked.repoRoot, blocked.branch);
+    if (!restoreResult.ok) {
+      const detail = [restoreResult.stderr, restoreResult.stdout].filter(Boolean).join('\n').trim();
+      throw new Error(
+        `doctor sandbox startup switched protected base checkout and could not restore '${blocked.branch}'.` +
+        (detail ? `\n${detail}` : ''),
+      );
+    }
+    return startDoctorSandboxFallback(blocked);
   }
 
   return {
@@ -1069,6 +1184,19 @@ function isCommandAvailable(commandName) {
   return run('which', [commandName]).status === 0;
 }
 
+function extractAgentBranchFinishPrUrl(output) {
+  const match = String(output || '').match(/\[agent-branch-finish\] PR:\s*(\S+)/);
+  return match ? match[1] : '';
+}
+
+function doctorFinishFlowIsPending(output) {
+  return (
+    /\[agent-branch-finish\] PR merge not completed yet; leaving PR open\./.test(output) ||
+    /\[agent-branch-finish\] Merge pending review\/check policy\. Branch cleanup skipped for now\./.test(output) ||
+    /\[agent-branch-finish\] PR auto-merge enabled; waiting for required checks\/reviews\./.test(output)
+  );
+}
+
 function finishDoctorSandboxBranch(blocked, metadata) {
   const finishScript = path.join(metadata.worktreePath, 'scripts', 'agent-branch-finish.sh');
   if (!fs.existsSync(finishScript)) {
@@ -1122,6 +1250,17 @@ function finishDoctorSandboxBranch(blocked, metadata) {
     };
   }
 
+  const combinedOutput = `${finishResult.stdout || ''}\n${finishResult.stderr || ''}`;
+  if (doctorFinishFlowIsPending(combinedOutput)) {
+    return {
+      status: 'pending',
+      note: 'PR created and waiting for merge policy/checks',
+      prUrl: extractAgentBranchFinishPrUrl(combinedOutput),
+      stdout: finishResult.stdout || '',
+      stderr: finishResult.stderr || '',
+    };
+  }
+
   return {
     status: 'completed',
     note: 'doctor sandbox finish flow completed',
@@ -1157,7 +1296,35 @@ function runDoctorInSandbox(options, blocked) {
     status: 'skipped',
     note: 'sandbox doctor did not complete successfully',
   };
+  let postSandboxAutoFinishSummary = {
+    enabled: false,
+    attempted: 0,
+    completed: 0,
+    skipped: 0,
+    failed: 0,
+    details: ['Skipped auto-finish sweep (sandbox doctor did not complete successfully).'],
+  };
+  let omxScaffoldSyncResult = {
+    status: 'skipped',
+    note: 'sandbox doctor did not complete successfully',
+  };
   if (nestedResult.status === 0) {
+    const omxScaffoldOps = ensureOmxScaffold(blocked.repoRoot, Boolean(options.dryRun));
+    const changedOmxPaths = omxScaffoldOps.filter((operation) => operation.status !== 'unchanged');
+    if (changedOmxPaths.length === 0) {
+      omxScaffoldSyncResult = {
+        status: 'unchanged',
+        note: '.omx scaffold already in sync',
+        operations: omxScaffoldOps,
+      };
+    } else {
+      omxScaffoldSyncResult = {
+        status: options.dryRun ? 'would-sync' : 'synced',
+        note: `${options.dryRun ? 'would sync' : 'synced'} ${changedOmxPaths.length} .omx path(s)`,
+        operations: omxScaffoldOps,
+      };
+    }
+
     if (!options.dryRun) {
       autoCommitResult = autoCommitDoctorSandboxChanges(metadata);
       if (autoCommitResult.status === 'committed') {
@@ -1213,6 +1380,12 @@ function runDoctorInSandbox(options, blocked) {
         };
       }
     }
+
+    postSandboxAutoFinishSummary = autoFinishReadyAgentBranches(blocked.repoRoot, {
+      baseBranch: blocked.branch,
+      dryRun: options.dryRun,
+      excludeBranches: [metadata.branch],
+    });
   }
 
   if (options.json) {
@@ -1224,9 +1397,11 @@ function runDoctorInSandbox(options, blocked) {
             JSON.stringify(
               {
                 ...parsed,
+                sandboxOmxScaffoldSync: omxScaffoldSyncResult,
                 sandboxLockSync: lockSyncResult,
                 sandboxAutoCommit: autoCommitResult,
                 sandboxFinish: finishResult,
+                autoFinish: postSandboxAutoFinishSummary,
               },
               null,
               2,
@@ -1266,6 +1441,15 @@ function runDoctorInSandbox(options, blocked) {
         console.log(`[${TOOL_NAME}] Auto-finish flow completed for sandbox branch '${metadata.branch}'.`);
         if (finishResult.stdout) process.stdout.write(finishResult.stdout);
         if (finishResult.stderr) process.stderr.write(finishResult.stderr);
+      } else if (finishResult.status === 'pending') {
+        console.log(
+          `[${TOOL_NAME}] Auto-finish pending for sandbox branch '${metadata.branch}': ${finishResult.note}.`,
+        );
+        if (finishResult.prUrl) {
+          console.log(`[${TOOL_NAME}] PR: ${finishResult.prUrl}`);
+        }
+        if (finishResult.stdout) process.stdout.write(finishResult.stdout);
+        if (finishResult.stderr) process.stderr.write(finishResult.stderr);
       } else if (finishResult.status === 'failed') {
         console.log(`[${TOOL_NAME}] Auto-finish flow failed for sandbox branch '${metadata.branch}'.`);
         if (finishResult.stdout) process.stdout.write(finishResult.stdout);
@@ -1283,6 +1467,26 @@ function runDoctorInSandbox(options, blocked) {
       } else {
         console.log(`[${TOOL_NAME}] Lock registry sync skipped: ${lockSyncResult.note}.`);
       }
+
+      if (postSandboxAutoFinishSummary.enabled) {
+        console.log(
+          `[${TOOL_NAME}] Auto-finish sweep (base=${blocked.branch}): attempted=${postSandboxAutoFinishSummary.attempted}, completed=${postSandboxAutoFinishSummary.completed}, skipped=${postSandboxAutoFinishSummary.skipped}, failed=${postSandboxAutoFinishSummary.failed}`,
+        );
+        for (const detail of postSandboxAutoFinishSummary.details) {
+          console.log(`[${TOOL_NAME}]   ${detail}`);
+        }
+      } else if (postSandboxAutoFinishSummary.details.length > 0) {
+        console.log(`[${TOOL_NAME}] ${postSandboxAutoFinishSummary.details[0]}`);
+      }
+      if (omxScaffoldSyncResult.status === 'synced') {
+        console.log(`[${TOOL_NAME}] Synced .omx scaffold back to protected branch workspace.`);
+      } else if (omxScaffoldSyncResult.status === 'unchanged') {
+        console.log(`[${TOOL_NAME}] .omx scaffold already aligned in protected branch workspace.`);
+      } else if (omxScaffoldSyncResult.status === 'would-sync') {
+        console.log(`[${TOOL_NAME}] Dry run: would sync .omx scaffold back to protected branch workspace.`);
+      } else {
+        console.log(`[${TOOL_NAME}] .omx scaffold sync skipped: ${omxScaffoldSyncResult.note}.`);
+      }
     }
   }
 
@@ -1314,6 +1518,18 @@ function parseTargetFlag(rawArgs, defaultTarget = process.cwd()) {
   return { target, args: remaining };
 }
 
+function parseReviewArgs(rawArgs) {
+  const parsed = parseTargetFlag(rawArgs, process.cwd());
+  const passthroughArgs = [...parsed.args];
+  if (passthroughArgs[0] === 'start') {
+    passthroughArgs.shift();
+  }
+  return {
+    target: parsed.target,
+    passthroughArgs,
+  };
+}
+
 function parseReportArgs(rawArgs) {
   const options = {
     target: process.cwd(),
@@ -1579,6 +1795,203 @@ function listLocalUserBranches(repoRoot) {
   return [branchName];
 }
 
+function listLocalAgentBranches(repoRoot) {
+  const result = gitRun(
+    repoRoot,
+    ['for-each-ref', '--format=%(refname:short)', 'refs/heads/agent/'],
+    { allowFailure: true },
+  );
+  if (result.status !== 0) {
+    return [];
+  }
+  return uniquePreserveOrder(
+    String(result.stdout || '')
+      .split('\n')
+      .map((item) => item.trim())
+      .filter(Boolean),
+  );
+}
+
+function mapWorktreePathsByBranch(repoRoot) {
+  const result = gitRun(repoRoot, ['worktree', 'list', '--porcelain'], { allowFailure: true });
+  const map = new Map();
+  if (result.status !== 0) {
+    return map;
+  }
+
+  const lines = String(result.stdout || '').split('\n');
+  let currentWorktree = '';
+  for (const line of lines) {
+    if (line.startsWith('worktree ')) {
+      currentWorktree = line.slice('worktree '.length).trim();
+      continue;
+    }
+    if (line.startsWith('branch refs/heads/')) {
+      const branchName = line.slice('branch refs/heads/'.length).trim();
+      if (currentWorktree && branchName) {
+        map.set(branchName, currentWorktree);
+      }
+    }
+  }
+  return map;
+}
+
+function hasSignificantWorkingTreeChanges(worktreePath) {
+  const result = run('git', ['-C', worktreePath, 'status', '--porcelain']);
+  if (result.status !== 0) {
+    return true;
+  }
+
+  const lines = String(result.stdout || '')
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length > 0);
+
+  for (const line of lines) {
+    const pathPart = (line.length > 3 ? line.slice(3) : '').trim();
+    if (!pathPart) continue;
+    if (pathPart === LOCK_FILE_RELATIVE) continue;
+    if (pathPart.startsWith(`${LOCK_FILE_RELATIVE} -> `)) continue;
+    if (pathPart.endsWith(` -> ${LOCK_FILE_RELATIVE}`)) continue;
+    return true;
+  }
+  return false;
+}
+
+function autoFinishReadyAgentBranches(repoRoot, options = {}) {
+  const baseBranch = String(options.baseBranch || '').trim();
+  const dryRun = Boolean(options.dryRun);
+  const excludedBranches = new Set(
+    Array.isArray(options.excludeBranches)
+      ? options.excludeBranches.map((branch) => String(branch || '').trim()).filter(Boolean)
+      : [],
+  );
+
+  const summary = {
+    enabled: true,
+    baseBranch,
+    attempted: 0,
+    completed: 0,
+    skipped: 0,
+    failed: 0,
+    details: [],
+  };
+
+  if (!baseBranch || baseBranch === 'HEAD' || baseBranch.startsWith('agent/')) {
+    summary.enabled = false;
+    summary.details.push('Skipped auto-finish sweep (base branch is missing or not a non-agent local branch).');
+    return summary;
+  }
+
+  if (String(process.env.MUSAFETY_DOCTOR_SANDBOX || '') === '1') {
+    summary.enabled = false;
+    summary.details.push('Skipped auto-finish sweep inside doctor sandbox pass.');
+    return summary;
+  }
+
+  if (String(process.env.MUSAFETY_SKIP_AUTO_FINISH_READY_BRANCHES || '') === '1') {
+    summary.enabled = false;
+    summary.details.push('Skipped auto-finish sweep (MUSAFETY_SKIP_AUTO_FINISH_READY_BRANCHES=1).');
+    return summary;
+  }
+
+  if (dryRun) {
+    summary.enabled = false;
+    summary.details.push('Skipped auto-finish sweep in dry-run mode.');
+    return summary;
+  }
+
+  const finishScript = path.join(repoRoot, 'scripts', 'agent-branch-finish.sh');
+  if (!fs.existsSync(finishScript)) {
+    summary.enabled = false;
+    summary.details.push(`Skipped auto-finish sweep (missing ${path.relative(repoRoot, finishScript)}).`);
+    return summary;
+  }
+
+  const hasOrigin = gitRun(repoRoot, ['remote', 'get-url', 'origin'], { allowFailure: true }).status === 0;
+  if (!hasOrigin) {
+    summary.enabled = false;
+    summary.details.push('Skipped auto-finish sweep (origin remote missing).');
+    return summary;
+  }
+
+  const ghBin = process.env.MUSAFETY_GH_BIN || 'gh';
+  if (run(ghBin, ['--version']).status !== 0) {
+    summary.enabled = false;
+    summary.details.push(`Skipped auto-finish sweep (${ghBin} not available).`);
+    return summary;
+  }
+
+  const branchWorktrees = mapWorktreePathsByBranch(repoRoot);
+  const agentBranches = listLocalAgentBranches(repoRoot);
+  if (agentBranches.length === 0) {
+    summary.enabled = false;
+    summary.details.push('No local agent branches found for auto-finish sweep.');
+    return summary;
+  }
+
+  for (const branch of agentBranches) {
+    if (excludedBranches.has(branch)) {
+      summary.skipped += 1;
+      summary.details.push(`[skip] ${branch}: excluded from this auto-finish sweep.`);
+      continue;
+    }
+
+    if (branch === baseBranch) {
+      summary.skipped += 1;
+      summary.details.push(`[skip] ${branch}: source branch equals base branch.`);
+      continue;
+    }
+
+    let counts;
+    try {
+      counts = aheadBehind(repoRoot, branch, baseBranch);
+    } catch (error) {
+      summary.failed += 1;
+      summary.details.push(`[fail] ${branch}: unable to compute ahead/behind (${error.message}).`);
+      continue;
+    }
+
+    if (counts.ahead <= 0) {
+      summary.skipped += 1;
+      summary.details.push(`[skip] ${branch}: already merged into ${baseBranch}.`);
+      continue;
+    }
+
+    const branchWorktree = branchWorktrees.get(branch) || '';
+    if (branchWorktree && hasSignificantWorkingTreeChanges(branchWorktree)) {
+      summary.skipped += 1;
+      summary.details.push(`[skip] ${branch}: dirty worktree (${branchWorktree}).`);
+      continue;
+    }
+
+    summary.attempted += 1;
+    const finishArgs = [
+      finishScript,
+      '--branch',
+      branch,
+      '--base',
+      baseBranch,
+      '--via-pr',
+      '--cleanup',
+    ];
+    const finishResult = run('bash', finishArgs, { cwd: repoRoot });
+    const combinedOutput = [finishResult.stdout || '', finishResult.stderr || ''].join('\n').trim();
+
+    if (finishResult.status === 0) {
+      summary.completed += 1;
+      summary.details.push(`[done] ${branch}: auto-finish completed.`);
+      continue;
+    }
+
+    summary.failed += 1;
+    const tail = combinedOutput ? ` ${combinedOutput.split('\n').slice(-2).join(' | ')}` : '';
+    summary.details.push(`[fail] ${branch}: auto-finish failed.${tail}`);
+  }
+
+  return summary;
+}
+
 function ensureSetupProtectedBranches(repoRoot, dryRun) {
   const localUserBranches = listLocalUserBranches(repoRoot);
   if (localUserBranches.length === 0) {
@@ -1818,6 +2231,7 @@ function parseCleanupArgs(rawArgs) {
     dryRun: false,
     forceDirty: false,
     keepRemote: false,
+    keepCleanWorktrees: false,
   };
 
   for (let index = 0; index < rawArgs.length; index += 1) {
@@ -1861,6 +2275,10 @@ function parseCleanupArgs(rawArgs) {
       options.keepRemote = true;
       continue;
     }
+    if (arg === '--keep-clean-worktrees') {
+      options.keepCleanWorktrees = true;
+      continue;
+    }
     throw new Error(`Unknown option: ${arg}`);
   }
 
@@ -2271,6 +2689,8 @@ function runInstallInternal(options) {
   const repoRoot = resolveRepoRoot(options.target);
   const operations = [];
 
+  operations.push(...ensureOmxScaffold(repoRoot, Boolean(options.dryRun)));
+
   for (const templateFile of TEMPLATE_FILES) {
     operations.push(copyTemplateFile(repoRoot, templateFile, Boolean(options.force), Boolean(options.dryRun)));
   }
@@ -2297,6 +2717,8 @@ function runFixInternal(options) {
   const repoRoot = resolveRepoRoot(options.target);
   const operations = [];
 
+  operations.push(...ensureOmxScaffold(repoRoot, Boolean(options.dryRun)));
+
   for (const templateFile of TEMPLATE_FILES) {
     operations.push(ensureTemplateFilePresent(repoRoot, templateFile, Boolean(options.dryRun)));
   }
@@ -2350,6 +2772,8 @@ function runScanInternal(options) {
   const findings = [];
 
   const requiredPaths = [
+    ...OMX_SCAFFOLD_DIRECTORIES,
+    ...Array.from(OMX_SCAFFOLD_FILES.keys()),
     ...TEMPLATE_FILES.map((entry) => toDestinationPath(entry)),
     LOCK_FILE_RELATIVE,
   ];
@@ -2701,6 +3125,11 @@ function doctor(rawArgs) {
   assertProtectedMainWriteAllowed(options, 'doctor');
   const fixPayload = runFixInternal(options);
   const scanResult = runScanInternal({ target: options.target, json: false });
+  const currentBaseBranch = currentBranchName(scanResult.repoRoot);
+  const autoFinishSummary = autoFinishReadyAgentBranches(scanResult.repoRoot, {
+    baseBranch: currentBaseBranch,
+    dryRun: options.dryRun,
+  });
   const safe = scanResult.errors === 0 && scanResult.warnings === 0;
   const musafe = safe;
 
@@ -2722,6 +3151,7 @@ function doctor(rawArgs) {
             warnings: scanResult.warnings,
             findings: scanResult.findings,
           },
+          autoFinish: autoFinishSummary,
         },
         null,
         2,
@@ -2733,6 +3163,16 @@ function doctor(rawArgs) {
 
   printOperations('Doctor/fix', fixPayload, options.dryRun);
   printScanResult(scanResult, false);
+  if (autoFinishSummary.enabled) {
+    console.log(
+      `[${TOOL_NAME}] Auto-finish sweep (base=${currentBaseBranch}): attempted=${autoFinishSummary.attempted}, completed=${autoFinishSummary.completed}, skipped=${autoFinishSummary.skipped}, failed=${autoFinishSummary.failed}`,
+    );
+    for (const detail of autoFinishSummary.details) {
+      console.log(`[${TOOL_NAME}]   ${detail}`);
+    }
+  } else if (autoFinishSummary.details.length > 0) {
+    console.log(`[${TOOL_NAME}] ${autoFinishSummary.details[0]}`);
+  }
   if (safe) {
     console.log(`[${TOOL_NAME}] ✅ Repo is fully safe.`);
   } else {
@@ -2743,6 +3183,27 @@ function doctor(rawArgs) {
   setExitCodeFromScan(scanResult);
 }
 
+function review(rawArgs) {
+  const options = parseReviewArgs(rawArgs);
+  const repoRoot = resolveRepoRoot(options.target);
+  const reviewScriptPath = path.join(repoRoot, 'scripts', 'review-bot-watch.sh');
+  if (!fs.existsSync(reviewScriptPath)) {
+    throw new Error(
+      `Missing review bot script: ${reviewScriptPath}\n` +
+      `Run '${SHORT_TOOL_NAME} setup --target ${repoRoot}' then '${SHORT_TOOL_NAME} doctor --target ${repoRoot}'.`,
+    );
+  }
+
+  const result = run('bash', [reviewScriptPath, ...options.passthroughArgs], { cwd: repoRoot });
+  if (isSpawnFailure(result)) {
+    throw result.error;
+  }
+
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exitCode = typeof result.status === 'number' ? result.status : 1;
+}
+
 function report(rawArgs) {
   const options = parseReportArgs(rawArgs);
   const subcommand = options.subcommand || 'help';
@@ -2901,7 +3362,22 @@ function setup(rawArgs) {
   }
 
   const scanResult = runScanInternal({ target: options.target, json: false });
+  const currentBaseBranch = currentBranchName(scanResult.repoRoot);
+  const autoFinishSummary = autoFinishReadyAgentBranches(scanResult.repoRoot, {
+    baseBranch: currentBaseBranch,
+    dryRun: options.dryRun,
+  });
   printScanResult(scanResult, false);
+  if (autoFinishSummary.enabled) {
+    console.log(
+      `[${TOOL_NAME}] Auto-finish sweep (base=${currentBaseBranch}): attempted=${autoFinishSummary.attempted}, completed=${autoFinishSummary.completed}, skipped=${autoFinishSummary.skipped}, failed=${autoFinishSummary.failed}`,
+    );
+    for (const detail of autoFinishSummary.details) {
+      console.log(`[${TOOL_NAME}]   ${detail}`);
+    }
+  } else if (autoFinishSummary.details.length > 0) {
+    console.log(`[${TOOL_NAME}] ${autoFinishSummary.details[0]}`);
+  }
 
   if (scanResult.errors === 0 && scanResult.warnings === 0) {
     console.log(`[${TOOL_NAME}] ✅ Setup complete.`);
@@ -2996,6 +3472,9 @@ function cleanup(rawArgs) {
   if (options.dryRun) {
     args.push('--dry-run');
   }
+  if (!options.keepCleanWorktrees) {
+    args.push('--only-dirty-worktrees');
+  }
   args.push('--delete-branches');
   if (!options.keepRemote) {
     args.push('--delete-remote-branches');
@@ -3331,6 +3810,11 @@ function main() {
     return;
   }
 
+  if (command === 'review') {
+    review(rest);
+    return;
+  }
+
   if (command === 'report') {
     report(rest);
     return;