@imdeadpool/guardex 7.0.18 → 7.0.19

package/bin/multiagent-safety.js

@@ -109,7 +109,7 @@ const TEMPLATE_FILES = [
   'vscode/guardex-active-agents/README.md',
 ];
 
-const SCRIPT_SHIMS = [
+const LEGACY_WORKFLOW_SHIM_SPECS = [
   { relativePath: 'scripts/agent-branch-start.sh', kind: 'shell', command: ['branch', 'start'] },
   { relativePath: 'scripts/agent-branch-finish.sh', kind: 'shell', command: ['branch', 'finish'] },
   { relativePath: 'scripts/agent-branch-merge.sh', kind: 'shell', command: ['branch', 'merge'] },
@@ -121,21 +121,20 @@ const SCRIPT_SHIMS = [
   { relativePath: 'scripts/openspec/init-change-workspace.sh', kind: 'shell', command: ['internal', 'run-shell', 'changeInit'] },
 ];
 
+const LEGACY_WORKFLOW_SHIMS = LEGACY_WORKFLOW_SHIM_SPECS.map((entry) => entry.relativePath);
+
+const MANAGED_TEMPLATE_DESTINATIONS = TEMPLATE_FILES.map((entry) => toDestinationPath(entry));
+const MANAGED_TEMPLATE_SCRIPT_FILES = MANAGED_TEMPLATE_DESTINATIONS.filter((entry) =>
+  entry.startsWith('scripts/'),
+);
+
 const LEGACY_MANAGED_REPO_FILES = [
-  'scripts/agent-branch-start.sh',
-  'scripts/agent-branch-finish.sh',
-  'scripts/agent-branch-merge.sh',
+  ...LEGACY_WORKFLOW_SHIMS,
   'scripts/agent-session-state.js',
-  'scripts/codex-agent.sh',
   'scripts/guardex-docker-loader.sh',
   'scripts/install-vscode-active-agents-extension.js',
-  'scripts/review-bot-watch.sh',
-  'scripts/agent-worktree-prune.sh',
-  'scripts/agent-file-locks.py',
   'scripts/guardex-env.sh',
   'scripts/install-agent-git-hooks.sh',
-  'scripts/openspec/init-plan-workspace.sh',
-  'scripts/openspec/init-change-workspace.sh',
   '.githooks/pre-commit',
   '.githooks/pre-push',
   '.githooks/post-merge',
@@ -145,9 +144,8 @@ const LEGACY_MANAGED_REPO_FILES = [
   '.claude/commands/gitguardex.md',
 ];
 
-const REQUIRED_WORKFLOW_FILES = [
-  ...TEMPLATE_FILES.map((entry) => toDestinationPath(entry)),
-  ...SCRIPT_SHIMS.map((entry) => entry.relativePath),
+const REQUIRED_MANAGED_REPO_FILES = [
+  ...MANAGED_TEMPLATE_DESTINATIONS,
   ...HOOK_NAMES.map((entry) => path.posix.join('.githooks', entry)),
   '.omx/state/agent-file-locks.json',
 ];
@@ -205,22 +203,13 @@ const USER_LEVEL_SKILL_ASSETS = [
 ];
 
 const EXECUTABLE_RELATIVE_PATHS = new Set([
-  'scripts/agent-session-state.js',
-  'scripts/guardex-docker-loader.sh',
-  'scripts/install-vscode-active-agents-extension.js',
-  ...SCRIPT_SHIMS.map((entry) => entry.relativePath),
+  ...MANAGED_TEMPLATE_SCRIPT_FILES,
   ...HOOK_NAMES.map((entry) => path.posix.join('.githooks', entry)),
 ]);
 
 const CRITICAL_GUARDRAIL_PATHS = new Set([
   'AGENTS.md',
   ...HOOK_NAMES.map((entry) => path.posix.join('.githooks', entry)),
-  'scripts/agent-branch-start.sh',
-  'scripts/agent-branch-finish.sh',
-  'scripts/agent-branch-merge.sh',
-  'scripts/agent-worktree-prune.sh',
-  'scripts/codex-agent.sh',
-  'scripts/agent-file-locks.py',
   'scripts/guardex-env.sh',
 ]);
 
@@ -239,9 +228,10 @@ const AGENT_WORKTREE_RELATIVE_DIRS = [
 const MANAGED_GITIGNORE_PATHS = [
   '.omx/',
   '.omc/',
-  'scripts/*',
-  'scripts/agent-branch-start.sh',
-  'scripts/agent-file-locks.py',
+  'scripts/agent-session-state.js',
+  'scripts/guardex-docker-loader.sh',
+  'scripts/guardex-env.sh',
+  'scripts/install-vscode-active-agents-extension.js',
   '.githooks',
   'oh-my-codex/',
   LOCK_FILE_RELATIVE,
@@ -260,6 +250,13 @@ const OMX_SCAFFOLD_FILES = new Map([
   ['.omx/notepad.md', '\n\n## WORKING MEMORY\n'],
   ['.omx/project-memory.json', '{}\n'],
 ]);
+const TARGETED_FORCEABLE_MANAGED_PATHS = new Set([
+  'AGENTS.md',
+  '.gitignore',
+  ...Array.from(OMX_SCAFFOLD_FILES.keys()),
+  ...REQUIRED_MANAGED_REPO_FILES,
+  ...LEGACY_WORKFLOW_SHIMS,
+]);
 const COMMAND_TYPO_ALIASES = new Map([
   ['relaese', 'release'],
   ['realaese', 'release'],
@@ -311,7 +308,7 @@ const CLI_COMMAND_DESCRIPTIONS = [
   ['locks', 'CLI-owned file lock surface (claim/allow-delete/release/status/validate)'],
   ['worktree', 'CLI-owned worktree cleanup surface (prune)'],
   ['hook', 'Hook dispatch/install surface used by managed shims'],
-  ['migrate', 'Convert legacy repo-local installs to the new shim-based CLI-owned surface'],
+  ['migrate', 'Convert legacy repo-local installs to the zero-copy CLI-owned surface'],
   ['install-agent-skills', 'Install Guardex Codex/Claude skills into the user home'],
   ['protect', 'Manage protected branches (list/add/remove/set/reset)'],
   ['merge', 'Create/reuse an integration lane and merge overlapping agent branches'],
@@ -680,6 +677,27 @@ function runPackageAsset(assetKey, rawArgs, options = {}) {
   });
 }
 
+function repoLocalLegacyScriptPath(repoRoot, relativePath) {
+  const assetPath = path.join(repoRoot, relativePath);
+  return fs.existsSync(assetPath) ? assetPath : null;
+}
+
+function runReviewBotCommand(repoRoot, rawArgs, options = {}) {
+  const legacyScript = repoLocalLegacyScriptPath(repoRoot, 'scripts/review-bot-watch.sh');
+  if (legacyScript) {
+    return run('bash', [legacyScript, ...rawArgs], {
+      cwd: repoRoot,
+      stdio: options.stdio || 'pipe',
+      timeout: options.timeout,
+      env: packageAssetEnv(options.env),
+    });
+  }
+  return runPackageAsset('reviewBot', rawArgs, {
+    ...options,
+    cwd: repoRoot,
+  });
+}
+
 function invokePackageAsset(assetKey, rawArgs, options = {}) {
   const result = runPackageAsset(assetKey, rawArgs, options);
   if (result.stdout) process.stdout.write(result.stdout);
@@ -1028,6 +1046,13 @@ function renderPythonDispatchShim(commandParts) {
   );
 }
 
+function managedForceConflictMessage(relativePath) {
+  return (
+    `Refusing to overwrite existing file without --force: ${relativePath}\n` +
+    `Use '--force ${relativePath}' to rewrite only this managed file, or '--force' to rewrite all managed files.`
+  );
+}
+
 function renderManagedFile(repoRoot, relativePath, content, options = {}) {
   const destinationPath = path.join(repoRoot, relativePath);
   const destinationExists = fs.existsSync(destinationPath);
@@ -1041,7 +1066,7 @@ function renderManagedFile(repoRoot, relativePath, content, options = {}) {
       return { status: 'unchanged', file: relativePath };
     }
     if (!force && !isCriticalGuardrailPath(relativePath)) {
-      throw new Error(`Refusing to overwrite existing file without --force: ${relativePath}`);
+      throw new Error(managedForceConflictMessage(relativePath));
     }
   }
 
@@ -1089,9 +1114,7 @@ function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
       return { status: 'unchanged', file: destinationRelativePath };
     }
     if (!force && !isCriticalGuardrailPath(destinationRelativePath)) {
-      throw new Error(
-        `Refusing to overwrite existing file without --force: ${destinationRelativePath}`,
-      );
+      throw new Error(managedForceConflictMessage(destinationRelativePath));
     }
   }
 
@@ -1142,6 +1165,22 @@ function ensureTemplateFilePresent(repoRoot, relativeTemplatePath, dryRun) {
   return { status: 'created', file: destinationRelativePath };
 }
 
+function ensureTargetedLegacyWorkflowShims(repoRoot, options) {
+  const targetedPaths = Array.isArray(options.forceManagedPaths) ? options.forceManagedPaths : [];
+  if (targetedPaths.length === 0) {
+    return [];
+  }
+
+  const operations = [];
+  for (const shim of LEGACY_WORKFLOW_SHIM_SPECS) {
+    if (!shouldForceManagedPath(options, shim.relativePath)) {
+      continue;
+    }
+    operations.push(ensureGeneratedScriptShim(repoRoot, shim, { dryRun: options.dryRun, force: true }));
+  }
+  return operations;
+}
+
 function lockFilePath(repoRoot) {
   return path.join(repoRoot, LOCK_FILE_RELATIVE);
 }
@@ -1448,8 +1487,65 @@ function requireValue(rawArgs, index, flagName) {
   return value;
 }
 
+function normalizeManagedForcePath(rawPath) {
+  if (typeof rawPath !== 'string') {
+    return null;
+  }
+  const normalized = path.posix.normalize(rawPath.replace(/\\/g, '/'));
+  if (!normalized || normalized === '.' || normalized.startsWith('../') || path.posix.isAbsolute(normalized)) {
+    return null;
+  }
+  return normalized.startsWith('./') ? normalized.slice(2) : normalized;
+}
+
+function collectForceManagedPaths(rawArgs, startIndex) {
+  const forceManagedPaths = [];
+  let nextIndex = startIndex;
+
+  while (nextIndex + 1 < rawArgs.length) {
+    const candidate = rawArgs[nextIndex + 1];
+    if (!candidate || candidate.startsWith('-')) {
+      break;
+    }
+    const normalized = normalizeManagedForcePath(candidate);
+    if (!normalized || !TARGETED_FORCEABLE_MANAGED_PATHS.has(normalized)) {
+      throw new Error(`Unknown managed path after --force: ${candidate}`);
+    }
+    forceManagedPaths.push(normalized);
+    nextIndex += 1;
+  }
+
+  return { forceManagedPaths, nextIndex };
+}
+
+function appendForceArgs(args, options) {
+  if (!options.force) {
+    return;
+  }
+  args.push('--force');
+  for (const managedPath of options.forceManagedPaths || []) {
+    args.push(managedPath);
+  }
+}
+
+function shouldForceManagedPath(options, relativePath) {
+  if (!options.force) {
+    return false;
+  }
+  const targetedPaths = Array.isArray(options.forceManagedPaths) ? options.forceManagedPaths : [];
+  if (targetedPaths.length === 0) {
+    return true;
+  }
+  const normalized = normalizeManagedForcePath(relativePath);
+  return normalized !== null && targetedPaths.includes(normalized);
+}
+
 function parseCommonArgs(rawArgs, defaults) {
   const options = { ...defaults };
+  const supportsForce = Object.prototype.hasOwnProperty.call(options, 'force');
+  if (supportsForce && !Array.isArray(options.forceManagedPaths)) {
+    options.forceManagedPaths = [];
+  }
 
   for (let index = 0; index < rawArgs.length; index += 1) {
     const arg = rawArgs[index];
@@ -1471,7 +1567,17 @@ function parseCommonArgs(rawArgs, defaults) {
       continue;
     }
     if (arg === '--force') {
+      if (!supportsForce) {
+        throw new Error(`Unknown option: ${arg}`);
+      }
       options.force = true;
+      const parsed = collectForceManagedPaths(rawArgs, index);
+      if (parsed.forceManagedPaths.length > 0) {
+        options.forceManagedPaths = Array.from(
+          new Set([...(options.forceManagedPaths || []), ...parsed.forceManagedPaths]),
+        );
+      }
+      index = parsed.nextIndex;
       continue;
     }
     if (arg === '--keep-stale-locks') {
@@ -1589,6 +1695,7 @@ function parseSetupArgs(rawArgs, defaults) {
 function parseDoctorArgs(rawArgs) {
   const doctorDefaults = {
     target: process.cwd(),
+    force: false,
     dropStaleLocks: true,
     skipAgents: false,
     skipPackageJson: false,
@@ -1670,7 +1777,6 @@ function ensureParentWorkspaceView(repoRoot, dryRun) {
 function hasGuardexBootstrapFiles(repoRoot) {
   const required = [
     'AGENTS.md',
-    'scripts/agent-branch-start.sh',
     '.githooks/pre-commit',
     '.githooks/pre-push',
     LOCK_FILE_RELATIVE,
@@ -1738,6 +1844,7 @@ function runSetupBootstrapInternal(options) {
     target: installPayload.repoRoot,
     dryRun: options.dryRun,
     force: options.force,
+    forceManagedPaths: options.forceManagedPaths,
     dropStaleLocks: true,
     skipAgents: options.skipAgents,
     skipPackageJson: options.skipPackageJson,
@@ -1775,7 +1882,7 @@ function resolveSandboxTarget(repoRoot, worktreePath, targetPath) {
 
 function buildSandboxSetupArgs(options, sandboxTarget) {
   const args = ['setup', '--target', sandboxTarget, '--no-global-install', '--no-recursive'];
-  if (options.force) args.push('--force');
+  appendForceArgs(args, options);
   if (options.skipAgents) args.push('--skip-agents');
   if (options.skipPackageJson) args.push('--skip-package-json');
   if (options.skipGitignore) args.push('--no-gitignore');
@@ -1786,7 +1893,7 @@ function buildSandboxSetupArgs(options, sandboxTarget) {
 function buildSandboxDoctorArgs(options, sandboxTarget) {
   const args = ['doctor', '--target', sandboxTarget];
   if (options.dryRun) args.push('--dry-run');
-  if (options.force) args.push('--force');
+  appendForceArgs(args, options);
   if (options.skipAgents) args.push('--skip-agents');
   if (options.skipPackageJson) args.push('--skip-package-json');
   if (options.skipGitignore) args.push('--no-gitignore');
@@ -1934,11 +2041,6 @@ function startProtectedBaseSandbox(blocked, { taskName, sandboxSuffix }) {
     return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
   }
 
-  const startScript = path.join(blocked.repoRoot, 'scripts', 'agent-branch-start.sh');
-  if (!fs.existsSync(startScript)) {
-    return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
-  }
-
   const startResult = runPackageAsset('branchStart', [
     '--task',
     taskName,
@@ -2088,7 +2190,7 @@ function collectWorktreeDirtyPaths(worktreePath) {
 }
 
 function collectDoctorForceAddPaths(worktreePath) {
-  return REQUIRED_WORKFLOW_FILES
+  return REQUIRED_MANAGED_REPO_FILES
     .filter((relativePath) => relativePath.startsWith('scripts/') || relativePath.startsWith('.githooks/'))
     .filter((relativePath) => fs.existsSync(path.join(worktreePath, relativePath)));
 }
@@ -2124,11 +2226,10 @@ function stripDoctorSandboxLocks(rawContent, branchName) {
 }
 
 function claimDoctorChangedLocks(metadata) {
-  const lockScript = path.join(metadata.worktreePath, 'scripts', 'agent-file-locks.py');
-  if (!fs.existsSync(lockScript) || !metadata.branch) {
+  if (!metadata.branch) {
     return {
       status: 'skipped',
-      note: 'lock helper unavailable in sandbox',
+      note: 'missing sandbox branch metadata',
       changedCount: 0,
       deletedCount: 0,
     };
@@ -2247,13 +2348,6 @@ function doctorFinishFlowIsPending(output) {
 }
 
 function finishDoctorSandboxBranch(blocked, metadata, options = {}) {
-  const finishScript = path.join(metadata.worktreePath, 'scripts', 'agent-branch-finish.sh');
-  if (!fs.existsSync(finishScript)) {
-    return {
-      status: 'skipped',
-      note: `${path.relative(metadata.worktreePath, finishScript)} missing in sandbox`,
-    };
-  }
   if (!hasOriginRemote(blocked.repoRoot)) {
     return {
       status: 'skipped',
@@ -2290,9 +2384,9 @@ function finishDoctorSandboxBranch(blocked, metadata, options = {}) {
   const finishTimeoutMs = Math.max(180_000, (waitTimeoutSeconds + 60) * 1000);
   const waitForMergeArg = options.waitForMerge === false ? '--no-wait-for-merge' : '--wait-for-merge';
 
-  const finishResult = run(
-    'bash',
-    [finishScript, '--branch', metadata.branch, '--base', blocked.branch, '--via-pr', waitForMergeArg, '--cleanup'],
+  const finishResult = runPackageAsset(
+    'branchFinish',
+    ['--branch', metadata.branch, '--base', blocked.branch, '--via-pr', waitForMergeArg, '--cleanup'],
     { cwd: metadata.worktreePath, timeout: finishTimeoutMs },
   );
   if (isSpawnFailure(finishResult)) {
@@ -2363,7 +2457,7 @@ function mergeDoctorSandboxRepairsBackToProtectedBase(options, blocked, metadata
     ...(autoCommitResult.stagedFiles || []),
     ...OMX_SCAFFOLD_DIRECTORIES,
     ...Array.from(OMX_SCAFFOLD_FILES.keys()),
-    ...REQUIRED_WORKFLOW_FILES,
+    ...REQUIRED_MANAGED_REPO_FILES,
     'bin',
     'package.json',
     '.gitignore',
@@ -3387,13 +3481,6 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
     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;
@@ -4212,11 +4299,6 @@ function gitOutputLines(worktreePath, args) {
 }
 
 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']),
@@ -5171,13 +5253,24 @@ function runInstallInternal(options) {
   operations.push(...ensureOmxScaffold(repoRoot, Boolean(options.dryRun)));
 
   for (const templateFile of TEMPLATE_FILES) {
-    operations.push(copyTemplateFile(repoRoot, templateFile, Boolean(options.force), Boolean(options.dryRun)));
-  }
-  for (const shim of SCRIPT_SHIMS) {
-    operations.push(ensureGeneratedScriptShim(repoRoot, shim, options));
+    operations.push(
+      copyTemplateFile(
+        repoRoot,
+        templateFile,
+        shouldForceManagedPath(options, toDestinationPath(templateFile)),
+        Boolean(options.dryRun),
+      ),
+    );
   }
+  operations.push(...ensureTargetedLegacyWorkflowShims(repoRoot, options));
   for (const hookName of HOOK_NAMES) {
-    operations.push(ensureHookShim(repoRoot, hookName, options));
+    const hookRelativePath = path.posix.join('.githooks', hookName);
+    operations.push(
+      ensureHookShim(repoRoot, hookName, {
+        dryRun: options.dryRun,
+        force: shouldForceManagedPath(options, hookRelativePath),
+      }),
+    );
   }
 
   operations.push(ensureLockRegistry(repoRoot, Boolean(options.dryRun)));
@@ -5218,13 +5311,21 @@ function runFixInternal(options) {
   operations.push(...ensureOmxScaffold(repoRoot, Boolean(options.dryRun)));
 
   for (const templateFile of TEMPLATE_FILES) {
+    if (shouldForceManagedPath(options, toDestinationPath(templateFile))) {
+      operations.push(copyTemplateFile(repoRoot, templateFile, true, Boolean(options.dryRun)));
+      continue;
+    }
     operations.push(ensureTemplateFilePresent(repoRoot, templateFile, Boolean(options.dryRun)));
   }
-  for (const shim of SCRIPT_SHIMS) {
-    operations.push(ensureGeneratedScriptShim(repoRoot, shim, options));
-  }
+  operations.push(...ensureTargetedLegacyWorkflowShims(repoRoot, options));
   for (const hookName of HOOK_NAMES) {
-    operations.push(ensureHookShim(repoRoot, hookName, options));
+    const hookRelativePath = path.posix.join('.githooks', hookName);
+    operations.push(
+      ensureHookShim(repoRoot, hookName, {
+        dryRun: options.dryRun,
+        force: shouldForceManagedPath(options, hookRelativePath),
+      }),
+    );
   }
 
   operations.push(ensureLockRegistry(repoRoot, Boolean(options.dryRun)));
@@ -5284,7 +5385,7 @@ function runScanInternal(options) {
   const requiredPaths = [
     ...OMX_SCAFFOLD_DIRECTORIES,
     ...Array.from(OMX_SCAFFOLD_FILES.keys()),
-    ...REQUIRED_WORKFLOW_FILES,
+    ...REQUIRED_MANAGED_REPO_FILES,
   ];
 
   for (const relativePath of requiredPaths) {
@@ -5294,7 +5395,7 @@ function runScanInternal(options) {
         level: 'error',
         code: 'missing-managed-file',
         path: relativePath,
-        message: `Missing managed workflow file: ${relativePath}`,
+        message: `Missing managed repo file: ${relativePath}`,
       });
     }
   }
@@ -5738,6 +5839,7 @@ function doctor(rawArgs) {
         '--single-repo',
         '--target',
         repoPath,
+        ...(options.force ? ['--force', ...(options.forceManagedPaths || [])] : []),
         ...(options.dropStaleLocks ? [] : ['--keep-stale-locks']),
         ...(options.skipAgents ? ['--skip-agents'] : []),
         ...(options.skipPackageJson ? ['--skip-package-json'] : []),
@@ -5902,15 +6004,7 @@ function doctor(rawArgs) {
 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 });
+  const result = runReviewBotCommand(repoRoot, options.passthroughArgs);
   if (isSpawnFailure(result)) {
     throw result.error;
   }
@@ -6049,24 +6143,9 @@ function spawnDetachedAgentProcess({ command, args, cwd, logPath }) {
 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);
@@ -6091,8 +6170,17 @@ function agents(rawArgs) {
 
     if (!reviewRunning) {
       reviewPid = spawnDetachedAgentProcess({
-        command: 'bash',
-        args: [reviewScriptPath, '--interval', String(options.reviewIntervalSeconds)],
+        command: process.execPath,
+        args: [
+          path.resolve(__filename),
+          'internal',
+          'run-shell',
+          'reviewBot',
+          '--target',
+          repoRoot,
+          '--interval',
+          String(options.reviewIntervalSeconds),
+        ],
         cwd: repoRoot,
         logPath: reviewLogPath,
       });
@@ -6143,7 +6231,7 @@ function agents(rawArgs) {
       review: {
         pid: reviewPid,
         intervalSeconds: reviewIntervalSeconds,
-        script: reviewScriptPath,
+        script: path.resolve(__filename),
         logPath: reviewLogPath,
       },
       cleanup: {
@@ -6174,7 +6262,7 @@ function agents(rawArgs) {
       return;
     }
 
-    const reviewStop = stopAgentProcessByPid(existingState?.review?.pid, 'review-bot-watch.sh');
+    const reviewStop = stopAgentProcessByPid(existingState?.review?.pid, 'internal run-shell reviewBot');
     const cleanupStop = stopAgentProcessByPid(existingState?.cleanup?.pid, `${path.basename(__filename)} cleanup`);
 
     if (fs.existsSync(statePath)) {
@@ -6870,7 +6958,7 @@ function doctorAudit(rawArgs) {
     ok('git core.hooksPath is .githooks');
   }
 
-  for (const relativePath of REQUIRED_WORKFLOW_FILES) {
+  for (const relativePath of REQUIRED_MANAGED_REPO_FILES) {
     const absolutePath = path.join(repoRoot, relativePath);
     if (!fs.existsSync(absolutePath)) {
       fail(`missing ${relativePath}`);
@@ -7084,7 +7172,10 @@ function internal(rawArgs) {
     throw new Error(`Unknown internal command: ${subcommand || '(missing)'}`);
   }
   const { target, passthrough } = extractTargetedArgs(rest);
-  const result = runPackageAsset(assetKey, passthrough, { cwd: resolveRepoRoot(target) });
+  const repoRoot = resolveRepoRoot(target);
+  const result = assetKey === 'reviewBot'
+    ? runReviewBotCommand(repoRoot, passthrough)
+    : runPackageAsset(assetKey, passthrough, { cwd: repoRoot });
   if (result.stdout) process.stdout.write(result.stdout);
   if (result.stderr) process.stderr.write(result.stderr);
   process.exitCode = result.status;
@@ -7149,7 +7240,7 @@ function migrate(rawArgs) {
   }
 
   const removableLegacyFiles = LEGACY_MANAGED_REPO_FILES.filter(
-    (relativePath) => !REQUIRED_WORKFLOW_FILES.includes(relativePath),
+    (relativePath) => !REQUIRED_MANAGED_REPO_FILES.includes(relativePath),
   );
   const removalOps = removableLegacyFiles.map((relativePath) => removeLegacyManagedRepoFile(repoRoot, relativePath, { dryRun, force }));
   removalOps.push(removeLegacyPackageScripts(repoRoot, dryRun));
@@ -7160,10 +7251,6 @@ function migrate(rawArgs) {
 function cleanup(rawArgs) {
   const options = parseCleanupArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);
-  const pruneScript = path.join(repoRoot, 'scripts', 'agent-worktree-prune.sh');
-  if (!fs.existsSync(pruneScript)) {
-    throw new Error(`Missing cleanup script: ${pruneScript}. Run '${SHORT_TOOL_NAME} setup' first.`);
-  }
 
   const args = [];
   if (options.base) {
@@ -7229,11 +7316,6 @@ function cleanup(rawArgs) {
 function merge(rawArgs) {
   const options = parseMergeArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);
-  const mergeScript = path.join(repoRoot, 'scripts', 'agent-branch-merge.sh');
-
-  if (!fs.existsSync(mergeScript)) {
-    throw new Error(`Missing merge script: ${mergeScript}. Run '${SHORT_TOOL_NAME} setup' first.`);
-  }
 
   const args = [];
   if (options.base) {
@@ -7269,11 +7351,6 @@ function merge(rawArgs) {
 function finish(rawArgs, defaults = {}) {
   const options = parseFinishArgs(rawArgs, defaults);
   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]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.18",
+  "version": "7.0.19",
   "description": "Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman.",
   "license": "MIT",
   "preferGlobal": true,

package/templates/AGENTS.multiagent-safety.md

@@ -7,6 +7,9 @@
 `GUARDEX_ON=0` disables Guardex for that repo.
 `GUARDEX_ON=1` explicitly enables Guardex for that repo again.
 
+**Task-size routing.** Small tasks stay in direct caveman-only mode. For typos, single-file tweaks, one-liners, version bumps, or similarly bounded asks, solve directly and do not escalate into heavy OMX orchestration just because a keyword appears. Treat `quick:`, `simple:`, `tiny:`, `minor:`, `small:`, `just:`, and `only:` as explicit lightweight escape hatches.
+Promote to OMX orchestration only when the task is medium/large: multi-file behavior changes, API/schema work, refactors, migrations, architecture, cross-cutting scope, or long prompts. Heavy OMX modes (`ralph`, `autopilot`, `team`, `ultrawork`, `swarm`, `ralplan`) are for that larger scope. If the task grows while working, upgrade then.
+
 **Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `gx branch start "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout <branch>` on a primary working tree (including nested repos); use `git worktree add` instead. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions - bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
 For every new task, including follow-up work in the same chat/session, if an assigned agent sub-branch/worktree is already open, continue in that sub-branch instead of creating a fresh lane unless the user explicitly redirects scope.
 Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree.

package/templates/codex/skills/gitguardex/SKILL.md

@@ -8,4 +8,4 @@ Use when repo safety may be broken.
 `gx status` -> `gx doctor` -> `gx status --strict`
 
 Bootstrap: `gx setup`
-Ops: `bash scripts/codex-agent.sh "<task>" "<agent>"`, `gx finish --all`, `gx cleanup`
+Ops: `gx branch start "<task>" "<agent>"`, `gx locks claim --branch "<agent-branch>" <file...>`, `gx branch finish --branch "<agent-branch>" --base <base> --via-pr --wait-for-merge --cleanup`, `gx finish --all`, `gx cleanup`