@imdeadpool/guardex 5.0.8 → 5.0.11

package/bin/multiagent-safety.js

@@ -78,6 +78,7 @@ const CRITICAL_GUARDRAIL_PATHS = new Set([
 ]);
 
 const LOCK_FILE_RELATIVE = '.omx/state/agent-file-locks.json';
+const AGENTS_BOTS_STATE_RELATIVE = '.omx/state/agents-bots.json';
 const AGENTS_MARKER_START = '<!-- multiagent-safety:START -->';
 const AGENTS_MARKER_END = '<!-- multiagent-safety:END -->';
 const GITIGNORE_MARKER_START = '# multiagent-safety:START';
@@ -128,6 +129,8 @@ const SUGGESTIBLE_COMMANDS = [
   'init',
   'doctor',
   'review',
+  'agents',
+  'finish',
   'report',
   'copy-prompt',
   'copy-commands',
@@ -148,11 +151,13 @@ const CLI_COMMAND_DESCRIPTIONS = [
   ['init', 'Alias of setup (bootstrap + repair guardrails in a git repo)'],
   ['doctor', 'Repair safety setup drift, then verify repo safety'],
   ['report', 'Generate security/safety reports (for example: OpenSSF scorecard)'],
+  ['finish', 'Auto-commit completed agent branches, then run PR finish flow'],
   ['copy-prompt', 'Print the AI-ready setup checklist'],
   ['copy-commands', 'Print setup checklist as executable commands only'],
   ['protect', 'Manage protected branches (list/add/remove/set/reset)'],
   ['sync', 'Check or sync agent branches with origin/<base>'],
-  ['cleanup', 'Cleanup merged agent branches/worktrees (local + remote)'],
+  ['cleanup', 'Cleanup agent branches/worktrees (supports idle watch mode)'],
+  ['agents', 'Start/stop repo-scoped review + cleanup bots'],
   ['install', 'Install templates/locks/hooks without running full setup (supports --no-gitignore)'],
   ['fix', 'Repair broken or missing guardrail files/config (supports --no-gitignore)'],
   ['scan', 'Report safety issues and exit non-zero on findings'],
@@ -163,6 +168,7 @@ const CLI_COMMAND_DESCRIPTIONS = [
 ];
 const AGENT_BOT_DESCRIPTIONS = [
   ['review', 'Start PR monitor + codex-agent review flow (default interval: 30s)'],
+  ['agents', 'Start/stop both review and cleanup bots for this repo'],
 ];
 
 const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-Rex for your repo) in this repository for Codex or Claude.
@@ -198,18 +204,31 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
    - Finished branches stay available by default for audit/follow-up.
      Remove them explicitly when done:
      gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
+   - To finalize all completed agent branches in one pass:
+     gx finish --all
 
-6) Optional: create OpenSpec planning workspace:
+6) OpenSpec default change flow (core profile):
+   /opsx:propose <change-name>
+   /opsx:apply
+   /opsx:archive
+   - Full guide: docs/openspec-getting-started.md
+
+7) Optional: enable expanded OpenSpec workflow commands:
+   openspec config profile <profile-name>
+   openspec update
+   - Expanded path: /opsx:new -> /opsx:ff or /opsx:continue -> /opsx:apply -> /opsx:verify -> /opsx:archive
+
+8) Optional: create OpenSpec planning workspace:
    bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
 
-7) Optional: protect extra branches:
+9) Optional: protect extra branches:
    gx protect add release staging
 
-8) Optional: sync your current agent branch with latest base branch:
+10) Optional: sync your current agent branch with latest base branch:
    gx sync --check
    gx sync
 
-9) Optional (GitHub remote cleanup): enable:
+11) Optional (GitHub remote cleanup): enable:
    Settings -> General -> Pull Requests -> Automatically delete head branches
 `;
 
@@ -222,8 +241,11 @@ 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...>
 bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)"
+gx finish --all
 gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
 bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
+openspec config profile <profile-name>
+openspec update
 gx protect add release staging
 gx sync --check
 gx sync
@@ -628,6 +650,7 @@ function ensurePackageScripts(repoRoot, dryRun) {
     '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:finish': `${SHORT_TOOL_NAME} finish --all`,
     'agent:cleanup': `${SHORT_TOOL_NAME} cleanup`,
     'agent:hooks:install': 'bash ./scripts/install-agent-git-hooks.sh',
     'agent:locks:claim': 'python3 ./scripts/agent-file-locks.py claim',
@@ -1180,6 +1203,14 @@ function hasOriginRemote(repoRoot) {
   return run('git', ['-C', repoRoot, 'remote', 'get-url', 'origin']).status === 0;
 }
 
+function originRemoteLooksLikeGithub(repoRoot) {
+  const originUrl = readGitConfig(repoRoot, 'remote.origin.url');
+  if (!originUrl) {
+    return false;
+  }
+  return /github\.com[:/]/i.test(originUrl);
+}
+
 function isCommandAvailable(commandName) {
   return run('which', [commandName]).status === 0;
 }
@@ -1211,6 +1242,13 @@ function finishDoctorSandboxBranch(blocked, metadata) {
       note: 'origin remote missing; skipped auto-finish',
     };
   }
+  const explicitGhBin = Boolean(String(process.env.MUSAFETY_GH_BIN || '').trim());
+  if (!explicitGhBin && !originRemoteLooksLikeGithub(blocked.repoRoot)) {
+    return {
+      status: 'skipped',
+      note: 'origin remote is not GitHub; skipped auto-finish PR flow',
+    };
+  }
 
   const ghBin = process.env.MUSAFETY_GH_BIN || 'gh';
   if (!isCommandAvailable(ghBin)) {
@@ -1228,10 +1266,15 @@ function finishDoctorSandboxBranch(blocked, metadata) {
     };
   }
 
+  const rawWaitTimeoutSeconds = Number.parseInt(process.env.MUSAFETY_FINISH_WAIT_TIMEOUT_SECONDS || '1800', 10);
+  const waitTimeoutSeconds =
+    Number.isFinite(rawWaitTimeoutSeconds) && rawWaitTimeoutSeconds >= 30 ? rawWaitTimeoutSeconds : 1800;
+  const finishTimeoutMs = Math.max(180_000, (waitTimeoutSeconds + 60) * 1000);
+
   const finishResult = run(
     'bash',
-    [finishScript, '--branch', metadata.branch, '--via-pr'],
-    { cwd: metadata.worktreePath, timeout: 180_000 },
+    [finishScript, '--branch', metadata.branch, '--via-pr', '--wait-for-merge'],
+    { cwd: metadata.worktreePath, timeout: finishTimeoutMs },
   );
   if (isSpawnFailure(finishResult)) {
     return {
@@ -1491,7 +1534,18 @@ function runDoctorInSandbox(options, blocked) {
   }
 
   if (typeof nestedResult.status === 'number') {
-    process.exitCode = nestedResult.status;
+    let exitCode = nestedResult.status;
+    if (exitCode === 0 && autoCommitResult.status === 'failed') {
+      exitCode = 1;
+    }
+    if (
+      exitCode === 0 &&
+      autoCommitResult.status === 'committed' &&
+      (finishResult.status === 'failed' || finishResult.status === 'pending')
+    ) {
+      exitCode = 1;
+    }
+    process.exitCode = exitCode;
     return;
   }
   process.exitCode = 1;
@@ -1530,6 +1584,69 @@ function parseReviewArgs(rawArgs) {
   };
 }
 
+function parseAgentsArgs(rawArgs) {
+  const parsed = parseTargetFlag(rawArgs, process.cwd());
+  const [subcommandRaw = '', ...rest] = parsed.args;
+  const subcommand = subcommandRaw || 'status';
+  const options = {
+    target: parsed.target,
+    subcommand,
+    reviewIntervalSeconds: 30,
+    cleanupIntervalSeconds: 60,
+    idleMinutes: 10,
+  };
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    if (arg === '--review-interval') {
+      const next = rest[index + 1];
+      if (!next) {
+        throw new Error('--review-interval requires an integer seconds value');
+      }
+      const parsedValue = Number.parseInt(next, 10);
+      if (!Number.isInteger(parsedValue) || parsedValue < 5) {
+        throw new Error('--review-interval must be an integer >= 5 seconds');
+      }
+      options.reviewIntervalSeconds = parsedValue;
+      index += 1;
+      continue;
+    }
+    if (arg === '--cleanup-interval') {
+      const next = rest[index + 1];
+      if (!next) {
+        throw new Error('--cleanup-interval requires an integer seconds value');
+      }
+      const parsedValue = Number.parseInt(next, 10);
+      if (!Number.isInteger(parsedValue) || parsedValue < 5) {
+        throw new Error('--cleanup-interval must be an integer >= 5 seconds');
+      }
+      options.cleanupIntervalSeconds = parsedValue;
+      index += 1;
+      continue;
+    }
+    if (arg === '--idle-minutes') {
+      const next = rest[index + 1];
+      if (!next) {
+        throw new Error('--idle-minutes requires an integer minutes value');
+      }
+      const parsedValue = Number.parseInt(next, 10);
+      if (!Number.isInteger(parsedValue) || parsedValue < 1) {
+        throw new Error('--idle-minutes must be an integer >= 1');
+      }
+      options.idleMinutes = parsedValue;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (!['start', 'stop', 'status'].includes(options.subcommand)) {
+    throw new Error(`Unknown agents subcommand: ${options.subcommand}`);
+  }
+
+  return options;
+}
+
 function parseReportArgs(rawArgs) {
   const options = {
     target: process.cwd(),
@@ -1914,6 +2031,12 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
     summary.details.push('Skipped auto-finish sweep (origin remote missing).');
     return summary;
   }
+  const explicitGhBin = Boolean(String(process.env.MUSAFETY_GH_BIN || '').trim());
+  if (!explicitGhBin && !originRemoteLooksLikeGithub(repoRoot)) {
+    summary.enabled = false;
+    summary.details.push('Skipped auto-finish sweep (origin remote is not GitHub).');
+    return summary;
+  }
 
   const ghBin = process.env.MUSAFETY_GH_BIN || 'gh';
   if (run(ghBin, ['--version']).status !== 0) {
@@ -1973,6 +2096,7 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
       '--base',
       baseBranch,
       '--via-pr',
+      '--wait-for-merge',
       '--cleanup',
     ];
     const finishResult = run('bash', finishArgs, { cwd: repoRoot });
@@ -2232,6 +2356,10 @@ function parseCleanupArgs(rawArgs) {
     forceDirty: false,
     keepRemote: false,
     keepCleanWorktrees: false,
+    idleMinutes: 0,
+    watch: false,
+    intervalSeconds: 60,
+    once: false,
   };
 
   for (let index = 0; index < rawArgs.length; index += 1) {
@@ -2279,12 +2407,426 @@ function parseCleanupArgs(rawArgs) {
       options.keepCleanWorktrees = true;
       continue;
     }
+    if (arg === '--idle-minutes') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--idle-minutes requires an integer value');
+      }
+      const parsed = Number.parseInt(next, 10);
+      if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new Error('--idle-minutes must be an integer >= 0');
+      }
+      options.idleMinutes = parsed;
+      index += 1;
+      continue;
+    }
+    if (arg === '--watch') {
+      options.watch = true;
+      continue;
+    }
+    if (arg === '--interval') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--interval requires an integer seconds value');
+      }
+      const parsed = Number.parseInt(next, 10);
+      if (!Number.isInteger(parsed) || parsed < 5) {
+        throw new Error('--interval must be an integer >= 5 seconds');
+      }
+      options.intervalSeconds = parsed;
+      index += 1;
+      continue;
+    }
+    if (arg === '--once') {
+      options.once = true;
+      continue;
+    }
     throw new Error(`Unknown option: ${arg}`);
   }
 
+  if (options.watch && options.idleMinutes === 0) {
+    options.idleMinutes = 10;
+  }
+
   return options;
 }
 
+function parseFinishArgs(rawArgs) {
+  const options = {
+    target: process.cwd(),
+    base: '',
+    branch: '',
+    all: false,
+    dryRun: false,
+    waitForMerge: true,
+    cleanup: true,
+    keepRemote: false,
+    noAutoCommit: false,
+    failFast: false,
+    commitMessage: '',
+  };
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === '--target') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--target requires a path value');
+      }
+      options.target = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--base') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--base requires a branch value');
+      }
+      options.base = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--branch') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--branch requires an agent/* branch value');
+      }
+      options.branch = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--commit-message') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--commit-message requires a value');
+      }
+      options.commitMessage = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--all') {
+      options.all = true;
+      continue;
+    }
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+    if (arg === '--wait-for-merge') {
+      options.waitForMerge = true;
+      continue;
+    }
+    if (arg === '--no-wait-for-merge') {
+      options.waitForMerge = false;
+      continue;
+    }
+    if (arg === '--cleanup') {
+      options.cleanup = true;
+      continue;
+    }
+    if (arg === '--no-cleanup') {
+      options.cleanup = false;
+      continue;
+    }
+    if (arg === '--keep-remote') {
+      options.keepRemote = true;
+      continue;
+    }
+    if (arg === '--no-auto-commit') {
+      options.noAutoCommit = true;
+      continue;
+    }
+    if (arg === '--fail-fast') {
+      options.failFast = true;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (options.branch && !options.branch.startsWith('agent/')) {
+    throw new Error(`--branch must reference an agent/* branch (received: ${options.branch})`);
+  }
+
+  return options;
+}
+
+function listAgentWorktrees(repoRoot) {
+  const result = gitRun(repoRoot, ['worktree', 'list', '--porcelain'], { allowFailure: true });
+  if (result.status !== 0) {
+    throw new Error('Unable to list git worktrees for finish command');
+  }
+
+  const entries = [];
+  let currentPath = '';
+  let currentBranchRef = '';
+  const lines = String(result.stdout || '').split('\n');
+  for (const line of lines) {
+    if (!line.trim()) {
+      if (currentPath && currentBranchRef.startsWith('refs/heads/agent/')) {
+        entries.push({
+          worktreePath: currentPath,
+          branch: currentBranchRef.replace(/^refs\/heads\//, ''),
+        });
+      }
+      currentPath = '';
+      currentBranchRef = '';
+      continue;
+    }
+    if (line.startsWith('worktree ')) {
+      currentPath = line.slice('worktree '.length).trim();
+      continue;
+    }
+    if (line.startsWith('branch ')) {
+      currentBranchRef = line.slice('branch '.length).trim();
+      continue;
+    }
+  }
+  if (currentPath && currentBranchRef.startsWith('refs/heads/agent/')) {
+    entries.push({
+      worktreePath: currentPath,
+      branch: currentBranchRef.replace(/^refs\/heads\//, ''),
+    });
+  }
+
+  return entries;
+}
+
+function listLocalAgentBranchesForFinish(repoRoot) {
+  const result = gitRun(
+    repoRoot,
+    ['for-each-ref', '--format=%(refname:short)', 'refs/heads/agent/'],
+    { allowFailure: true },
+  );
+  if (result.status !== 0) {
+    throw new Error('Unable to list local agent branches');
+  }
+  return uniquePreserveOrder(
+    String(result.stdout || '')
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.startsWith('agent/')),
+  );
+}
+
+function gitQuietChangeResult(worktreePath, args) {
+  const result = run('git', ['-C', worktreePath, ...args], { stdio: 'pipe' });
+  if (result.status === 0) {
+    return false;
+  }
+  if (result.status === 1) {
+    return true;
+  }
+  throw new Error(
+    `git ${args.join(' ')} failed in ${worktreePath}: ${(
+      result.stderr || result.stdout || ''
+    ).trim()}`,
+  );
+}
+
+function worktreeHasLocalChanges(worktreePath) {
+  const hasUnstaged = gitQuietChangeResult(worktreePath, [
+    'diff',
+    '--quiet',
+    '--',
+    '.',
+    ':(exclude).omx/state/agent-file-locks.json',
+  ]);
+  if (hasUnstaged) {
+    return true;
+  }
+
+  const hasStaged = gitQuietChangeResult(worktreePath, [
+    'diff',
+    '--cached',
+    '--quiet',
+    '--',
+    '.',
+    ':(exclude).omx/state/agent-file-locks.json',
+  ]);
+  if (hasStaged) {
+    return true;
+  }
+
+  const untracked = run('git', ['-C', worktreePath, 'ls-files', '--others', '--exclude-standard'], {
+    stdio: 'pipe',
+  });
+  if (untracked.status !== 0) {
+    throw new Error(`Unable to inspect untracked files in ${worktreePath}`);
+  }
+  return String(untracked.stdout || '').trim().length > 0;
+}
+
+function gitOutputLines(worktreePath, args) {
+  const result = run('git', ['-C', worktreePath, ...args], { stdio: 'pipe' });
+  if (result.status !== 0) {
+    throw new Error(
+      `git ${args.join(' ')} failed in ${worktreePath}: ${(
+        result.stderr || result.stdout || ''
+      ).trim()}`,
+    );
+  }
+  return String(result.stdout || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function claimLocksForAutoCommit(repoRoot, worktreePath, branch) {
+  const lockScript = path.join(repoRoot, 'scripts', 'agent-file-locks.py');
+  if (!fs.existsSync(lockScript)) {
+    return;
+  }
+
+  const changedFiles = uniquePreserveOrder([
+    ...gitOutputLines(worktreePath, ['diff', '--name-only', '--', '.', ':(exclude).omx/state/agent-file-locks.json']),
+    ...gitOutputLines(worktreePath, ['diff', '--cached', '--name-only', '--', '.', ':(exclude).omx/state/agent-file-locks.json']),
+    ...gitOutputLines(worktreePath, ['ls-files', '--others', '--exclude-standard']),
+  ]);
+
+  if (changedFiles.length > 0) {
+    const claim = run('python3', [lockScript, 'claim', '--branch', branch, ...changedFiles], {
+      cwd: repoRoot,
+      stdio: 'pipe',
+    });
+    if (claim.status !== 0) {
+      throw new Error(
+        `Lock claim failed for ${branch}: ${(
+          claim.stderr || claim.stdout || ''
+        ).trim()}`,
+      );
+    }
+  }
+
+  const deletedFiles = uniquePreserveOrder([
+    ...gitOutputLines(worktreePath, [
+      'diff',
+      '--name-only',
+      '--diff-filter=D',
+      '--',
+      '.',
+      ':(exclude).omx/state/agent-file-locks.json',
+    ]),
+    ...gitOutputLines(worktreePath, [
+      'diff',
+      '--cached',
+      '--name-only',
+      '--diff-filter=D',
+      '--',
+      '.',
+      ':(exclude).omx/state/agent-file-locks.json',
+    ]),
+  ]);
+
+  if (deletedFiles.length > 0) {
+    const allowDelete = run('python3', [lockScript, 'allow-delete', '--branch', branch, ...deletedFiles], {
+      cwd: repoRoot,
+      stdio: 'pipe',
+    });
+    if (allowDelete.status !== 0) {
+      throw new Error(
+        `Delete-lock grant failed for ${branch}: ${(
+          allowDelete.stderr || allowDelete.stdout || ''
+        ).trim()}`,
+      );
+    }
+  }
+}
+
+function branchExists(repoRoot, branch) {
+  const result = gitRun(repoRoot, ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], {
+    allowFailure: true,
+  });
+  return result.status === 0;
+}
+
+function resolveFinishBaseBranch(repoRoot, sourceBranch, explicitBase) {
+  if (explicitBase) {
+    return explicitBase;
+  }
+
+  const branchSpecific = readGitConfig(repoRoot, `branch.${sourceBranch}.musafetyBase`);
+  if (branchSpecific) {
+    return branchSpecific;
+  }
+
+  const configured = readGitConfig(repoRoot, GIT_BASE_BRANCH_KEY);
+  if (configured) {
+    return configured;
+  }
+
+  const current = gitRun(repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD'], { allowFailure: true });
+  const currentBranch = String(current.stdout || '').trim();
+  if (current.status === 0 && currentBranch && currentBranch !== 'HEAD' && !currentBranch.startsWith('agent/')) {
+    return currentBranch;
+  }
+
+  return DEFAULT_BASE_BRANCH;
+}
+
+function branchMergedIntoBase(repoRoot, branch, baseBranch) {
+  if (!branchExists(repoRoot, baseBranch)) {
+    return false;
+  }
+  const result = gitRun(repoRoot, ['merge-base', '--is-ancestor', branch, baseBranch], {
+    allowFailure: true,
+  });
+  if (result.status === 0) {
+    return true;
+  }
+  if (result.status === 1) {
+    return false;
+  }
+  throw new Error(`Unable to determine merge status for ${branch} -> ${baseBranch}`);
+}
+
+function autoCommitWorktreeForFinish(repoRoot, worktreePath, branch, options) {
+  const hasChanges = worktreeHasLocalChanges(worktreePath);
+  if (!hasChanges) {
+    return { changed: false, committed: false };
+  }
+
+  if (options.noAutoCommit) {
+    throw new Error(
+      `Branch '${branch}' has local changes in ${worktreePath}. Re-run without --no-auto-commit or commit manually first.`,
+    );
+  }
+
+  if (options.dryRun) {
+    return { changed: true, committed: false, dryRun: true };
+  }
+
+  claimLocksForAutoCommit(repoRoot, worktreePath, branch);
+
+  const addResult = run('git', ['-C', worktreePath, 'add', '-A'], { stdio: 'pipe' });
+  if (addResult.status !== 0) {
+    throw new Error(`git add failed in ${worktreePath}: ${(addResult.stderr || addResult.stdout || '').trim()}`);
+  }
+
+  const stagedHasChanges = gitQuietChangeResult(worktreePath, [
+    'diff',
+    '--cached',
+    '--quiet',
+    '--',
+    '.',
+    ':(exclude).omx/state/agent-file-locks.json',
+  ]);
+  if (!stagedHasChanges) {
+    return { changed: true, committed: false };
+  }
+
+  const commitMessage = options.commitMessage || `Auto-finish: ${branch}`;
+  const commitResult = run('git', ['-C', worktreePath, 'commit', '-m', commitMessage], { stdio: 'pipe' });
+  if (commitResult.status !== 0) {
+    throw new Error(
+      `Auto-commit failed on '${branch}': ${(
+        commitResult.stderr || commitResult.stdout || ''
+      ).trim()}`,
+    );
+  }
+
+  return { changed: true, committed: true, message: commitMessage };
+}
+
 function syncOperation(repoRoot, strategy, baseRef, ffOnly) {
   if (strategy === 'rebase') {
     if (ffOnly) {
@@ -3065,6 +3607,9 @@ function install(rawArgs) {
   printOperations('Install target', payload, options.dryRun);
 
   if (!options.dryRun) {
+    if (!options.skipAgents) {
+      console.log(`[${TOOL_NAME}] AGENTS.md managed policy block is configured by install.`);
+    }
     console.log(`[${TOOL_NAME}] Installed. Next step: ${TOOL_NAME} setup`);
   }
 
@@ -3204,6 +3749,263 @@ function review(rawArgs) {
   process.exitCode = typeof result.status === 'number' ? result.status : 1;
 }
 
+function agentsStatePathForRepo(repoRoot) {
+  return path.join(repoRoot, AGENTS_BOTS_STATE_RELATIVE);
+}
+
+function readAgentsState(repoRoot) {
+  const statePath = agentsStatePathForRepo(repoRoot);
+  if (!fs.existsSync(statePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(statePath, 'utf8'));
+  } catch (_error) {
+    return null;
+  }
+}
+
+function writeAgentsState(repoRoot, state) {
+  const statePath = agentsStatePathForRepo(repoRoot);
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  fs.writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+
+function processAlive(pid) {
+  const normalizedPid = Number.parseInt(String(pid || ''), 10);
+  if (!Number.isInteger(normalizedPid) || normalizedPid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(normalizedPid, 0);
+    return true;
+  } catch (_error) {
+    return false;
+  }
+}
+
+function sleepSeconds(seconds) {
+  const result = run('sleep', [String(seconds)]);
+  if (isSpawnFailure(result) || result.status !== 0) {
+    throw new Error(`sleep command failed for ${seconds}s`);
+  }
+}
+
+function readProcessCommand(pid) {
+  const result = run('ps', ['-o', 'command=', '-p', String(pid)]);
+  if (isSpawnFailure(result) || result.status !== 0) {
+    return '';
+  }
+  return String(result.stdout || '').trim();
+}
+
+function stopAgentProcessByPid(pid, expectedToken = '') {
+  const normalizedPid = Number.parseInt(String(pid || ''), 10);
+  if (!Number.isInteger(normalizedPid) || normalizedPid <= 0) {
+    return { status: 'invalid', pid: normalizedPid };
+  }
+  if (!processAlive(normalizedPid)) {
+    return { status: 'not-running', pid: normalizedPid };
+  }
+
+  if (expectedToken) {
+    const cmdline = readProcessCommand(normalizedPid);
+    if (cmdline && !cmdline.includes(expectedToken)) {
+      return { status: 'mismatch', pid: normalizedPid, command: cmdline };
+    }
+  }
+
+  try {
+    process.kill(-normalizedPid, 'SIGTERM');
+  } catch (_error) {
+    try {
+      process.kill(normalizedPid, 'SIGTERM');
+    } catch (_err) {
+      return { status: 'term-failed', pid: normalizedPid };
+    }
+  }
+
+  const deadline = Date.now() + 3_000;
+  while (Date.now() < deadline) {
+    if (!processAlive(normalizedPid)) {
+      return { status: 'stopped', pid: normalizedPid };
+    }
+    sleepSeconds(0.1);
+  }
+
+  try {
+    process.kill(-normalizedPid, 'SIGKILL');
+  } catch (_error) {
+    try {
+      process.kill(normalizedPid, 'SIGKILL');
+    } catch (_err) {
+      return { status: 'kill-failed', pid: normalizedPid };
+    }
+  }
+  sleepSeconds(0.1);
+
+  return {
+    status: processAlive(normalizedPid) ? 'kill-failed' : 'stopped',
+    pid: normalizedPid,
+  };
+}
+
+function spawnDetachedAgentProcess({ command, args, cwd, logPath }) {
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  const logHandle = fs.openSync(logPath, 'a');
+  fs.writeSync(
+    logHandle,
+    `[${new Date().toISOString()}] spawn: ${command} ${args.join(' ')}\n`,
+  );
+  const child = cp.spawn(command, args, {
+    cwd,
+    detached: true,
+    stdio: ['ignore', logHandle, logHandle],
+    env: process.env,
+  });
+  fs.closeSync(logHandle);
+  if (child.error) {
+    throw child.error;
+  }
+  child.unref();
+  const pid = Number.parseInt(String(child.pid || ''), 10);
+  if (!Number.isInteger(pid) || pid <= 0) {
+    throw new Error(`Failed to spawn detached process for ${command}`);
+  }
+  return pid;
+}
+
+function agents(rawArgs) {
+  const options = parseAgentsArgs(rawArgs);
+  const repoRoot = resolveRepoRoot(options.target);
+  const reviewScriptPath = path.join(repoRoot, 'scripts', 'review-bot-watch.sh');
+  const pruneScriptPath = path.join(repoRoot, 'scripts', 'agent-worktree-prune.sh');
+  const statePath = agentsStatePathForRepo(repoRoot);
+
+  if (options.subcommand === 'start') {
+    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}'.`,
+      );
+    }
+    if (!fs.existsSync(pruneScriptPath)) {
+      throw new Error(
+        `Missing cleanup script: ${pruneScriptPath}\n` +
+          `Run '${SHORT_TOOL_NAME} setup --target ${repoRoot}' then '${SHORT_TOOL_NAME} doctor --target ${repoRoot}'.`,
+      );
+    }
+
+    const existingState = readAgentsState(repoRoot);
+    const existingReviewPid = Number.parseInt(String(existingState?.review?.pid || ''), 10);
+    const existingCleanupPid = Number.parseInt(String(existingState?.cleanup?.pid || ''), 10);
+    const reviewRunning = processAlive(existingReviewPid);
+    const cleanupRunning = processAlive(existingCleanupPid);
+
+    if (reviewRunning && cleanupRunning) {
+      console.log(
+        `[${TOOL_NAME}] Repo agents already running (review pid=${existingReviewPid}, cleanup pid=${existingCleanupPid}).`,
+      );
+      process.exitCode = 0;
+      return;
+    }
+
+    if (reviewRunning) {
+      stopAgentProcessByPid(existingReviewPid, 'review-bot-watch.sh');
+    }
+    if (cleanupRunning) {
+      stopAgentProcessByPid(existingCleanupPid, `${path.basename(__filename)} cleanup`);
+    }
+
+    const reviewLogPath = path.join(repoRoot, '.omx', 'logs', 'agent-review.log');
+    const cleanupLogPath = path.join(repoRoot, '.omx', 'logs', 'agent-cleanup.log');
+    const reviewPid = spawnDetachedAgentProcess({
+      command: 'bash',
+      args: [reviewScriptPath, '--interval', String(options.reviewIntervalSeconds)],
+      cwd: repoRoot,
+      logPath: reviewLogPath,
+    });
+    const cleanupPid = spawnDetachedAgentProcess({
+      command: process.execPath,
+      args: [
+        path.resolve(__filename),
+        'cleanup',
+        '--target',
+        repoRoot,
+        '--watch',
+        '--interval',
+        String(options.cleanupIntervalSeconds),
+        '--idle-minutes',
+        String(options.idleMinutes),
+      ],
+      cwd: repoRoot,
+      logPath: cleanupLogPath,
+    });
+
+    writeAgentsState(repoRoot, {
+      schemaVersion: 1,
+      repoRoot,
+      startedAt: new Date().toISOString(),
+      review: {
+        pid: reviewPid,
+        intervalSeconds: options.reviewIntervalSeconds,
+        script: reviewScriptPath,
+        logPath: reviewLogPath,
+      },
+      cleanup: {
+        pid: cleanupPid,
+        intervalSeconds: options.cleanupIntervalSeconds,
+        idleMinutes: options.idleMinutes,
+        script: path.resolve(__filename),
+        logPath: cleanupLogPath,
+      },
+    });
+
+    console.log(
+      `[${TOOL_NAME}] Started repo agents in ${repoRoot} (review pid=${reviewPid}, cleanup pid=${cleanupPid}).`,
+    );
+    console.log(`[${TOOL_NAME}] Logs: ${reviewLogPath}, ${cleanupLogPath}`);
+    process.exitCode = 0;
+    return;
+  }
+
+  if (options.subcommand === 'stop') {
+    const existingState = readAgentsState(repoRoot);
+    if (!existingState) {
+      console.log(`[${TOOL_NAME}] Repo agents are not running for ${repoRoot}.`);
+      process.exitCode = 0;
+      return;
+    }
+
+    const reviewStop = stopAgentProcessByPid(existingState?.review?.pid, 'review-bot-watch.sh');
+    const cleanupStop = stopAgentProcessByPid(existingState?.cleanup?.pid, `${path.basename(__filename)} cleanup`);
+
+    if (fs.existsSync(statePath)) {
+      fs.unlinkSync(statePath);
+    }
+
+    console.log(
+      `[${TOOL_NAME}] Stopped repo agents in ${repoRoot} (review=${reviewStop.status}, cleanup=${cleanupStop.status}).`,
+    );
+    process.exitCode = 0;
+    return;
+  }
+
+  const existingState = readAgentsState(repoRoot);
+  if (!existingState) {
+    console.log(`[${TOOL_NAME}] Repo agents status: inactive (${repoRoot})`);
+    process.exitCode = 0;
+    return;
+  }
+
+  const reviewPid = Number.parseInt(String(existingState?.review?.pid || ''), 10);
+  const cleanupPid = Number.parseInt(String(existingState?.cleanup?.pid || ''), 10);
+  console.log(
+    `[${TOOL_NAME}] Repo agents status: review=${processAlive(reviewPid) ? 'running' : 'stopped'}(pid=${reviewPid || 0}), cleanup=${processAlive(cleanupPid) ? 'running' : 'stopped'}(pid=${cleanupPid || 0})`,
+  );
+  process.exitCode = 0;
+}
+
 function report(rawArgs) {
   const options = parseReportArgs(rawArgs);
   const subcommand = options.subcommand || 'help';
@@ -3382,6 +4184,13 @@ function setup(rawArgs) {
   if (scanResult.errors === 0 && scanResult.warnings === 0) {
     console.log(`[${TOOL_NAME}] ✅ Setup complete.`);
     console.log(`[${TOOL_NAME}] Copy AI setup prompt with: ${SHORT_TOOL_NAME} copy-prompt`);
+    console.log(
+      `[${TOOL_NAME}] OpenSpec core workflow: /opsx:propose -> /opsx:apply -> /opsx:archive`,
+    );
+    console.log(
+      `[${TOOL_NAME}] Optional expanded OpenSpec profile: openspec config profile <profile-name> && openspec update`,
+    );
+    console.log(`[${TOOL_NAME}] OpenSpec guide: docs/openspec-getting-started.md`);
   }
 
   setExitCodeFromScan(scanResult);
@@ -3475,15 +4284,165 @@ function cleanup(rawArgs) {
   if (!options.keepCleanWorktrees) {
     args.push('--only-dirty-worktrees');
   }
+  if (options.idleMinutes > 0) {
+    args.push('--idle-minutes', String(options.idleMinutes));
+  }
   args.push('--delete-branches');
   if (!options.keepRemote) {
     args.push('--delete-remote-branches');
   }
 
-  const runResult = run('bash', args, { cwd: repoRoot, stdio: 'inherit' });
-  if (runResult.status !== 0) {
-    throw new Error('Cleanup command failed');
+  const runCleanupCycle = () => {
+    const runResult = run('bash', args, { cwd: repoRoot, stdio: 'inherit' });
+    if (runResult.status !== 0) {
+      throw new Error('Cleanup command failed');
+    }
+  };
+
+  if (options.watch) {
+    let cycle = 0;
+    while (true) {
+      cycle += 1;
+      console.log(
+        `[${TOOL_NAME}] Cleanup watch cycle=${cycle} (interval=${options.intervalSeconds}s, idleMinutes=${options.idleMinutes}).`,
+      );
+      runCleanupCycle();
+      if (options.once) {
+        break;
+      }
+      const sleepResult = run('sleep', [String(options.intervalSeconds)], { cwd: repoRoot });
+      if (sleepResult.status !== 0) {
+        throw new Error(`Cleanup watch sleep failed (interval=${options.intervalSeconds}s)`);
+      }
+    }
+    process.exitCode = 0;
+    return;
   }
+
+  runCleanupCycle();
+  process.exitCode = 0;
+}
+
+function finish(rawArgs) {
+  const options = parseFinishArgs(rawArgs);
+  const repoRoot = resolveRepoRoot(options.target);
+  const finishScript = path.join(repoRoot, 'scripts', 'agent-branch-finish.sh');
+
+  if (!fs.existsSync(finishScript)) {
+    throw new Error(`Missing finish script: ${finishScript}. Run '${SHORT_TOOL_NAME} setup' first.`);
+  }
+
+  const worktreeEntries = listAgentWorktrees(repoRoot);
+  const worktreeByBranch = new Map(worktreeEntries.map((entry) => [entry.branch, entry.worktreePath]));
+
+  let candidateBranches = [];
+  if (options.branch) {
+    if (!branchExists(repoRoot, options.branch)) {
+      throw new Error(`Local branch not found: ${options.branch}`);
+    }
+    candidateBranches = [options.branch];
+  } else {
+    candidateBranches = uniquePreserveOrder([
+      ...listLocalAgentBranchesForFinish(repoRoot),
+      ...worktreeEntries.map((entry) => entry.branch),
+    ]);
+  }
+
+  const candidates = [];
+  for (const branch of candidateBranches) {
+    const worktreePath = worktreeByBranch.get(branch) || '';
+    const baseBranch = resolveFinishBaseBranch(repoRoot, branch, options.base);
+    const hasChanges = worktreePath ? worktreeHasLocalChanges(worktreePath) : false;
+    const alreadyMerged = branchMergedIntoBase(repoRoot, branch, baseBranch);
+    if (options.all || options.branch || hasChanges || !alreadyMerged) {
+      candidates.push({
+        branch,
+        baseBranch,
+        worktreePath,
+        hasChanges,
+        alreadyMerged,
+      });
+    }
+  }
+
+  if (candidates.length === 0) {
+    console.log(`[${TOOL_NAME}] No pending agent branches to finish.`);
+    process.exitCode = 0;
+    return;
+  }
+
+  let succeeded = 0;
+  let failed = 0;
+  let autoCommitted = 0;
+
+  for (const candidate of candidates) {
+    const { branch, baseBranch, worktreePath } = candidate;
+    console.log(
+      `[${TOOL_NAME}] Finishing '${branch}' -> '${baseBranch}'${worktreePath ? ` (${worktreePath})` : ''}...`,
+    );
+
+    try {
+      let commitState = { changed: false, committed: false };
+      if (worktreePath) {
+        commitState = autoCommitWorktreeForFinish(repoRoot, worktreePath, branch, options);
+      }
+
+      if (commitState.committed) {
+        autoCommitted += 1;
+        console.log(`[${TOOL_NAME}] Auto-committed '${branch}' before finish.`);
+      } else if (commitState.changed && commitState.dryRun) {
+        console.log(`[${TOOL_NAME}] [dry-run] Would auto-commit pending changes on '${branch}'.`);
+      }
+
+      const finishArgs = [
+        finishScript,
+        '--branch',
+        branch,
+        '--base',
+        baseBranch,
+        '--via-pr',
+        options.waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge',
+        options.cleanup ? '--cleanup' : '--no-cleanup',
+      ];
+      if (options.keepRemote) {
+        finishArgs.push('--keep-remote-branch');
+      }
+
+      if (options.dryRun) {
+        console.log(`[${TOOL_NAME}] [dry-run] Would run: bash ${finishArgs.join(' ')}`);
+        succeeded += 1;
+        continue;
+      }
+
+      const finishResult = run('bash', finishArgs, { cwd: repoRoot, stdio: 'pipe' });
+      if (finishResult.stdout) {
+        process.stdout.write(finishResult.stdout);
+      }
+      if (finishResult.stderr) {
+        process.stderr.write(finishResult.stderr);
+      }
+      if (finishResult.status !== 0) {
+        throw new Error(`agent-branch-finish exited with status ${finishResult.status}`);
+      }
+
+      succeeded += 1;
+    } catch (error) {
+      failed += 1;
+      console.error(`[${TOOL_NAME}] Finish failed for '${branch}': ${error.message}`);
+      if (options.failFast) {
+        break;
+      }
+    }
+  }
+
+  console.log(
+    `[${TOOL_NAME}] Finish summary: total=${candidates.length}, success=${succeeded}, failed=${failed}, autoCommitted=${autoCommitted}`,
+  );
+
+  if (failed > 0) {
+    throw new Error('finish command failed for one or more agent branches');
+  }
+
   process.exitCode = 0;
 }
 
@@ -3815,6 +4774,16 @@ function main() {
     return;
   }
 
+  if (command === 'agents') {
+    agents(rest);
+    return;
+  }
+
+  if (command === 'finish') {
+    finish(rest);
+    return;
+  }
+
   if (command === 'report') {
     report(rest);
     return;