@imdeadpool/guardex 5.0.7 → 5.0.9

package/bin/multiagent-safety.js

@@ -83,6 +83,7 @@ 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',
@@ -98,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'],
@@ -115,6 +127,8 @@ const SUGGESTIBLE_COMMANDS = [
   'setup',
   'init',
   'doctor',
+  'review',
+  'finish',
   'report',
   'copy-prompt',
   'copy-commands',
@@ -135,6 +149,7 @@ 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)'],
@@ -149,8 +164,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.
@@ -172,7 +186,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,18 +200,20 @@ 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
 
-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
 `;
 
@@ -202,10 +221,12 @@ 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...>
 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>"
 gx protect add release staging
@@ -349,7 +370,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)
@@ -359,7 +382,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>`);
   }
 }
 
@@ -502,6 +526,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)) {
@@ -570,6 +633,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',
@@ -844,6 +908,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 = [
@@ -945,12 +1036,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 {
@@ -1081,6 +1186,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;
 }
@@ -1112,6 +1225,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)) {
@@ -1129,10 +1249,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 {
@@ -1197,7 +1322,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') {
@@ -1253,6 +1406,12 @@ function runDoctorInSandbox(options, blocked) {
         };
       }
     }
+
+    postSandboxAutoFinishSummary = autoFinishReadyAgentBranches(blocked.repoRoot, {
+      baseBranch: blocked.branch,
+      dryRun: options.dryRun,
+      excludeBranches: [metadata.branch],
+    });
   }
 
   if (options.json) {
@@ -1264,9 +1423,11 @@ function runDoctorInSandbox(options, blocked) {
             JSON.stringify(
               {
                 ...parsed,
+                sandboxOmxScaffoldSync: omxScaffoldSyncResult,
                 sandboxLockSync: lockSyncResult,
                 sandboxAutoCommit: autoCommitResult,
                 sandboxFinish: finishResult,
+                autoFinish: postSandboxAutoFinishSummary,
               },
               null,
               2,
@@ -1332,11 +1493,42 @@ 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}.`);
+      }
     }
   }
 
   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;
@@ -1363,6 +1555,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(),
@@ -1628,6 +1832,210 @@ 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 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) {
+    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',
+      '--wait-for-merge',
+      '--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) {
@@ -1921,6 +2329,382 @@ function parseCleanupArgs(rawArgs) {
   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) {
@@ -2325,6 +3109,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)));
   }
@@ -2351,6 +3137,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)));
   }
@@ -2404,6 +3192,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,
   ];
@@ -2755,6 +3545,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;
 
@@ -2776,6 +3571,7 @@ function doctor(rawArgs) {
             warnings: scanResult.warnings,
             findings: scanResult.findings,
           },
+          autoFinish: autoFinishSummary,
         },
         null,
         2,
@@ -2787,6 +3583,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 {
@@ -2797,6 +3603,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';
@@ -2955,7 +3782,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.`);
@@ -3065,6 +3907,129 @@ function cleanup(rawArgs) {
   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;
+}
+
 function sync(rawArgs) {
   const options = parseSyncArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);
@@ -3388,6 +4353,16 @@ function main() {
     return;
   }
 
+  if (command === 'review') {
+    review(rest);
+    return;
+  }
+
+  if (command === 'finish') {
+    finish(rest);
+    return;
+  }
+
   if (command === 'report') {
     report(rest);
     return;