@imdeadpool/guardex 5.0.0 → 5.0.2

package/README.md

@@ -50,26 +50,29 @@ Related tools:
 
 - [oh-my-codex (OMX)](https://github.com/Yeachan-Heo/oh-my-codex)
 - [OpenSpec](https://github.com/Fission-AI/OpenSpec)
+- [codex-account-switcher-cli](https://github.com/recodeecom/codex-account-switcher-cli)
 
 ## Fast setup (recommended)
 
 ```sh
 # inside your repo
 gx setup
+# alias:
+gx init
 ```
 
 That one command runs:
 
-1. detects whether OMX/OpenSpec are already globally installed,
+1. detects whether OMX/OpenSpec/codex-auth are already globally installed,
 2. asks strict Y/N approval only if something is missing,
 3. installs guardrail scripts/hooks,
 4. repairs common safety problems,
 5. installs local Codex + Claude gx helper skill files if missing,
 6. scans and reports final status.
 
-## Setup screenshot
+## Setup behavior screenshot
 
-![gx setup success screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/setup-success.svg)
+![gx status/setup behavior screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/setup-success.svg)
 
 ## Status logs screenshot
 
@@ -217,10 +220,11 @@ Use this exact checklist to setup multi-agent safety in this repository for Code
 
 2) Bootstrap safety in this repo:
    gx setup
+   # alias: gx init
 
-   - Setup detects global OMX/OpenSpec first.
+   - Setup detects global OMX/OpenSpec/codex-auth first.
    - If one is missing and setup asks for approval, reply explicitly:
-     - y = run: npm i -g oh-my-codex @fission-ai/openspec (missing ones only)
+     - y = run: npm i -g oh-my-codex @fission-ai/openspec @imdeadpool/codex-account-switcher (missing ones only)
      - n = skip global installs
 
 3) If setup reports warnings/errors, repair + re-check:
@@ -231,6 +235,13 @@ Use this exact checklist to setup multi-agent safety in this repository for Code
    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)"
+   - For every new user message/task, repeat the same cycle:
+     start isolated agent branch/worktree -> claim file locks -> implement/verify ->
+     finish via PR/merge cleanup with scripts/agent-branch-finish.sh.
+   - `scripts/codex-agent.sh` now auto-runs this finish flow after Codex exits:
+     auto-commit changed files -> push/create PR -> merge attempt -> keep branch/worktree for follow-up.
+   - Remove merged branches when you are done reviewing:
+     gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
 
 5) Optional: create OpenSpec planning workspace:
    bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
@@ -250,8 +261,9 @@ Use this exact checklist to setup multi-agent safety in this repository for Code
 
 ```sh
 gx status [--target <path>] [--json]
-gx setup [--target <path>] [--dry-run] [--yes-global-install|--no-global-install] [--no-gitignore]
-gx doctor [--target <path>] [--dry-run] [--json] [--keep-stale-locks] [--no-gitignore]
+gx setup [--target <path>] [--dry-run] [--yes-global-install|--no-global-install] [--no-gitignore] [--allow-protected-base-write]
+gx init [--target <path>] [--dry-run] [--yes-global-install|--no-global-install] [--no-gitignore] [--allow-protected-base-write]
+gx doctor [--target <path>] [--dry-run] [--json] [--keep-stale-locks] [--no-gitignore] [--allow-protected-base-write]
 gx copy-prompt
 gx copy-commands
 gx protect list [--target <path>]
@@ -261,25 +273,37 @@ gx protect set <branch...> [--target <path>]
 gx protect reset [--target <path>]
 gx sync --check [--target <path>] [--base <branch>] [--json]
 gx sync [--target <path>] [--base <branch>] [--strategy rebase|merge] [--ff-only]
+gx cleanup [--target <path>] [--base <branch>] [--branch <agent/...>] [--dry-run] [--force-dirty] [--keep-remote]
 gx report scorecard [--target <path>] [--repo github.com/<owner>/<repo>] [--scorecard-json <file>] [--output-dir <path>] [--date YYYY-MM-DD]
-bash scripts/agent-worktree-prune.sh --base dev   # manual stale worktree cleanup
+bash scripts/agent-worktree-prune.sh   # prune temporary worktrees only (keeps merged agent branches by default)
+bash scripts/agent-worktree-prune.sh --delete-branches --delete-remote-branches   # full merged-branch cleanup
+bash scripts/agent-worktree-prune.sh --force-dirty --delete-branches   # force-remove dirty merged worktrees too
 bash scripts/openspec/init-plan-workspace.sh <plan-slug>   # optional OpenSpec plan scaffold
 ```
 
 No command defaults to `gx status` (non-mutating health/status view).
-`gx status` reports CLI/runtime info, global OMX/OpenSpec service status, and repo safety service state.
+`gx status` reports CLI/runtime info, global OMX/OpenSpec/codex-auth service status, and repo safety service state.
+`gx init` is an alias of `gx setup`.
 When run in an interactive terminal, default `GuardeX` checks npm for a newer version first
 and asks `[y/N]` whether to update immediately (default is `N`).
 
-- Interactive setup: prompts for Y/N approval before global OMX/OpenSpec install.
+- Interactive setup: prompts for Y/N approval before global OMX/OpenSpec/codex-auth install.
 - Interactive prompt is strict (`[y/n]`) and waits for explicit answer.
 - Non-interactive setup: skips global installs by default; use `--yes-global-install` to force.
+- In already-initialized repos, `setup` / `install` / `fix` block writes on protected `main` by default; start an agent branch first. Use `--allow-protected-base-write` only for emergency in-place maintenance.
+- `gx doctor` on protected `main` auto-starts an isolated `agent/gx/...-gx-doctor` worktree branch and applies repairs there.
+- `gx setup` and `gx doctor` always refresh `.githooks/pre-commit` from templates, so Codex sub-branch enforcement stays repaired.
+- `scripts/codex-agent.sh` now auto-runs finish automation after a Codex session when `origin` exists:
+  auto-commit changed files, run PR/merge automation, and keep merged agent branches/worktrees by default.
+  It also auto-syncs each sandbox branch against the latest base branch before task execution.
+  If conflicts remain, it keeps the sandbox and prompts for a conflict-resolution review pass.
+- use `gx cleanup` (or `gx cleanup --branch <agent/...>`) to remove merged branches/worktrees when done.
 
 ## Advanced commands
 
 ```sh
-gx install [--target <path>] [--force] [--skip-agents] [--skip-package-json] [--no-gitignore] [--dry-run]
-gx fix [--target <path>] [--dry-run] [--keep-stale-locks] [--no-gitignore]
+gx install [--target <path>] [--force] [--skip-agents] [--skip-package-json] [--no-gitignore] [--dry-run] [--allow-protected-base-write]
+gx fix [--target <path>] [--dry-run] [--keep-stale-locks] [--no-gitignore] [--allow-protected-base-write]
 gx scan [--target <path>] [--json]
 gx report help
 ```
@@ -350,7 +374,7 @@ multiagent.protectedBranches
 ## What is protected
 
 - direct commits to protected branches (defaults: `dev`, `main`, `master`; configurable via `gx protect ...`)
-- protected-branch commits are blocked regardless of commit client (including VS Code Source Control)
+- protected-branch commits are blocked by default for all clients; Codex sessions only may commit protected branches when staged files are strictly `AGENTS.md` and/or `.gitignore`
 - Codex-session commits on non-`agent/*` branches are blocked by default (`multiagent.codexRequireAgentBranch=true`)
 - Codex commits attempted on protected branches trigger `guardex-preedit-guard` and require starting work via `scripts/codex-agent.sh`
 - overlapping file ownership between agents

package/bin/multiagent-safety.js

@@ -10,7 +10,11 @@ const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
 const TOOL_NAME = 'guardex';
 const SHORT_TOOL_NAME = 'gx';
 const LEGACY_NAMES = ['musafety', 'multiagent-safety'];
-const GLOBAL_TOOLCHAIN_PACKAGES = ['oh-my-codex', '@fission-ai/openspec'];
+const GLOBAL_TOOLCHAIN_PACKAGES = [
+  'oh-my-codex',
+  '@fission-ai/openspec',
+  '@imdeadpool/codex-account-switcher',
+];
 const MAINTAINER_RELEASE_REPO = path.resolve(
   process.env.MUSAFETY_RELEASE_REPO || '/tmp/multiagent-safety',
 );
@@ -54,6 +58,8 @@ const CRITICAL_GUARDRAIL_PATHS = new Set([
   '.githooks/pre-commit',
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
+  'scripts/agent-worktree-prune.sh',
+  'scripts/codex-agent.sh',
   'scripts/agent-file-locks.py',
 ]);
 
@@ -80,20 +86,24 @@ const COMMAND_TYPO_ALIASES = new Map([
   ['realaese', 'release'],
   ['relase', 'release'],
   ['setpu', 'setup'],
+  ['inti', 'init'],
   ['intsall', 'install'],
   ['docter', 'doctor'],
   ['doctro', 'doctor'],
+  ['cleunup', 'cleanup'],
   ['scna', 'scan'],
 ]);
 const SUGGESTIBLE_COMMANDS = [
   'status',
   'setup',
+  'init',
   'doctor',
   'report',
   'copy-prompt',
   'copy-commands',
   'protect',
   'sync',
+  'cleanup',
   'release',
   'install',
   'fix',
@@ -105,12 +115,14 @@ const SUGGESTIBLE_COMMANDS = [
 const CLI_COMMAND_DESCRIPTIONS = [
   ['status', 'Show GuardeX CLI + service health without modifying files'],
   ['setup', 'Install + repair guardrails in a git repo (supports --no-gitignore)'],
+  ['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)'],
   ['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)'],
   ['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'],
@@ -127,10 +139,11 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
 
 2) Bootstrap safety in this repo:
    gx setup
+   # alias: gx init
 
-   - Setup detects global OMX/OpenSpec first.
+   - Setup detects global OMX/OpenSpec/codex-auth first.
    - If one is missing and setup asks for approval, reply explicitly:
-     - y = run: npm i -g oh-my-codex @fission-ai/openspec (missing ones only)
+     - y = run: npm i -g oh-my-codex @fission-ai/openspec @imdeadpool/codex-account-switcher (missing ones only)
      - n = skip global installs
 
 3) If setup reports warnings/errors, repair + re-check:
@@ -141,6 +154,12 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
    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)"
+   - For every new user message/task, repeat the same cycle:
+     start isolated agent branch/worktree -> claim file locks -> implement/verify ->
+     finish via PR/merge cleanup with scripts/agent-branch-finish.sh.
+   - Finished branches stay available by default for audit/follow-up.
+     Remove them explicitly when done:
+     gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
 
 5) Optional: create OpenSpec planning workspace:
    bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
@@ -151,6 +170,9 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
 7) Optional: sync your current agent branch with latest base branch:
    gx sync --check
    gx sync
+
+8) Optional (GitHub remote cleanup): enable:
+   Settings -> General -> Pull Requests -> Automatically delete head branches
 `;
 
 const AI_SETUP_COMMANDS = `npm i -g @imdeadpool/guardex
@@ -160,6 +182,7 @@ 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 cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
 bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
 gx protect add release staging
 gx sync --check
@@ -272,7 +295,12 @@ ${commandCatalogLines().join('\n')}
 NOTES
   - Running ${TOOL_NAME} with no command defaults to: ${SHORT_TOOL_NAME} status
   - Short alias: ${SHORT_TOOL_NAME}
+  - ${SHORT_TOOL_NAME} init is an alias of ${SHORT_TOOL_NAME} setup
   - ${TOOL_NAME} setup asks for Y/N approval before global installs
+  - In initialized repos, setup/install/fix block in-place writes on protected main by default
+  - doctor auto-starts a sandbox agent branch/worktree when run on protected main
+  - 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)
   - Legacy command aliases are still supported: ${LEGACY_NAMES.join(', ')}`);
 
   if (outsideGitRepo) {
@@ -346,6 +374,10 @@ function ensureExecutable(destinationPath, relativePath, dryRun) {
   }
 }
 
+function isCriticalGuardrailPath(relativePath) {
+  return CRITICAL_GUARDRAIL_PATHS.has(relativePath);
+}
+
 function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
   const sourcePath = path.join(TEMPLATE_ROOT, relativeTemplatePath);
   const destinationRelativePath = toDestinationPath(relativeTemplatePath);
@@ -360,7 +392,7 @@ function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
       ensureExecutable(destinationPath, destinationRelativePath, dryRun);
       return { status: 'unchanged', file: destinationRelativePath };
     }
-    if (!force) {
+    if (!force && !isCriticalGuardrailPath(destinationRelativePath)) {
       throw new Error(
         `Refusing to overwrite existing file without --force: ${destinationRelativePath}`,
       );
@@ -373,6 +405,10 @@ function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
     ensureExecutable(destinationPath, destinationRelativePath, dryRun);
   }
 
+  if (destinationExists && !force && isCriticalGuardrailPath(destinationRelativePath)) {
+    return { status: dryRun ? 'would-repair-critical' : 'repaired-critical', file: destinationRelativePath };
+  }
+
   return { status: destinationExists ? 'overwritten' : 'created', file: destinationRelativePath };
 }
 
@@ -389,6 +425,14 @@ function ensureTemplateFilePresent(repoRoot, relativeTemplatePath, dryRun) {
       return { status: 'unchanged', file: destinationRelativePath };
     }
 
+    if (isCriticalGuardrailPath(destinationRelativePath)) {
+      if (!dryRun) {
+        fs.writeFileSync(destinationPath, sourceContent, 'utf8');
+        ensureExecutable(destinationPath, destinationRelativePath, dryRun);
+      }
+      return { status: dryRun ? 'would-repair-critical' : 'repaired-critical', file: destinationRelativePath };
+    }
+
     // In fix mode, avoid silently replacing local customizations.
     return { status: 'skipped-conflict', file: destinationRelativePath };
   }
@@ -473,7 +517,7 @@ function ensurePackageScripts(repoRoot, dryRun) {
     'agent:codex': 'bash ./scripts/codex-agent.sh',
     'agent:branch:start': 'bash ./scripts/agent-branch-start.sh',
     'agent:branch:finish': 'bash ./scripts/agent-branch-finish.sh',
-    'agent:cleanup': 'bash ./scripts/agent-worktree-prune.sh --base dev',
+    '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',
     'agent:locks:allow-delete': 'python3 ./scripts/agent-file-locks.py allow-delete',
@@ -630,6 +674,10 @@ function parseCommonArgs(rawArgs, defaults) {
       options.skipGitignore = true;
       continue;
     }
+    if (arg === '--allow-protected-base-write') {
+      options.allowProtectedBaseWrite = true;
+      continue;
+    }
 
     throw new Error(`Unknown option: ${arg}`);
   }
@@ -641,6 +689,149 @@ function parseCommonArgs(rawArgs, defaults) {
   return options;
 }
 
+function hasGuardexBootstrapFiles(repoRoot) {
+  const required = [
+    'AGENTS.md',
+    'scripts/agent-branch-start.sh',
+    '.githooks/pre-commit',
+    LOCK_FILE_RELATIVE,
+  ];
+  return required.every((relativePath) => fs.existsSync(path.join(repoRoot, relativePath)));
+}
+
+function protectedBaseWriteBlock(options) {
+  if (options.dryRun || options.allowProtectedBaseWrite) {
+    return null;
+  }
+
+  const repoRoot = resolveRepoRoot(options.target);
+  if (!hasGuardexBootstrapFiles(repoRoot)) {
+    return null;
+  }
+
+  const branch = currentBranchName(repoRoot);
+  if (branch !== 'main') {
+    return null;
+  }
+
+  const protectedBranches = readProtectedBranches(repoRoot);
+  if (!protectedBranches.includes(branch)) {
+    return null;
+  }
+
+  return {
+    repoRoot,
+    branch,
+  };
+}
+
+function assertProtectedMainWriteAllowed(options, commandName) {
+  const blocked = protectedBaseWriteBlock(options);
+  if (!blocked) {
+    return;
+  }
+
+  throw new Error(
+    `${commandName} blocked on protected branch '${blocked.branch}' in an initialized repo.\n` +
+    `Keep local '${blocked.branch}' pull-only: start an agent branch/worktree first:\n` +
+    `  bash scripts/agent-branch-start.sh "<task>" "codex"\n` +
+    `Override once only when intentional: --allow-protected-base-write`,
+  );
+}
+
+function extractAgentBranchStartMetadata(output) {
+  const branchMatch = String(output || '').match(/^\[agent-branch-start\] Created branch: (.+)$/m);
+  const worktreeMatch = String(output || '').match(/^\[agent-branch-start\] Worktree: (.+)$/m);
+  return {
+    branch: branchMatch ? branchMatch[1].trim() : '',
+    worktreePath: worktreeMatch ? worktreeMatch[1].trim() : '',
+  };
+}
+
+function resolveSandboxTarget(repoRoot, worktreePath, targetPath) {
+  const resolvedTarget = path.resolve(targetPath);
+  const relativeTarget = path.relative(repoRoot, resolvedTarget);
+  if (relativeTarget.startsWith('..') || path.isAbsolute(relativeTarget)) {
+    throw new Error(`doctor target must stay inside repo root when sandboxing: ${resolvedTarget}`);
+  }
+  if (!relativeTarget || relativeTarget === '.') {
+    return worktreePath;
+  }
+  return path.join(worktreePath, relativeTarget);
+}
+
+function buildSandboxDoctorArgs(options, sandboxTarget) {
+  const args = ['doctor', '--target', sandboxTarget];
+  if (options.dryRun) args.push('--dry-run');
+  if (options.skipAgents) args.push('--skip-agents');
+  if (options.skipPackageJson) args.push('--skip-package-json');
+  if (options.skipGitignore) args.push('--no-gitignore');
+  if (!options.dropStaleLocks) args.push('--keep-stale-locks');
+  if (options.json) args.push('--json');
+  return args;
+}
+
+function runDoctorInSandbox(options, blocked) {
+  const startScript = path.join(blocked.repoRoot, 'scripts', 'agent-branch-start.sh');
+  if (!fs.existsSync(startScript)) {
+    throw new Error(
+      `doctor sandbox fallback is unavailable because '${startScript}' is missing.\n` +
+      `Run '${SHORT_TOOL_NAME} setup --allow-protected-base-write' once to restore branch-start tooling.`,
+    );
+  }
+
+  const startResult = run('bash', [
+    startScript,
+    '--task',
+    `${SHORT_TOOL_NAME}-doctor`,
+    '--agent',
+    SHORT_TOOL_NAME,
+    '--base',
+    blocked.branch,
+  ], { cwd: blocked.repoRoot });
+  if (startResult.error) {
+    throw startResult.error;
+  }
+  if (startResult.status !== 0) {
+    throw new Error((startResult.stderr || startResult.stdout || 'failed to start doctor sandbox').trim());
+  }
+
+  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 sandboxTarget = resolveSandboxTarget(blocked.repoRoot, metadata.worktreePath, options.target);
+  const nestedResult = run(
+    process.execPath,
+    [__filename, ...buildSandboxDoctorArgs(options, sandboxTarget)],
+    { cwd: metadata.worktreePath },
+  );
+  if (nestedResult.error) {
+    throw nestedResult.error;
+  }
+
+  if (options.json) {
+    if (nestedResult.stdout) process.stdout.write(nestedResult.stdout);
+    if (nestedResult.stderr) process.stderr.write(nestedResult.stderr);
+  } else {
+    console.log(
+      `[${TOOL_NAME}] doctor detected protected branch '${blocked.branch}'. ` +
+      `Running repairs in sandbox branch '${metadata.branch || 'agent/<auto>'}'.`,
+    );
+    if (startResult.stdout) process.stdout.write(startResult.stdout);
+    if (startResult.stderr) process.stderr.write(startResult.stderr);
+    if (nestedResult.stdout) process.stdout.write(nestedResult.stdout);
+    if (nestedResult.stderr) process.stderr.write(nestedResult.stderr);
+  }
+
+  if (typeof nestedResult.status === 'number') {
+    process.exitCode = nestedResult.status;
+    return;
+  }
+  process.exitCode = 1;
+}
+
 function parseTargetFlag(rawArgs, defaultTarget = process.cwd()) {
   const remaining = [];
   let target = defaultTarget;
@@ -1076,6 +1267,63 @@ function parseSyncArgs(rawArgs) {
   return options;
 }
 
+function parseCleanupArgs(rawArgs) {
+  const options = {
+    target: process.cwd(),
+    base: '',
+    branch: '',
+    dryRun: false,
+    forceDirty: false,
+    keepRemote: false,
+  };
+
+  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 === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+    if (arg === '--force-dirty') {
+      options.forceDirty = true;
+      continue;
+    }
+    if (arg === '--keep-remote') {
+      options.keepRemote = true;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  return options;
+}
+
 function syncOperation(repoRoot, strategy, baseRef, ffOnly) {
   if (strategy === 'rebase') {
     if (ffOnly) {
@@ -1777,8 +2025,10 @@ function install(rawArgs) {
     skipPackageJson: false,
     skipGitignore: false,
     dryRun: false,
+    allowProtectedBaseWrite: false,
   });
 
+  assertProtectedMainWriteAllowed(options, 'install');
   const payload = runInstallInternal(options);
   printOperations('Install target', payload, options.dryRun);
 
@@ -1797,8 +2047,10 @@ function fix(rawArgs) {
     skipPackageJson: false,
     skipGitignore: false,
     dryRun: false,
+    allowProtectedBaseWrite: false,
   });
 
+  assertProtectedMainWriteAllowed(options, 'fix');
   const payload = runFixInternal(options);
   printOperations('Fix target', payload, options.dryRun);
 
@@ -1829,8 +2081,16 @@ function doctor(rawArgs) {
     skipGitignore: false,
     dryRun: false,
     json: false,
+    allowProtectedBaseWrite: false,
   });
 
+  const blocked = protectedBaseWriteBlock(options);
+  if (blocked) {
+    runDoctorInSandbox(options, blocked);
+    return;
+  }
+
+  assertProtectedMainWriteAllowed(options, 'doctor');
   const fixPayload = runFixInternal(options);
   const scanResult = runScanInternal({ target: options.target, json: false });
   const musafe = scanResult.errors === 0 && scanResult.warnings === 0;
@@ -1974,6 +2234,7 @@ function setup(rawArgs) {
     dryRun: false,
     yesGlobalInstall: false,
     noGlobalInstall: false,
+    allowProtectedBaseWrite: false,
   });
 
   const globalInstallStatus = installGlobalToolchain(options);
@@ -1982,7 +2243,7 @@ function setup(rawArgs) {
       `[${TOOL_NAME}] ✅ Global tools installed (${(globalInstallStatus.packages || []).join(', ')}).`,
     );
   } else if (globalInstallStatus.status === 'already-installed') {
-    console.log(`[${TOOL_NAME}] ✅ OMX/OpenSpec global tools already installed. Skipping.`);
+    console.log(`[${TOOL_NAME}] ✅ OMX/OpenSpec/codex-auth global tools already installed. Skipping.`);
   } else if (globalInstallStatus.status === 'failed') {
     console.log(
       `[${TOOL_NAME}] ⚠️ Global install failed: ${globalInstallStatus.reason}\n` +
@@ -1996,6 +2257,7 @@ function setup(rawArgs) {
     );
   }
 
+  assertProtectedMainWriteAllowed(options, 'setup');
   const installPayload = runInstallInternal(options);
   printOperations('Setup/install', installPayload, options.dryRun);
 
@@ -2090,6 +2352,39 @@ function copyCommands() {
   process.exitCode = 0;
 }
 
+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 = [pruneScript];
+  if (options.base) {
+    args.push('--base', options.base);
+  }
+  if (options.branch) {
+    args.push('--branch', options.branch);
+  }
+  if (options.forceDirty) {
+    args.push('--force-dirty');
+  }
+  if (options.dryRun) {
+    args.push('--dry-run');
+  }
+  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');
+  }
+  process.exitCode = 0;
+}
+
 function sync(rawArgs) {
   const options = parseSyncArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);
@@ -2403,7 +2698,7 @@ function main() {
     return;
   }
 
-  if (command === 'setup') {
+  if (command === 'setup' || command === 'init') {
     setup(rest);
     return;
   }
@@ -2438,6 +2733,11 @@ function main() {
     return;
   }
 
+  if (command === 'cleanup') {
+    cleanup(rest);
+    return;
+  }
+
   if (command === 'release') {
     release(rest);
     return;

package/package.json

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

package/templates/AGENTS.multiagent-safety.md

@@ -10,7 +10,13 @@
 - Before deleting/replacing code, each agent must read the latest session comments/handoffs first and confirm the target code is in their owned scope.
 - If ownership is unclear or overlaps, stop that edit, post a blocker comment, and let the leader/integrator reassign scope.
 - For git isolation, each agent must start on a dedicated branch via `scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"`.
-- Agent completion must use `scripts/agent-branch-finish.sh` (direct merge to base when allowed; auto PR fallback for protected bases, then cleanup after merge).
+- Treat the base branch (`main` or the user's current local base branch) as read-only while the agent branch is active.
+- Agent completion defaults to `scripts/codex-agent.sh`, which auto-finishes the branch (auto-commit changed files, push/create PR, attempt merge, and pull the local base branch after merge).
+- Auto-finish keeps the sandbox branch/worktree by default so conflict follow-ups and audits stay reproducible.
+- Use explicit cleanup when done: `gx cleanup --branch "<agent-branch>"` (or `gx cleanup` for all merged agent branches).
+- If codex-agent auto-finish cannot complete, immediately run `scripts/agent-branch-finish.sh --branch "<agent-branch>" --via-pr` and keep the branch open until checks/review pass.
+- If merge/rebase conflicts block auto-finish, run a conflict-resolution review pass in that sandbox branch, then rerun `agent-branch-finish.sh --via-pr` until merged.
+- Per-message loop is mandatory: for every new user message/task, start a fresh agent branch/worktree, claim ownership locks, implement and verify, finish via PR/merge cleanup, then repeat for the next message/task.
 
 1. Explicit ownership before edits
 

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

@@ -19,6 +19,8 @@ If guardrails are missing entirely, run:
 
 ```sh
 gx setup
+# alias
+gx init
 ```
 
 Then verify:
@@ -32,5 +34,8 @@ gx scan
 
 - Prefer `gx doctor` for one-step repair + verification.
 - Keep agent work isolated (`agent/*` branches + lock claims).
+- For every new user message/task, restart the full loop on a fresh agent branch/worktree.
 - For one-command Codex sandbox startup, use `bash scripts/codex-agent.sh "<task>" "<agent-name>"`.
+- `scripts/codex-agent.sh` auto-syncs the sandbox branch against base before each task and auto-finishes merge/PR flow after Codex exits.
+- Auto-finish keeps the branch/worktree by default; remove merged branches explicitly with `gx cleanup` (or `gx cleanup --branch "<agent-branch>"`).
 - Do not bypass protected branch safeguards unless explicitly required.