@imdeadpool/guardex 5.0.8 → 5.0.9

package/README.md

@@ -71,6 +71,12 @@ gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
 If you use `scripts/codex-agent.sh`, the finish flow is auto-run after the Codex session exits.
 It auto-commits sandbox changes, retries once after syncing if the branch moved behind base during the run, then pushes/opens PR merge flow against the current base branch.
 
+If you run Codex in multiple existing agent worktrees directly (for example from VS Code Source Control), finalize all completed branches with:
+
+```sh
+gx finish --all
+```
+
 ## Visual workflow
 
 ### Setup status
@@ -89,6 +95,10 @@ It auto-commits sandbox changes, retries once after syncing if the branch moved
 
 ![gx lock and delete guard screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/workflow-lock-guard.svg)
 
+### Real VS Code Source Control layout (exact screenshot)
+
+![Real VS Code Source Control layout](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/workflow-vscode-source-control-exact.png)
+
 ## Copy-paste: common commands
 
 ```sh
@@ -114,6 +124,9 @@ gx sync
 # continuously monitor open PRs targeting current branch and dispatch codex-agent review/merge tasks
 gx review --interval 30
 
+# auto-commit finished agent branches and open/merge PR flow in one pass
+gx finish --all
+
 # cleanup merged agent branches and hide clean stale agent worktrees
 gx cleanup
 
@@ -228,6 +241,19 @@ scripts/openspec/init-plan-workspace.sh
 
 If `package.json` exists, setup also adds `agent:*` helper scripts.
 
+## OpenSpec quick start after `gx setup`
+
+If you enabled global OpenSpec install during setup (`@fission-ai/openspec`), use the full guide here:
+
+- [`docs/openspec-getting-started.md`](./docs/openspec-getting-started.md)
+
+### OpenSpec in agent sub-branches
+
+- `scripts/codex-agent.sh` enforces an OpenSpec workspace before it launches Codex in each sandbox branch/worktree.
+- `scripts/agent-branch-start.sh` can also scaffold `openspec/plan/<agent-branch-slug>/` when you set `MUSAFETY_OPENSPEC_AUTO_INIT=true`.
+- Set `MUSAFETY_OPENSPEC_AUTO_INIT=false` (default for `agent-branch-start`) to skip branch-start auto-bootstrap.
+- Set `MUSAFETY_OPENSPEC_PLAN_SLUG=<kebab-case-slug>` to force a specific plan workspace name.
+
 ## Security and maintenance posture
 
 - CI matrix on Node 18/20/22 (`npm test`, `node --check`, `npm pack --dry-run`)
@@ -245,6 +271,12 @@ npm pack --dry-run
 
 ## Release notes
 
+### v5.0.9
+
+- Enforced OpenSpec workspace bootstrap for sandbox agent execution: `scripts/codex-agent.sh` now initializes `openspec/plan/<agent-branch-slug>/` before launching Codex, and `scripts/agent-branch-start.sh` supports `MUSAFETY_OPENSPEC_AUTO_INIT` plus `MUSAFETY_OPENSPEC_PLAN_SLUG`.
+- Tightened doctor auto-finish correctness: sandbox finish now waits for merge and exits non-zero if the PR closes without merge, so repair flows are not reported as complete when policy blocks merge.
+- Updated package version from `5.0.8` to `5.0.9` for the next npm publish.
+
 ### v5.0.8
 
 - Fixed `bin/multiagent-safety.js` syntax regressions in the doctor sandbox flow (`Unexpected identifier` / `Unexpected end of input`) that were breaking CLI execution and CI tests.

package/bin/multiagent-safety.js

@@ -128,6 +128,7 @@ const SUGGESTIBLE_COMMANDS = [
   'init',
   'doctor',
   'review',
+  'finish',
   'report',
   'copy-prompt',
   'copy-commands',
@@ -148,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)'],
@@ -198,6 +200,8 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
    - Finished branches stay available by default for audit/follow-up.
      Remove them explicitly when done:
      gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
+   - To finalize all completed agent branches in one pass:
+     gx finish --all
 
 6) Optional: create OpenSpec planning workspace:
    bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
@@ -222,6 +226,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 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
@@ -628,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',
@@ -1180,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;
 }
@@ -1211,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)) {
@@ -1228,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 {
@@ -1491,7 +1517,18 @@ function runDoctorInSandbox(options, blocked) {
   }
 
   if (typeof nestedResult.status === 'number') {
-    process.exitCode = nestedResult.status;
+    let exitCode = nestedResult.status;
+    if (exitCode === 0 && autoCommitResult.status === 'failed') {
+      exitCode = 1;
+    }
+    if (
+      exitCode === 0 &&
+      autoCommitResult.status === 'committed' &&
+      (finishResult.status === 'failed' || finishResult.status === 'pending')
+    ) {
+      exitCode = 1;
+    }
+    process.exitCode = exitCode;
     return;
   }
   process.exitCode = 1;
@@ -1914,6 +1951,12 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
     summary.details.push('Skipped auto-finish sweep (origin remote missing).');
     return summary;
   }
+  const explicitGhBin = Boolean(String(process.env.MUSAFETY_GH_BIN || '').trim());
+  if (!explicitGhBin && !originRemoteLooksLikeGithub(repoRoot)) {
+    summary.enabled = false;
+    summary.details.push('Skipped auto-finish sweep (origin remote is not GitHub).');
+    return summary;
+  }
 
   const ghBin = process.env.MUSAFETY_GH_BIN || 'gh';
   if (run(ghBin, ['--version']).status !== 0) {
@@ -1973,6 +2016,7 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
       '--base',
       baseBranch,
       '--via-pr',
+      '--wait-for-merge',
       '--cleanup',
     ];
     const finishResult = run('bash', finishArgs, { cwd: repoRoot });
@@ -2285,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) {
@@ -3487,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);
@@ -3815,6 +4358,11 @@ function main() {
     return;
   }
 
+  if (command === 'finish') {
+    finish(rest);
+    return;
+  }
+
   if (command === 'report') {
     report(rest);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "5.0.8",
+  "version": "5.0.9",
   "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

@@ -45,9 +45,17 @@
 - Verification commands + results
 - Risks / follow-ups
 
-## OpenSpec Plan Workspace (recommended)
+## OpenSpec Plan Workspace (required for agent sub-branch changes)
 
-When work needs a durable planning phase, scaffold a plan workspace before implementation:
+OMX Codex execution flows must use OpenSpec. `scripts/codex-agent.sh` bootstraps a
+per-branch plan workspace automatically under:
+
+```text
+openspec/plan/<agent-branch-slug>/
+```
+
+For manual `scripts/agent-branch-start.sh` usage, enable auto-bootstrap with
+`MUSAFETY_OPENSPEC_AUTO_INIT=true` or scaffold manually before implementation:
 
 ```bash
 bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"

package/templates/scripts/agent-branch-finish.sh

@@ -338,7 +338,7 @@ is_local_branch_delete_error() {
 
 read_pr_state() {
   local state_line
-  state_line="$("$GH_BIN" pr view "$SOURCE_BRANCH" --json state,mergedAt,url --jq '[.state, (.mergedAt // ""), (.url // "")] | @tsv' 2>/dev/null || true)"
+  state_line="$("$GH_BIN" pr view "$SOURCE_BRANCH" --json state,mergedAt,url --jq '[.state, (.mergedAt // ""), (.url // "")] | join("\u001f")' 2>/dev/null || true)"
   if [[ -z "$state_line" ]]; then
     return 1
   fi
@@ -346,7 +346,7 @@ read_pr_state() {
   local parsed_state=""
   local parsed_merged_at=""
   local parsed_url=""
-  IFS=$'\t' read -r parsed_state parsed_merged_at parsed_url <<< "$state_line"
+  IFS=$'\x1f' read -r parsed_state parsed_merged_at parsed_url <<< "$state_line"
   PR_STATE="$parsed_state"
   PR_MERGED_AT="$parsed_merged_at"
   if [[ -n "$parsed_url" ]]; then

package/templates/scripts/agent-branch-start.sh

@@ -6,6 +6,8 @@ AGENT_NAME="agent"
 BASE_BRANCH=""
 BASE_BRANCH_EXPLICIT=0
 WORKTREE_ROOT_REL=".omx/agent-worktrees"
+OPENSPEC_AUTO_INIT_RAW="${MUSAFETY_OPENSPEC_AUTO_INIT:-false}"
+OPENSPEC_PLAN_SLUG_OVERRIDE="${MUSAFETY_OPENSPEC_PLAN_SLUG:-}"
 POSITIONAL_ARGS=()
 
 while [[ $# -gt 0 ]]; do
@@ -82,6 +84,31 @@ sanitize_slug() {
   printf '%s' "$slug"
 }
 
+normalize_bool() {
+  local raw="${1:-}"
+  local fallback="${2:-0}"
+  local lowered
+  lowered="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')"
+  case "$lowered" in
+    1|true|yes|on) printf '1' ;;
+    0|false|no|off) printf '0' ;;
+    '') printf '%s' "$fallback" ;;
+    *) printf '%s' "$fallback" ;;
+  esac
+}
+
+OPENSPEC_AUTO_INIT="$(normalize_bool "$OPENSPEC_AUTO_INIT_RAW" "1")"
+
+resolve_openspec_plan_slug() {
+  local branch_name="$1"
+  local task_slug="$2"
+  if [[ -n "$OPENSPEC_PLAN_SLUG_OVERRIDE" ]]; then
+    sanitize_slug "$OPENSPEC_PLAN_SLUG_OVERRIDE" "$task_slug"
+    return 0
+  fi
+  sanitize_slug "${branch_name//\//-}" "$task_slug"
+}
+
 resolve_active_codex_snapshot_name() {
   local override="${MUSAFETY_CODEX_AUTH_SNAPSHOT:-}"
   if [[ -n "$override" ]]; then
@@ -114,17 +141,6 @@ has_local_changes() {
   return 1
 }
 
-has_tracked_changes() {
-  local root="$1"
-  if ! git -C "$root" diff --quiet; then
-    return 0
-  fi
-  if ! git -C "$root" diff --cached --quiet; then
-    return 0
-  fi
-  return 1
-}
-
 resolve_protected_branches() {
   local root="$1"
   local raw
@@ -177,6 +193,43 @@ hydrate_local_helper_in_worktree() {
   echo "[agent-branch-start] Hydrated local helper in worktree: ${relative_path}"
 }
 
+initialize_openspec_plan_workspace() {
+  local repo="$1"
+  local worktree="$2"
+  local plan_slug="$3"
+
+  hydrate_local_helper_in_worktree "$repo" "$worktree" "scripts/openspec/init-plan-workspace.sh"
+
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+    return 0
+  fi
+
+  local openspec_script="${worktree}/scripts/openspec/init-plan-workspace.sh"
+  if [[ ! -f "$openspec_script" ]]; then
+    echo "[agent-branch-start] OpenSpec init script is missing in sandbox worktree." >&2
+    echo "[agent-branch-start] Run 'gx setup --target \"$repo\"' to repair templates, then retry." >&2
+    return 1
+  fi
+  if [[ ! -x "$openspec_script" ]]; then
+    chmod +x "$openspec_script" 2>/dev/null || true
+  fi
+
+  local init_output=""
+  if ! init_output="$(
+    cd "$worktree"
+    bash "scripts/openspec/init-plan-workspace.sh" "$plan_slug" 2>&1
+  )"; then
+    printf '%s\n' "$init_output" >&2
+    echo "[agent-branch-start] OpenSpec workspace initialization failed for plan '${plan_slug}'." >&2
+    return 1
+  fi
+
+  if [[ -n "$init_output" ]]; then
+    printf '%s\n' "$init_output"
+  fi
+  echo "[agent-branch-start] OpenSpec plan workspace: ${worktree}/openspec/plan/${plan_slug}"
+}
+
 if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   echo "[agent-branch-start] Not inside a git repository." >&2
   exit 1
@@ -190,12 +243,15 @@ if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
 fi
 
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 0 ]]; then
-  configured_base="$(git -C "$repo_root" config --get multiagent.baseBranch || true)"
-  if [[ -n "$configured_base" ]]; then
-    BASE_BRANCH="$configured_base"
+  current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+  protected_branches_raw="$(resolve_protected_branches "$repo_root")"
+  if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]] && is_protected_branch_name "$current_branch" "$protected_branches_raw"; then
+    BASE_BRANCH="$current_branch"
   else
-    current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
-    if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]]; then
+    configured_base="$(git -C "$repo_root" config --get multiagent.baseBranch || true)"
+    if [[ -n "$configured_base" ]]; then
+      BASE_BRANCH="$configured_base"
+    elif [[ -n "$current_branch" && "$current_branch" != "HEAD" ]]; then
       BASE_BRANCH="$current_branch"
     else
       BASE_BRANCH="dev"
@@ -235,6 +291,7 @@ done
 worktree_root="${repo_root}/${WORKTREE_ROOT_REL}"
 mkdir -p "$worktree_root"
 worktree_path="${worktree_root}/${branch_name//\//__}"
+openspec_plan_slug="$(resolve_openspec_plan_slug "$branch_name" "$task_slug")"
 
 if [[ -e "$worktree_path" ]]; then
   echo "[agent-branch-start] Worktree path already exists: ${worktree_path}" >&2
@@ -243,10 +300,11 @@ fi
 
 auto_transfer_stash_ref=""
 auto_transfer_message=""
+auto_transfer_source_branch=""
 current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
 protected_branches_raw="$(resolve_protected_branches "$repo_root")"
-if [[ "$current_branch" == "$BASE_BRANCH" ]] && is_protected_branch_name "$BASE_BRANCH" "$protected_branches_raw"; then
-  if has_tracked_changes "$repo_root"; then
+if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]] && is_protected_branch_name "$current_branch" "$protected_branches_raw"; then
+  if has_local_changes "$repo_root"; then
     auto_transfer_message="musafety-auto-transfer-${timestamp}-${agent_slug}-${task_slug}"
     if git -C "$repo_root" stash push --include-untracked --message "$auto_transfer_message" >/dev/null 2>&1; then
       auto_transfer_stash_ref="$(
@@ -254,7 +312,8 @@ if [[ "$current_branch" == "$BASE_BRANCH" ]] && is_protected_branch_name "$BASE_
           | awk -v msg="$auto_transfer_message" '$0 ~ msg { ref=$1; sub(/:$/, "", ref); print ref; exit }'
       )"
       if [[ -n "$auto_transfer_stash_ref" ]]; then
-        echo "[agent-branch-start] Detected local changes on protected base '${BASE_BRANCH}'. Moving them to '${branch_name}'..."
+        auto_transfer_source_branch="$current_branch"
+        echo "[agent-branch-start] Detected local changes on protected branch '${current_branch}'. Moving them to '${branch_name}'..."
       fi
     fi
   fi
@@ -270,19 +329,25 @@ fi
 if [[ -n "$auto_transfer_stash_ref" ]]; then
   if git -C "$worktree_path" stash apply "$auto_transfer_stash_ref" >/dev/null 2>&1; then
     git -C "$repo_root" stash drop "$auto_transfer_stash_ref" >/dev/null 2>&1 || true
-    echo "[agent-branch-start] Moved local changes from '${BASE_BRANCH}' into '${branch_name}'."
+    transfer_label="${auto_transfer_source_branch:-$BASE_BRANCH}"
+    echo "[agent-branch-start] Moved local changes from '${transfer_label}' into '${branch_name}'."
   else
     echo "[agent-branch-start] Failed to auto-apply moved changes in new worktree." >&2
-    echo "[agent-branch-start] Changes are preserved in ${auto_transfer_stash_ref} on ${BASE_BRANCH}." >&2
+    transfer_label="${auto_transfer_source_branch:-$BASE_BRANCH}"
+    echo "[agent-branch-start] Changes are preserved in ${auto_transfer_stash_ref} on ${transfer_label}." >&2
     echo "[agent-branch-start] Apply manually with: git -C \"$worktree_path\" stash apply \"${auto_transfer_stash_ref}\"" >&2
     exit 1
   fi
 fi
 
 hydrate_local_helper_in_worktree "$repo_root" "$worktree_path" "scripts/codex-agent.sh"
+if ! initialize_openspec_plan_workspace "$repo_root" "$worktree_path" "$openspec_plan_slug"; then
+  exit 1
+fi
 
 echo "[agent-branch-start] Created branch: ${branch_name}"
 echo "[agent-branch-start] Worktree: ${worktree_path}"
+echo "[agent-branch-start] OpenSpec plan: openspec/plan/${openspec_plan_slug}"
 echo "[agent-branch-start] Next steps:"
 echo "  cd \"${worktree_path}\""
 echo "  python3 scripts/agent-file-locks.py claim --branch \"${branch_name}\" <file...>"

package/templates/scripts/codex-agent.sh

@@ -10,6 +10,8 @@ AUTO_FINISH_RAW="${MUSAFETY_CODEX_AUTO_FINISH:-true}"
 AUTO_REVIEW_ON_CONFLICT_RAW="${MUSAFETY_CODEX_AUTO_REVIEW_ON_CONFLICT:-true}"
 AUTO_CLEANUP_RAW="${MUSAFETY_CODEX_AUTO_CLEANUP:-true}"
 AUTO_WAIT_FOR_MERGE_RAW="${MUSAFETY_CODEX_WAIT_FOR_MERGE:-true}"
+OPENSPEC_AUTO_INIT_RAW="${MUSAFETY_OPENSPEC_AUTO_INIT:-true}"
+OPENSPEC_PLAN_SLUG_OVERRIDE="${MUSAFETY_OPENSPEC_PLAN_SLUG:-}"
 
 normalize_bool() {
   local raw="${1:-}"
@@ -28,6 +30,7 @@ AUTO_FINISH="$(normalize_bool "$AUTO_FINISH_RAW" "1")"
 AUTO_REVIEW_ON_CONFLICT="$(normalize_bool "$AUTO_REVIEW_ON_CONFLICT_RAW" "1")"
 AUTO_CLEANUP="$(normalize_bool "$AUTO_CLEANUP_RAW" "1")"
 AUTO_WAIT_FOR_MERGE="$(normalize_bool "$AUTO_WAIT_FOR_MERGE_RAW" "1")"
+OPENSPEC_AUTO_INIT="$(normalize_bool "$OPENSPEC_AUTO_INIT_RAW" "1")"
 
 if [[ -n "$BASE_BRANCH" ]]; then
   BASE_BRANCH_EXPLICIT=1
@@ -136,6 +139,46 @@ sanitize_slug() {
   printf '%s' "$slug"
 }
 
+resolve_openspec_plan_slug() {
+  local branch_name="$1"
+  local task_slug
+  task_slug="$(sanitize_slug "$TASK_NAME" "task")"
+  if [[ -n "$OPENSPEC_PLAN_SLUG_OVERRIDE" ]]; then
+    sanitize_slug "$OPENSPEC_PLAN_SLUG_OVERRIDE" "$task_slug"
+    return 0
+  fi
+  sanitize_slug "${branch_name//\//-}" "$task_slug"
+}
+
+hydrate_local_helper_in_worktree() {
+  local worktree="$1"
+  local relative_path="$2"
+  local worktree_target="${worktree}/${relative_path}"
+  local source_path=""
+
+  if [[ -e "$worktree_target" ]]; then
+    return 0
+  fi
+
+  if [[ -f "${repo_root}/${relative_path}" ]]; then
+    source_path="${repo_root}/${relative_path}"
+  elif [[ -f "${repo_root}/templates/${relative_path}" ]]; then
+    source_path="${repo_root}/templates/${relative_path}"
+  fi
+
+  if [[ -z "$source_path" ]]; then
+    return 0
+  fi
+
+  mkdir -p "$(dirname "$worktree_target")"
+  cp "$source_path" "$worktree_target"
+  if [[ -x "$source_path" ]]; then
+    chmod +x "$worktree_target"
+  fi
+
+  echo "[codex-agent] Hydrated local helper in sandbox: ${relative_path}"
+}
+
 resolve_start_base_branch() {
   if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -n "$BASE_BRANCH" ]]; then
     printf '%s' "$BASE_BRANCH"
@@ -239,7 +282,7 @@ initial_repo_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/nu
 start_output=""
 start_status=0
 set +e
-start_output="$(bash "${repo_root}/scripts/agent-branch-start.sh" "${start_args[@]}" 2>&1)"
+start_output="$(MUSAFETY_OPENSPEC_AUTO_INIT=0 bash "${repo_root}/scripts/agent-branch-start.sh" "${start_args[@]}" 2>&1)"
 start_status=$?
 set -e
 
@@ -363,6 +406,43 @@ sync_worktree_with_base() {
   return 0
 }
 
+ensure_openspec_plan_workspace() {
+  local wt="$1"
+  local branch="$2"
+
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+    return 0
+  fi
+
+  hydrate_local_helper_in_worktree "$wt" "scripts/openspec/init-plan-workspace.sh"
+
+  local openspec_script="${wt}/scripts/openspec/init-plan-workspace.sh"
+  if [[ ! -f "$openspec_script" ]]; then
+    echo "[codex-agent] Missing OpenSpec init script in sandbox: ${openspec_script}" >&2
+    echo "[codex-agent] Run 'gx setup --target ${repo_root}' and retry." >&2
+    return 1
+  fi
+  if [[ ! -x "$openspec_script" ]]; then
+    chmod +x "$openspec_script" 2>/dev/null || true
+  fi
+
+  local plan_slug
+  plan_slug="$(resolve_openspec_plan_slug "$branch")"
+  local init_output=""
+  if ! init_output="$(
+    cd "$wt"
+    bash "scripts/openspec/init-plan-workspace.sh" "$plan_slug" 2>&1
+  )"; then
+    printf '%s\n' "$init_output" >&2
+    echo "[codex-agent] OpenSpec workspace initialization failed for plan '${plan_slug}'." >&2
+    return 1
+  fi
+  if [[ -n "$init_output" ]]; then
+    printf '%s\n' "$init_output"
+  fi
+  echo "[codex-agent] OpenSpec plan workspace: ${wt}/openspec/plan/${plan_slug}"
+}
+
 worktree_has_changes() {
   local wt="$1"
   if ! git -C "$wt" diff --quiet -- . ":(exclude).omx/state/agent-file-locks.json"; then
@@ -579,6 +659,16 @@ if ! sync_worktree_with_base "$worktree_path"; then
   exit 1
 fi
 
+worktree_branch="$(git -C "$worktree_path" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+if [[ -z "$worktree_branch" || "$worktree_branch" == "HEAD" ]]; then
+  echo "[codex-agent] Could not determine sandbox branch for worktree: $worktree_path" >&2
+  exit 1
+fi
+
+if ! ensure_openspec_plan_workspace "$worktree_path" "$worktree_branch"; then
+  exit 1
+fi
+
 echo "[codex-agent] Launching ${CODEX_BIN} in sandbox: $worktree_path"
 cd "$worktree_path"
 set +e
@@ -590,8 +680,6 @@ cd "$repo_root"
 final_exit="$codex_exit"
 auto_finish_completed=0
 
-worktree_branch="$(git -C "$worktree_path" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
-
 if [[ "$AUTO_FINISH" -eq 1 && -n "$worktree_branch" && "$worktree_branch" != "HEAD" ]]; then
   if [[ "$AUTO_WAIT_FOR_MERGE" -eq 1 && "$AUTO_CLEANUP" -eq 1 ]]; then
     echo "[codex-agent] Auto-finish enabled: commit -> push/PR -> wait for merge -> cleanup."