@imdeadpool/guardex 7.0.15 → 7.0.16

package/README.md

@@ -529,6 +529,12 @@ npm pack --dry-run
 <details>
 <summary><strong>v7.x</strong></summary>
 
+### v7.0.16
+- `gx doctor` now keeps nested repo repair runs visibly progressing, and overlapping integration work stays off the protected base branch instead of trying to merge back on `main`.
+- Cleanup and finish flows are less brittle: `codex-agent` no longer waits on PRs that can never exist, and prune cleanup now walks both managed worktree roots so stale sandboxes get removed consistently.
+- Mirror-sync diagnostics are quieter: when the mirror PAT is unset, Guardex now skips the sync path instead of marking the run red, and shared `ralplan` lanes stay easier to identify during handoff/debugging.
+- Bumped `@imdeadpool/guardex` from `7.0.15` → `7.0.16` after npm rejected a republish over the already-published `7.0.15`.
+
 ### v7.0.15
 - `gx doctor` no longer blocks recursive nested protected-repo repairs on child PR merge waits; nested sandboxes now force `--no-wait-for-merge` so the parent repair loop can continue.
 - `gx setup` can now refresh managed files from protected `main` through a temporary sandbox branch/worktree, sync the managed outputs back to the visible base checkout, and prune the sandbox afterward.

package/bin/multiagent-safety.js

@@ -89,6 +89,7 @@ const TEMPLATE_ROOT = path.resolve(__dirname, '..', 'templates');
 const TEMPLATE_FILES = [
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
+  'scripts/agent-branch-merge.sh',
   'scripts/codex-agent.sh',
   'scripts/guardex-docker-loader.sh',
   'scripts/review-bot-watch.sh',
@@ -112,6 +113,7 @@ const TEMPLATE_FILES = [
 const REQUIRED_WORKFLOW_FILES = [
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
+  'scripts/agent-branch-merge.sh',
   'scripts/guardex-docker-loader.sh',
   'scripts/agent-worktree-prune.sh',
   'scripts/agent-file-locks.py',
@@ -126,6 +128,7 @@ const REQUIRED_PACKAGE_SCRIPTS = {
   '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:branch:merge': 'bash ./scripts/agent-branch-merge.sh',
   'agent:cleanup': 'gx cleanup',
   'agent:hooks:install': 'bash ./scripts/install-agent-git-hooks.sh',
   'agent:locks:claim': 'python3 ./scripts/agent-file-locks.py claim',
@@ -149,6 +152,7 @@ const REQUIRED_PACKAGE_SCRIPTS = {
 const EXECUTABLE_RELATIVE_PATHS = new Set([
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
+  'scripts/agent-branch-merge.sh',
   'scripts/codex-agent.sh',
   'scripts/guardex-docker-loader.sh',
   'scripts/review-bot-watch.sh',
@@ -171,6 +175,7 @@ const CRITICAL_GUARDRAIL_PATHS = new Set([
   '.githooks/post-checkout',
   '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',
@@ -233,6 +238,7 @@ const SUGGESTIBLE_COMMANDS = [
   'setup',
   'doctor',
   'agents',
+  'merge',
   'finish',
   'report',
   'protect',
@@ -257,6 +263,7 @@ const CLI_COMMAND_DESCRIPTIONS = [
   ['setup', 'Install, repair, and verify guardrails (flags: --repair, --install-only, --target)'],
   ['doctor', 'Repair drift + verify (auto-sandboxes on protected main)'],
   ['protect', 'Manage protected branches (list/add/remove/set/reset)'],
+  ['merge', 'Create/reuse an integration lane and merge overlapping agent branches'],
   ['sync', 'Sync agent branches with origin/<base>'],
   ['finish', 'Commit + PR + merge completed agent branches (--all, --branch)'],
   ['cleanup', 'Prune merged/stale agent branches and worktrees'],
@@ -280,6 +287,9 @@ const DEPRECATED_COMMAND_ALIASES = new Map([
 const AGENT_BOT_DESCRIPTIONS = [
   ['agents', 'Start/stop review + cleanup bots for this repo'],
 ];
+const DOCTOR_AUTO_FINISH_DETAIL_LIMIT = 6;
+const DOCTOR_AUTO_FINISH_BRANCH_LABEL_MAX = 72;
+const DOCTOR_AUTO_FINISH_MESSAGE_MAX = 160;
 
 function envFlagIsTruthy(raw) {
   const lowered = String(raw || '').trim().toLowerCase();
@@ -301,13 +311,14 @@ const AI_SETUP_PROMPT = `GitGuardex (gx) setup checklist for Codex/Claude in thi
 3) Repair:     gx doctor
 4) Task loop:  bash scripts/codex-agent.sh "<task>" "<agent>"
                or branch-start -> python3 scripts/agent-file-locks.py claim -> branch-finish
-5) Finish:     gx finish --all
-6) Cleanup:    gx cleanup
-7) OpenSpec:   /opsx:propose -> /opsx:apply -> /opsx:archive
-8) Optional:   gx protect add release staging
-9) Optional:   gx sync --check && gx sync
-10) Review bot: install https://github.com/apps/cr-gpt + set OPENAI_API_KEY
-11) Fork sync:  install https://github.com/apps/pull + cp .github/pull.yml.example .github/pull.yml
+5) Integrate:  gx merge --branch <agent-a> --branch <agent-b>
+6) Finish:     gx finish --all
+7) Cleanup:    gx cleanup
+8) OpenSpec:   /opsx:propose -> /opsx:apply -> /opsx:archive
+9) Optional:   gx protect add release staging
+10) Optional:  gx sync --check && gx sync
+11) Review bot: install https://github.com/apps/cr-gpt + set OPENAI_API_KEY
+12) Fork sync:  install https://github.com/apps/pull + cp .github/pull.yml.example .github/pull.yml
 `;
 
 const AI_SETUP_COMMANDS = `npm i -g @imdeadpool/guardex
@@ -316,6 +327,7 @@ gx setup
 gx doctor
 bash scripts/codex-agent.sh "<task>" "<agent>"
 python3 scripts/agent-file-locks.py claim --branch "<agent-branch>" <file...>
+gx merge --branch "<agent-a>" --branch "<agent-b>"
 gx finish --all
 gx cleanup
 gx protect add release staging
@@ -504,6 +516,113 @@ function run(cmd, args, options = {}) {
   });
 }
 
+function formatElapsedDuration(ms) {
+  const durationMs = Number.isFinite(ms) ? Math.max(0, ms) : 0;
+  if (durationMs < 1000) {
+    return `${Math.round(durationMs)}ms`;
+  }
+  if (durationMs < 10_000) {
+    return `${(durationMs / 1000).toFixed(1)}s`;
+  }
+  return `${Math.round(durationMs / 1000)}s`;
+}
+
+function truncateMiddle(value, maxLength) {
+  const text = String(value || '');
+  const limit = Number.isFinite(maxLength) ? Math.max(4, maxLength) : 0;
+  if (!limit || text.length <= limit) {
+    return text;
+  }
+
+  const visible = limit - 1;
+  const headLength = Math.ceil(visible / 2);
+  const tailLength = Math.floor(visible / 2);
+  return `${text.slice(0, headLength)}…${text.slice(text.length - tailLength)}`;
+}
+
+function truncateTail(value, maxLength) {
+  const text = String(value || '');
+  const limit = Number.isFinite(maxLength) ? Math.max(4, maxLength) : 0;
+  if (!limit || text.length <= limit) {
+    return text;
+  }
+  return `${text.slice(0, limit - 1)}…`;
+}
+
+function compactAutoFinishPathSegments(message) {
+  return String(message || '').replace(/\((\/[^)]+)\)/g, (_, rawPath) => {
+    if (
+      rawPath.includes(`${path.sep}.omx${path.sep}agent-worktrees${path.sep}`) ||
+      rawPath.includes(`${path.sep}.omc${path.sep}agent-worktrees${path.sep}`)
+    ) {
+      return `(${path.basename(rawPath)})`;
+    }
+    return `(${truncateMiddle(rawPath, 72)})`;
+  });
+}
+
+function summarizeAutoFinishDetail(detail) {
+  const trimmed = String(detail || '').trim();
+  const match = trimmed.match(/^\[(\w+)\]\s+([^:]+):\s*(.*)$/);
+  if (!match) {
+    return truncateTail(compactAutoFinishPathSegments(trimmed), DOCTOR_AUTO_FINISH_MESSAGE_MAX);
+  }
+
+  const [, status, rawBranch, rawMessage] = match;
+  const branch = truncateMiddle(rawBranch, DOCTOR_AUTO_FINISH_BRANCH_LABEL_MAX);
+  let message = String(rawMessage || '').trim();
+
+  if (status === 'fail') {
+    message = message.replace(/^auto-finish failed\.?\s*/i, '');
+    if (/\[agent-sync-guard\]/.test(message) && /Resolve conflicts/i.test(message)) {
+      message = 'rebase conflict in finish flow; run rebase --continue or rebase --abort in the source-probe worktree';
+    } else if (/unable to compute ahead\/behind/i.test(message)) {
+      const aheadBehindMatch = message.match(/unable to compute ahead\/behind(?: \([^)]+\))?/i);
+      if (aheadBehindMatch) {
+        message = aheadBehindMatch[0];
+      }
+    } else if (/remote ref does not exist/i.test(message)) {
+      message = 'branch merged, but the remote ref was already removed during cleanup';
+    }
+  }
+
+  message = compactAutoFinishPathSegments(message)
+    .replace(/\s+\|\s+/g, '; ')
+    .trim();
+
+  return `[${status}] ${branch}: ${truncateTail(message, DOCTOR_AUTO_FINISH_MESSAGE_MAX)}`;
+}
+
+function printAutoFinishSummary(summary, options = {}) {
+  const enabled = Boolean(summary && summary.enabled);
+  const details = Array.isArray(summary && summary.details) ? summary.details : [];
+  const baseBranch = String(options.baseBranch || summary?.baseBranch || '').trim();
+  const verbose = Boolean(options.verbose);
+  const detailLimit = Number.isFinite(options.detailLimit)
+    ? Math.max(0, options.detailLimit)
+    : DOCTOR_AUTO_FINISH_DETAIL_LIMIT;
+
+  if (enabled) {
+    console.log(
+      `[${TOOL_NAME}] Auto-finish sweep (base=${baseBranch}): attempted=${summary.attempted}, completed=${summary.completed}, skipped=${summary.skipped}, failed=${summary.failed}`,
+    );
+    const visibleDetails = verbose ? details : details.slice(0, detailLimit).map(summarizeAutoFinishDetail);
+    for (const detail of visibleDetails) {
+      console.log(`[${TOOL_NAME}]   ${detail}`);
+    }
+    if (!verbose && details.length > detailLimit) {
+      console.log(
+        `[${TOOL_NAME}]   … ${details.length - detailLimit} more branch result(s). Re-run with --verbose-auto-finish for full details.`,
+      );
+    }
+    return;
+  }
+
+  if (details.length > 0) {
+    console.log(`[${TOOL_NAME}] ${verbose ? details[0] : summarizeAutoFinishDetail(details[0])}`);
+  }
+}
+
 function gitRun(repoRoot, args, { allowFailure = false } = {}) {
   const result = run('git', ['-C', repoRoot, ...args]);
   if (!allowFailure && result.status !== 0) {
@@ -1121,7 +1240,7 @@ function parseSetupArgs(rawArgs, defaults) {
 }
 
 function parseDoctorArgs(rawArgs) {
-  return parseRepoTraversalArgs(rawArgs, {
+  const doctorDefaults = {
     target: process.cwd(),
     dropStaleLocks: true,
     skipAgents: false,
@@ -1131,7 +1250,24 @@ function parseDoctorArgs(rawArgs) {
     json: false,
     allowProtectedBaseWrite: false,
     waitForMerge: true,
-  });
+    verboseAutoFinish: false,
+  };
+  const forwardedArgs = [];
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === '--verbose-auto-finish') {
+      doctorDefaults.verboseAutoFinish = true;
+      continue;
+    }
+    if (arg === '--compact-auto-finish') {
+      doctorDefaults.verboseAutoFinish = false;
+      continue;
+    }
+    forwardedArgs.push(arg);
+  }
+
+  return parseRepoTraversalArgs(forwardedArgs, doctorDefaults);
 }
 
 function normalizeWorkspacePath(relativePath) {
@@ -1309,6 +1445,7 @@ function buildSandboxDoctorArgs(options, sandboxTarget) {
   if (options.skipGitignore) args.push('--no-gitignore');
   if (!options.dropStaleLocks) args.push('--keep-stale-locks');
   args.push(options.waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge');
+  if (options.verboseAutoFinish) args.push('--verbose-auto-finish');
   if (options.json) args.push('--json');
   return args;
 }
@@ -2207,6 +2344,7 @@ function runDoctorInSandbox(options, blocked) {
     postSandboxAutoFinishSummary = autoFinishReadyAgentBranches(blocked.repoRoot, {
       baseBranch: blocked.branch,
       dryRun: options.dryRun,
+      waitForMerge: options.waitForMerge,
       excludeBranches: [metadata.branch],
     });
   }
@@ -2307,16 +2445,10 @@ function runDoctorInSandbox(options, blocked) {
         console.log(`[${TOOL_NAME}] Auto-finish skipped: ${finishResult.note}.`);
       }
 
-      if (postSandboxAutoFinishSummary.enabled) {
-        console.log(
-          `[${TOOL_NAME}] Auto-finish sweep (base=${blocked.branch}): attempted=${postSandboxAutoFinishSummary.attempted}, completed=${postSandboxAutoFinishSummary.completed}, skipped=${postSandboxAutoFinishSummary.skipped}, failed=${postSandboxAutoFinishSummary.failed}`,
-        );
-        for (const detail of postSandboxAutoFinishSummary.details) {
-          console.log(`[${TOOL_NAME}]   ${detail}`);
-        }
-      } else if (postSandboxAutoFinishSummary.details.length > 0) {
-        console.log(`[${TOOL_NAME}] ${postSandboxAutoFinishSummary.details[0]}`);
-      }
+      printAutoFinishSummary(postSandboxAutoFinishSummary, {
+        baseBranch: blocked.branch,
+        verbose: options.verboseAutoFinish,
+      });
       if (omxScaffoldSyncResult.status === 'synced') {
         console.log(`[${TOOL_NAME}] Synced .omx scaffold back to protected branch workspace.`);
       } else if (omxScaffoldSyncResult.status === 'unchanged') {
@@ -2871,6 +3003,7 @@ function hasSignificantWorkingTreeChanges(worktreePath) {
 function autoFinishReadyAgentBranches(repoRoot, options = {}) {
   const baseBranch = String(options.baseBranch || '').trim();
   const dryRun = Boolean(options.dryRun);
+  const waitForMerge = options.waitForMerge !== false;
   const excludedBranches = new Set(
     Array.isArray(options.excludeBranches)
       ? options.excludeBranches.map((branch) => String(branch || '').trim()).filter(Boolean)
@@ -2989,7 +3122,7 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
       '--base',
       baseBranch,
       '--via-pr',
-      '--wait-for-merge',
+      waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge',
       '--cleanup',
     ];
     const finishResult = run('bash', finishArgs, { cwd: repoRoot });
@@ -3419,6 +3552,82 @@ function parseCleanupArgs(rawArgs) {
   return options;
 }
 
+function parseMergeArgs(rawArgs) {
+  const options = {
+    target: process.cwd(),
+    base: '',
+    into: '',
+    branches: [],
+    task: '',
+    agent: '',
+  };
+
+  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 === '--into') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--into requires an agent/* branch value');
+      }
+      options.into = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--branch') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--branch requires an agent/* branch value');
+      }
+      options.branches.push(next);
+      index += 1;
+      continue;
+    }
+    if (arg === '--task') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--task requires a task value');
+      }
+      options.task = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--agent') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--agent requires an agent value');
+      }
+      options.agent = next;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (options.branches.length === 0) {
+    throw new Error('merge requires at least one --branch <agent/*> input');
+  }
+
+  return options;
+}
+
 function parseFinishArgs(rawArgs) {
   const options = {
     target: process.cwd(),
@@ -5127,31 +5336,38 @@ function doctor(rawArgs) {
 
     const repoResults = [];
     let aggregateExitCode = 0;
-    for (const repoPath of discoveredRepos) {
+    for (let repoIndex = 0; repoIndex < discoveredRepos.length; repoIndex += 1) {
+      const repoPath = discoveredRepos[repoIndex];
+      const progressLabel = `${repoIndex + 1}/${discoveredRepos.length}`;
       if (!options.json) {
-        console.log(`[${TOOL_NAME}] ── Doctor target: ${repoPath} ──`);
+        console.log(`[${TOOL_NAME}] ── Doctor target: ${repoPath} [${progressLabel}] ──`);
       }
 
-      const nestedResult = run(
-        process.execPath,
-        [
-          path.resolve(__filename),
-          'doctor',
-          '--single-repo',
-          '--target',
-          repoPath,
-          ...(options.dropStaleLocks ? [] : ['--keep-stale-locks']),
-          ...(options.skipAgents ? ['--skip-agents'] : []),
-          ...(options.skipPackageJson ? ['--skip-package-json'] : []),
-          ...(options.skipGitignore ? ['--no-gitignore'] : []),
-          ...(options.dryRun ? ['--dry-run'] : []),
-          // Recursive child doctor runs should report pending PR state immediately instead of blocking the parent loop.
-          '--no-wait-for-merge',
-          ...(options.json ? ['--json'] : []),
-          ...(options.allowProtectedBaseWrite ? ['--allow-protected-base-write'] : []),
-        ],
-        { cwd: topRepoRoot },
-      );
+      const childArgs = [
+        path.resolve(__filename),
+        'doctor',
+        '--single-repo',
+        '--target',
+        repoPath,
+        ...(options.dropStaleLocks ? [] : ['--keep-stale-locks']),
+        ...(options.skipAgents ? ['--skip-agents'] : []),
+        ...(options.skipPackageJson ? ['--skip-package-json'] : []),
+        ...(options.skipGitignore ? ['--no-gitignore'] : []),
+        ...(options.dryRun ? ['--dry-run'] : []),
+        // Recursive child doctor runs should report pending PR state immediately instead of blocking the parent loop.
+        '--no-wait-for-merge',
+        ...(options.verboseAutoFinish ? ['--verbose-auto-finish'] : []),
+        ...(options.json ? ['--json'] : []),
+        ...(options.allowProtectedBaseWrite ? ['--allow-protected-base-write'] : []),
+      ];
+      const startedAt = Date.now();
+      const nestedResult = options.json
+        ? run(process.execPath, childArgs, { cwd: topRepoRoot })
+        : cp.spawnSync(process.execPath, childArgs, {
+          cwd: topRepoRoot,
+          encoding: 'utf8',
+          stdio: 'inherit',
+        });
       if (isSpawnFailure(nestedResult)) {
         throw nestedResult.error;
       }
@@ -5181,9 +5397,12 @@ function doctor(rawArgs) {
             },
         );
       } else {
-        if (nestedResult.stdout) process.stdout.write(nestedResult.stdout);
-        if (nestedResult.stderr) process.stderr.write(nestedResult.stderr);
-        process.stdout.write('\n');
+        console.log(
+          `[${TOOL_NAME}] Doctor target complete: ${repoPath} [${progressLabel}] in ${formatElapsedDuration(Date.now() - startedAt)}.`,
+        );
+        if (repoIndex < discoveredRepos.length - 1) {
+          process.stdout.write('\n');
+        }
       }
     }
 
@@ -5232,6 +5451,7 @@ function doctor(rawArgs) {
     : autoFinishReadyAgentBranches(scanResult.repoRoot, {
       baseBranch: currentBaseBranch,
       dryRun: singleRepoOptions.dryRun,
+      waitForMerge: singleRepoOptions.waitForMerge,
     });
   const safe = scanResult.guardexEnabled === false || (scanResult.errors === 0 && scanResult.warnings === 0);
   const musafe = safe;
@@ -5273,16 +5493,10 @@ function doctor(rawArgs) {
     setExitCodeFromScan(scanResult);
     return;
   }
-  if (autoFinishSummary.enabled) {
-    console.log(
-      `[${TOOL_NAME}] Auto-finish sweep (base=${currentBaseBranch}): attempted=${autoFinishSummary.attempted}, completed=${autoFinishSummary.completed}, skipped=${autoFinishSummary.skipped}, failed=${autoFinishSummary.failed}`,
-    );
-    for (const detail of autoFinishSummary.details) {
-      console.log(`[${TOOL_NAME}]   ${detail}`);
-    }
-  } else if (autoFinishSummary.details.length > 0) {
-    console.log(`[${TOOL_NAME}] ${autoFinishSummary.details[0]}`);
-  }
+  printAutoFinishSummary(autoFinishSummary, {
+    baseBranch: currentBaseBranch,
+    verbose: singleRepoOptions.verboseAutoFinish,
+  });
   if (safe) {
     console.log(`[${TOOL_NAME}] ✅ Repo is fully safe.`);
   } else {
@@ -6458,6 +6672,46 @@ function cleanup(rawArgs) {
   process.exitCode = 0;
 }
 
+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 = [mergeScript];
+  if (options.base) {
+    args.push('--base', options.base);
+  }
+  if (options.into) {
+    args.push('--into', options.into);
+  }
+  if (options.task) {
+    args.push('--task', options.task);
+  }
+  if (options.agent) {
+    args.push('--agent', options.agent);
+  }
+  for (const branch of options.branches) {
+    args.push('--branch', branch);
+  }
+
+  const mergeResult = run('bash', args, { cwd: repoRoot, stdio: 'pipe' });
+  if (mergeResult.stdout) {
+    process.stdout.write(mergeResult.stdout);
+  }
+  if (mergeResult.stderr) {
+    process.stderr.write(mergeResult.stderr);
+  }
+  if (mergeResult.status !== 0) {
+    throw new Error(`merge command failed with status ${mergeResult.status}`);
+  }
+
+  process.exitCode = 0;
+}
+
 function finish(rawArgs) {
   const options = parseFinishArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);
@@ -6944,6 +7198,7 @@ function main() {
   if (command === 'prompt') return prompt(rest);
   if (command === 'doctor') return doctor(rest);
   if (command === 'agents') return agents(rest);
+  if (command === 'merge') return merge(rest);
   if (command === 'finish') return finish(rest);
   if (command === 'report') return report(rest);
   if (command === 'protect') return protect(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.15",
+  "version": "7.0.16",
   "description": "GitGuardex: hardened multi-agent git guardrails for parallel agent work.",
   "license": "MIT",
   "preferGlobal": true,
@@ -15,6 +15,7 @@
     "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:branch:merge": "bash ./scripts/agent-branch-merge.sh",
     "agent:cleanup": "gx cleanup",
     "agent:hooks:install": "bash ./scripts/install-agent-git-hooks.sh",
     "agent:locks:claim": "python3 ./scripts/agent-file-locks.py claim",

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

@@ -0,0 +1,421 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_BRANCH=""
+BASE_BRANCH_EXPLICIT=0
+TARGET_BRANCH=""
+TASK_NAME=""
+AGENT_NAME="${GUARDEX_MERGE_AGENT_NAME:-codex}"
+declare -a SOURCE_BRANCHES=()
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/agent-branch-merge.sh --branch <agent/...> [--branch <agent/...> ...] [--into <agent/...>] [--task <task>] [--agent <agent>] [--base <branch>]
+
+Examples:
+  bash scripts/agent-branch-merge.sh --branch agent/codex/ui-a --branch agent/codex/ui-b
+  bash scripts/agent-branch-merge.sh --into agent/codex/owner-lane --branch agent/codex/helper-a --branch agent/codex/helper-b
+EOF
+}
+
+sanitize_slug() {
+  local raw="$1"
+  local fallback="${2:-merge-agent-branches}"
+  local slug
+  slug="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
+  if [[ -z "$slug" ]]; then
+    slug="$fallback"
+  fi
+  printf '%s' "$slug"
+}
+
+resolve_base_branch() {
+  local repo="$1"
+  local explicit_target="$2"
+  local configured=""
+  local branch_base=""
+
+  if [[ -n "$explicit_target" ]]; then
+    branch_base="$(git -C "$repo" config --get "branch.${explicit_target}.guardexBase" || true)"
+    if [[ -n "$branch_base" ]]; then
+      printf '%s' "$branch_base"
+      return 0
+    fi
+  fi
+
+  configured="$(git -C "$repo" config --get multiagent.baseBranch || true)"
+  if [[ -n "$configured" ]]; then
+    printf '%s' "$configured"
+    return 0
+  fi
+
+  for fallback in dev main master; do
+    if git -C "$repo" show-ref --verify --quiet "refs/heads/${fallback}" \
+      || git -C "$repo" show-ref --verify --quiet "refs/remotes/origin/${fallback}"; then
+      printf '%s' "$fallback"
+      return 0
+    fi
+  done
+
+  printf '%s' "dev"
+}
+
+get_worktree_for_branch() {
+  local repo="$1"
+  local branch="$2"
+  git -C "$repo" worktree list --porcelain | awk -v target="refs/heads/${branch}" '
+    $1 == "worktree" { wt = $2 }
+    $1 == "branch" && $2 == target { print wt; exit }
+  '
+}
+
+is_clean_worktree() {
+  local wt="$1"
+  git -C "$wt" diff --quiet -- . ":(exclude).omx/state/agent-file-locks.json" \
+    && git -C "$wt" diff --cached --quiet -- . ":(exclude).omx/state/agent-file-locks.json" \
+    && [[ -z "$(git -C "$wt" ls-files --others --exclude-standard)" ]]
+}
+
+has_in_progress_git_op() {
+  local wt="$1"
+  local git_dir=""
+  git_dir="$(git -C "$wt" rev-parse --git-dir 2>/dev/null || true)"
+  if [[ -z "$git_dir" ]]; then
+    return 1
+  fi
+  if [[ "$git_dir" != /* ]]; then
+    git_dir="$(cd "$wt/$git_dir" 2>/dev/null && pwd -P || true)"
+  fi
+  if [[ -z "$git_dir" ]]; then
+    return 1
+  fi
+  [[ -f "${git_dir}/MERGE_HEAD" || -d "${git_dir}/rebase-merge" || -d "${git_dir}/rebase-apply" ]]
+}
+
+select_unique_worktree_path() {
+  local root="$1"
+  local name="$2"
+  local candidate="${root}/${name}"
+  local suffix=2
+  while [[ -e "$candidate" ]]; do
+    candidate="${root}/${name}-${suffix}"
+    suffix=$((suffix + 1))
+  done
+  printf '%s' "$candidate"
+}
+
+branch_exists() {
+  local repo="$1"
+  local branch="$2"
+  git -C "$repo" show-ref --verify --quiet "refs/heads/${branch}"
+}
+
+branch_is_agent_lane() {
+  local branch="$1"
+  [[ "$branch" == agent/* ]]
+}
+
+array_contains() {
+  local needle="$1"
+  shift || true
+  local item
+  for item in "$@"; do
+    if [[ "$item" == "$needle" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+collect_branch_files() {
+  local repo="$1"
+  local base_ref="$2"
+  local branch="$3"
+  git -C "$repo" diff --name-only "${base_ref}...${branch}" -- . ":(exclude).omx/state/agent-file-locks.json" 2>/dev/null || true
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --base)
+      BASE_BRANCH="${2:-}"
+      BASE_BRANCH_EXPLICIT=1
+      shift 2
+      ;;
+    --into)
+      TARGET_BRANCH="${2:-}"
+      shift 2
+      ;;
+    --branch)
+      SOURCE_BRANCHES+=("${2:-}")
+      shift 2
+      ;;
+    --task)
+      TASK_NAME="${2:-}"
+      shift 2
+      ;;
+    --agent)
+      AGENT_NAME="${2:-codex}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "[agent-branch-merge] Unknown argument: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "[agent-branch-merge] Not inside a git repository." >&2
+  exit 1
+fi
+
+repo_root="$(git rev-parse --show-toplevel)"
+common_git_dir_raw="$(git -C "$repo_root" rev-parse --git-common-dir)"
+if [[ "$common_git_dir_raw" == /* ]]; then
+  common_git_dir="$common_git_dir_raw"
+else
+  common_git_dir="$(cd "$repo_root/$common_git_dir_raw" && pwd -P)"
+fi
+repo_common_root="$(cd "$common_git_dir/.." && pwd -P)"
+agent_worktree_root="${repo_common_root}/.omx/agent-worktrees"
+mkdir -p "$agent_worktree_root"
+
+if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
+  echo "[agent-branch-merge] --base requires a branch value." >&2
+  exit 1
+fi
+
+if [[ -z "$TARGET_BRANCH" && "${#SOURCE_BRANCHES[@]}" -lt 1 ]]; then
+  echo "[agent-branch-merge] Provide at least one --branch <agent/...> source lane." >&2
+  exit 1
+fi
+
+if [[ -n "$TARGET_BRANCH" ]] && ! branch_is_agent_lane "$TARGET_BRANCH"; then
+  echo "[agent-branch-merge] --into must reference an agent/* branch: ${TARGET_BRANCH}" >&2
+  exit 1
+fi
+
+deduped_sources=()
+for branch in "${SOURCE_BRANCHES[@]}"; do
+  if [[ -z "$branch" ]]; then
+    echo "[agent-branch-merge] --branch requires an agent/* branch value." >&2
+    exit 1
+  fi
+  if ! branch_is_agent_lane "$branch"; then
+    echo "[agent-branch-merge] Source branch must be agent/*: ${branch}" >&2
+    exit 1
+  fi
+  if ! branch_exists "$repo_root" "$branch"; then
+    echo "[agent-branch-merge] Local source branch not found: ${branch}" >&2
+    exit 1
+  fi
+  if ! array_contains "$branch" "${deduped_sources[@]}"; then
+    deduped_sources+=("$branch")
+  fi
+done
+SOURCE_BRANCHES=("${deduped_sources[@]}")
+
+if [[ "${#SOURCE_BRANCHES[@]}" -eq 0 ]]; then
+  echo "[agent-branch-merge] No unique source branches were provided." >&2
+  exit 1
+fi
+
+if [[ "$BASE_BRANCH_EXPLICIT" -eq 0 ]]; then
+  BASE_BRANCH="$(resolve_base_branch "$repo_root" "$TARGET_BRANCH")"
+fi
+
+if [[ -z "$BASE_BRANCH" ]]; then
+  echo "[agent-branch-merge] Unable to resolve a base branch." >&2
+  exit 1
+fi
+
+start_ref="$BASE_BRANCH"
+if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
+  git -C "$repo_root" fetch origin "$BASE_BRANCH" --quiet
+  start_ref="origin/${BASE_BRANCH}"
+elif ! git -C "$repo_root" show-ref --verify --quiet "refs/heads/${BASE_BRANCH}"; then
+  echo "[agent-branch-merge] Base branch not found locally or on origin: ${BASE_BRANCH}" >&2
+  exit 1
+fi
+
+target_worktree=""
+target_created=0
+
+if [[ -z "$TARGET_BRANCH" ]]; then
+  if [[ -z "$TASK_NAME" ]]; then
+    first_hint="$(printf '%s' "${SOURCE_BRANCHES[0]}" | sed -E 's#^agent/[^/]+/##; s#^agent/##')"
+    source_count="${#SOURCE_BRANCHES[@]}"
+    if [[ "$source_count" -gt 1 ]]; then
+      TASK_NAME="$(sanitize_slug "merge-${first_hint}-and-$((source_count - 1))-more" "merge-agent-branches")"
+    else
+      TASK_NAME="$(sanitize_slug "merge-${first_hint}" "merge-agent-branches")"
+    fi
+  else
+    TASK_NAME="$(sanitize_slug "$TASK_NAME" "merge-agent-branches")"
+  fi
+
+  start_output=""
+  if ! start_output="$(
+    cd "$repo_root"
+    env GUARDEX_OPENSPEC_AUTO_INIT=1 bash "scripts/agent-branch-start.sh" "$TASK_NAME" "$AGENT_NAME" "$BASE_BRANCH" 2>&1
+  )"; then
+    printf '%s\n' "$start_output" >&2
+    exit 1
+  fi
+
+  printf '%s\n' "$start_output"
+  TARGET_BRANCH="$(printf '%s\n' "$start_output" | sed -n 's/^\[agent-branch-start\] Created branch: //p' | head -n 1)"
+  target_worktree="$(printf '%s\n' "$start_output" | sed -n 's/^\[agent-branch-start\] Worktree: //p' | head -n 1)"
+  if [[ -z "$TARGET_BRANCH" || -z "$target_worktree" ]]; then
+    echo "[agent-branch-merge] Unable to parse target branch/worktree from agent-branch-start output." >&2
+    exit 1
+  fi
+  target_created=1
+else
+  if ! branch_exists "$repo_root" "$TARGET_BRANCH"; then
+    echo "[agent-branch-merge] Target branch not found: ${TARGET_BRANCH}" >&2
+    exit 1
+  fi
+
+  target_worktree="$(get_worktree_for_branch "$repo_root" "$TARGET_BRANCH")"
+  if [[ -z "$target_worktree" ]]; then
+    target_worktree="$(select_unique_worktree_path "$agent_worktree_root" "${TARGET_BRANCH//\//__}")"
+    git -C "$repo_root" worktree add "$target_worktree" "$TARGET_BRANCH" >/dev/null
+    target_created=1
+    echo "[agent-branch-merge] Attached worktree for target branch '${TARGET_BRANCH}': ${target_worktree}"
+  fi
+fi
+
+if [[ "$TARGET_BRANCH" == "$BASE_BRANCH" ]]; then
+  echo "[agent-branch-merge] Target branch must not equal the protected base branch '${BASE_BRANCH}'." >&2
+  exit 1
+fi
+
+if ! is_clean_worktree "$target_worktree"; then
+  if [[ "$target_created" -eq 1 ]]; then
+    echo "[agent-branch-merge] Target worktree has freshly generated scaffold changes; continuing inside the new integration lane."
+  else
+    echo "[agent-branch-merge] Target worktree is not clean: ${target_worktree}" >&2
+    echo "[agent-branch-merge] Commit, stash, or discard local changes before merging agent lanes." >&2
+    exit 1
+  fi
+fi
+
+if has_in_progress_git_op "$target_worktree"; then
+  echo "[agent-branch-merge] Target worktree has an in-progress merge/rebase: ${target_worktree}" >&2
+  echo "[agent-branch-merge] Resolve or abort that git operation before running the merge workflow." >&2
+  exit 1
+fi
+
+for source_branch in "${SOURCE_BRANCHES[@]}"; do
+  if [[ "$source_branch" == "$TARGET_BRANCH" ]]; then
+    echo "[agent-branch-merge] Source branch list includes the target branch: ${source_branch}" >&2
+    exit 1
+  fi
+  source_worktree="$(get_worktree_for_branch "$repo_root" "$source_branch")"
+  if [[ -n "$source_worktree" ]] && ! is_clean_worktree "$source_worktree"; then
+    echo "[agent-branch-merge] Source worktree is not clean for '${source_branch}': ${source_worktree}" >&2
+    echo "[agent-branch-merge] Commit or stash source-lane changes before integration." >&2
+    exit 1
+  fi
+done
+
+pending_branches=()
+for source_branch in "${SOURCE_BRANCHES[@]}"; do
+  if git -C "$repo_root" merge-base --is-ancestor "$source_branch" "$TARGET_BRANCH" >/dev/null 2>&1; then
+    echo "[agent-branch-merge] Skipping '${source_branch}' because it is already integrated into '${TARGET_BRANCH}'."
+    continue
+  fi
+  pending_branches+=("$source_branch")
+done
+
+if [[ "${#pending_branches[@]}" -eq 0 ]]; then
+  echo "[agent-branch-merge] No pending source branches remain for target '${TARGET_BRANCH}'."
+  echo "[agent-branch-merge] Target worktree: ${target_worktree}"
+  exit 0
+fi
+
+declare -A file_to_branches=()
+declare -a overlap_files=()
+for source_branch in "${pending_branches[@]}"; do
+  while IFS= read -r changed_file; do
+    [[ -z "$changed_file" ]] && continue
+    existing="${file_to_branches[$changed_file]:-}"
+    if [[ -z "$existing" ]]; then
+      file_to_branches["$changed_file"]="$source_branch"
+      continue
+    fi
+    if [[ ",${existing}," == *",${source_branch},"* ]]; then
+      continue
+    fi
+    file_to_branches["$changed_file"]="${existing},${source_branch}"
+    if ! array_contains "$changed_file" "${overlap_files[@]}"; then
+      overlap_files+=("$changed_file")
+    fi
+  done < <(collect_branch_files "$repo_root" "$start_ref" "$source_branch")
+done
+
+echo "[agent-branch-merge] Target branch: ${TARGET_BRANCH}"
+echo "[agent-branch-merge] Target worktree: ${target_worktree}"
+echo "[agent-branch-merge] Base branch: ${BASE_BRANCH} (${start_ref})"
+echo "[agent-branch-merge] Merge order: ${pending_branches[*]}"
+
+if [[ "${#overlap_files[@]}" -gt 0 ]]; then
+  echo "[agent-branch-merge] Overlapping changed files detected across requested branches:"
+  for overlap_file in "${overlap_files[@]}"; do
+    branches_csv="${file_to_branches[$overlap_file]}"
+    branches_display="$(printf '%s' "$branches_csv" | sed 's/,/, /g')"
+    echo "  - ${overlap_file} <- ${branches_display}"
+  done
+else
+  echo "[agent-branch-merge] No overlapping changed files detected across requested branches."
+fi
+
+for index in "${!pending_branches[@]}"; do
+  source_branch="${pending_branches[$index]}"
+  echo "[agent-branch-merge] Merging '${source_branch}' into '${TARGET_BRANCH}'..."
+  if git -C "$target_worktree" merge --no-ff --no-edit "$source_branch"; then
+    echo "[agent-branch-merge] Merged '${source_branch}'."
+    continue
+  fi
+
+  conflict_files="$(git -C "$target_worktree" diff --name-only --diff-filter=U || true)"
+  echo "[agent-branch-merge] Merge conflict detected while merging '${source_branch}' into '${TARGET_BRANCH}'." >&2
+  echo "[agent-branch-merge] Target worktree: ${target_worktree}" >&2
+  if [[ -n "$conflict_files" ]]; then
+    echo "[agent-branch-merge] Conflicting files:" >&2
+    while IFS= read -r conflict_file; do
+      [[ -n "$conflict_file" ]] && echo "  - ${conflict_file}" >&2
+    done <<< "$conflict_files"
+  fi
+  echo "[agent-branch-merge] Resolve or abort inside the integration worktree:" >&2
+  echo "  cd \"${target_worktree}\"" >&2
+  echo "  git status" >&2
+  echo "  git add <resolved-files> && git commit" >&2
+  echo "  # or: git merge --abort" >&2
+
+  remaining_branches=("${pending_branches[@]:$((index + 1))}")
+  if [[ "${#remaining_branches[@]}" -gt 0 ]]; then
+    echo "[agent-branch-merge] Remaining branches:" >&2
+    for remaining in "${remaining_branches[@]}"; do
+      echo "  - ${remaining}" >&2
+    done
+    resume_cmd="gx merge --into ${TARGET_BRANCH} --base ${BASE_BRANCH}"
+    for remaining in "${remaining_branches[@]}"; do
+      resume_cmd="${resume_cmd} --branch ${remaining}"
+    done
+    echo "[agent-branch-merge] Resume after resolving with: ${resume_cmd}" >&2
+  fi
+  exit 1
+done
+
+echo "[agent-branch-merge] Merge sequence complete for '${TARGET_BRANCH}'."
+if [[ "$target_created" -eq 1 ]]; then
+  echo "[agent-branch-merge] Review and verify in '${target_worktree}', then finish the integration branch when ready."
+fi
+echo "[agent-branch-merge] Next step: bash scripts/agent-branch-finish.sh --branch \"${TARGET_BRANCH}\" --base \"${BASE_BRANCH}\" --via-pr --wait-for-merge --cleanup"

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

@@ -11,6 +11,7 @@ OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-false}"
 OPENSPEC_PLAN_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_PLAN_SLUG:-}"
 OPENSPEC_CHANGE_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CHANGE_SLUG:-}"
 OPENSPEC_CAPABILITY_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CAPABILITY_SLUG:-}"
+OPENSPEC_MASTERPLAN_LABEL_RAW="${GUARDEX_OPENSPEC_MASTERPLAN_LABEL-masterplan}"
 PRINT_NAME_ONLY=0
 POSITIONAL_ARGS=()
 
@@ -226,13 +227,35 @@ normalize_bool() {
 
 OPENSPEC_AUTO_INIT="$(normalize_bool "$OPENSPEC_AUTO_INIT_RAW" "1")"
 
+resolve_openspec_masterplan_label() {
+  local raw="${OPENSPEC_MASTERPLAN_LABEL_RAW:-}"
+  local label
+
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ -z "$raw" ]]; then
+    printf ''
+    return 0
+  fi
+
+  label="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
+  printf '%s' "$label"
+}
+
 resolve_openspec_plan_slug() {
   local branch_name="$1"
-  local task_slug="$2"
+  local agent_slug="$2"
+  local task_slug="$3"
+  local masterplan_label=""
+  local branch_leaf=""
   if [[ -n "$OPENSPEC_PLAN_SLUG_OVERRIDE" ]]; then
     sanitize_slug "$OPENSPEC_PLAN_SLUG_OVERRIDE" "$task_slug"
     return 0
   fi
+  masterplan_label="$(resolve_openspec_masterplan_label)"
+  if [[ -n "$masterplan_label" ]] && [[ "$branch_name" == "agent/${agent_slug}/"* ]]; then
+    branch_leaf="${branch_name#agent/${agent_slug}/}"
+    sanitize_slug "agent-${agent_slug}-${masterplan_label}-${branch_leaf}" "$task_slug"
+    return 0
+  fi
   sanitize_slug "${branch_name//\//-}" "$task_slug"
 }
 
@@ -255,6 +278,22 @@ resolve_openspec_capability_slug() {
   sanitize_slug "$task_slug" "general-behavior"
 }
 
+resolve_worktree_leaf() {
+  local branch_name="$1"
+  local agent_slug="$2"
+  local masterplan_label=""
+  local branch_leaf=""
+
+  masterplan_label="$(resolve_openspec_masterplan_label)"
+  if [[ -n "$masterplan_label" ]] && [[ "$branch_name" == "agent/${agent_slug}/"* ]]; then
+    branch_leaf="${branch_name#agent/${agent_slug}/}"
+    printf 'agent__%s__%s__%s' "$agent_slug" "$masterplan_label" "$branch_leaf"
+    return 0
+  fi
+
+  printf '%s' "${branch_name//\//__}"
+}
+
 has_local_changes() {
   local root="$1"
   if ! git -C "$root" diff --quiet; then
@@ -497,8 +536,9 @@ 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")"
+worktree_leaf="$(resolve_worktree_leaf "$branch_name" "$agent_slug")"
+worktree_path="${worktree_root}/${worktree_leaf}"
+openspec_plan_slug="$(resolve_openspec_plan_slug "$branch_name" "$agent_slug" "$task_slug")"
 openspec_change_slug="$(resolve_openspec_change_slug "$branch_name" "$task_slug")"
 openspec_capability_slug="$(resolve_openspec_capability_slug "$task_slug")"
 

package/templates/scripts/codex-agent.sh

@@ -14,6 +14,7 @@ OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-true}"
 OPENSPEC_PLAN_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_PLAN_SLUG:-}"
 OPENSPEC_CHANGE_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CHANGE_SLUG:-}"
 OPENSPEC_CAPABILITY_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CAPABILITY_SLUG:-}"
+OPENSPEC_MASTERPLAN_LABEL_RAW="${GUARDEX_OPENSPEC_MASTERPLAN_LABEL-masterplan}"
 
 normalize_bool() {
   local raw="${1:-}"
@@ -34,6 +35,19 @@ 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")"
 
+resolve_openspec_masterplan_label() {
+  local raw="${OPENSPEC_MASTERPLAN_LABEL_RAW:-}"
+  local label
+
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ -z "$raw" ]]; then
+    printf ''
+    return 0
+  fi
+
+  label="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
+  printf '%s' "$label"
+}
+
 if [[ -n "$BASE_BRANCH" ]]; then
   BASE_BRANCH_EXPLICIT=1
 fi
@@ -161,11 +175,21 @@ sanitize_slug() {
 resolve_openspec_plan_slug() {
   local branch_name="$1"
   local task_slug
+  local masterplan_label=""
+  local branch_role=""
+  local branch_leaf=""
   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
+  masterplan_label="$(resolve_openspec_masterplan_label)"
+  if [[ -n "$masterplan_label" ]] && [[ "$branch_name" =~ ^agent/([^/]+)/(.+)$ ]]; then
+    branch_role="${BASH_REMATCH[1]}"
+    branch_leaf="${BASH_REMATCH[2]}"
+    sanitize_slug "agent-${branch_role}-${masterplan_label}-${branch_leaf}" "$task_slug"
+    return 0
+  fi
   sanitize_slug "${branch_name//\//-}" "$task_slug"
 }
 
@@ -190,6 +214,23 @@ resolve_openspec_capability_slug() {
   sanitize_slug "$task_slug" "general-behavior"
 }
 
+resolve_worktree_leaf() {
+  local branch_name="$1"
+  local masterplan_label=""
+  local branch_role=""
+  local branch_leaf=""
+
+  masterplan_label="$(resolve_openspec_masterplan_label)"
+  if [[ -n "$masterplan_label" ]] && [[ "$branch_name" =~ ^agent/([^/]+)/(.+)$ ]]; then
+    branch_role="${BASH_REMATCH[1]}"
+    branch_leaf="${BASH_REMATCH[2]}"
+    printf 'agent__%s__%s__%s' "$branch_role" "$masterplan_label" "$branch_leaf"
+    return 0
+  fi
+
+  printf '%s' "${branch_name//\//__}"
+}
+
 hydrate_local_helper_in_worktree() {
   local worktree="$1"
   local relative_path="$2"
@@ -314,7 +355,7 @@ start_sandbox_fallback() {
 
   worktree_root="${repo_root}/.omx/agent-worktrees"
   mkdir -p "$worktree_root"
-  worktree_path="${worktree_root}/${branch_name//\//__}"
+  worktree_path="${worktree_root}/$(resolve_worktree_leaf "$branch_name")"
   if [[ -e "$worktree_path" ]]; then
     echo "[codex-agent] Fallback worktree path already exists: $worktree_path" >&2
     return 1
@@ -346,7 +387,11 @@ initial_repo_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/nu
 start_output=""
 start_status=0
 set +e
-start_output="$(GUARDEX_OPENSPEC_AUTO_INIT=0 bash "${repo_root}/scripts/agent-branch-start.sh" "${start_args[@]}" 2>&1)"
+start_output="$(
+  GUARDEX_OPENSPEC_AUTO_INIT="$OPENSPEC_AUTO_INIT" \
+  GUARDEX_OPENSPEC_MASTERPLAN_LABEL="$OPENSPEC_MASTERPLAN_LABEL_RAW" \
+  bash "${repo_root}/scripts/agent-branch-start.sh" "${start_args[@]}" 2>&1
+)"
 start_status=$?
 set -e
 

package/templates/scripts/openspec/init-plan-workspace.sh

@@ -54,6 +54,10 @@ write_if_missing "$PLAN_DIR/README.md" "# Plan Workspace: ${PLAN_SLUG}
 
 Durable pre-implementation planning workspace.
 
+Each role folder includes a copyable \`prompt.md\` for joined Codex helpers.
+Helpers reuse the owner branch/worktree, claim the role files they touch, and
+leave PR merge + sandbox cleanup to the owner change lane.
+
 Use this command to update checkpoints:
 
 \`\`\`bash
@@ -89,10 +93,39 @@ for role in "${ROLES[@]}"; do
   write_if_missing "$ROLE_DIR/README.md" "# ${role}
 
 Role workspace for \`${role}\`.
+"
+
+  write_if_missing "$ROLE_DIR/prompt.md" "# ${role} prompt
+
+You are the \`${role}\` lane for shared plan \`${PLAN_SLUG}\`.
+
+## Scope
+
+- Work inside \`openspec/plan/${PLAN_SLUG}/${role}/\` plus directly-related shared plan files you explicitly claim.
+- Reuse the owner's branch/worktree instead of creating a separate sandbox unless the owner says otherwise.
+
+## Ownership
+
+- Before editing, claim this role's files in the shared owner lane:
+  \`python3 scripts/agent-file-locks.py claim --branch <owner-branch> openspec/plan/${PLAN_SLUG}/${role}/README.md openspec/plan/${PLAN_SLUG}/${role}/prompt.md openspec/plan/${PLAN_SLUG}/${role}/tasks.md openspec/plan/${PLAN_SLUG}/checkpoints.md\`
+- Record branch, worktree, and scope in \`tasks.md\`.
+- Do not change another role's files without reassignment.
+
+## Deliverables
+
+- Complete the role checklist in \`tasks.md\`.
+- Leave a handoff with files changed, verification, and risks.
+- The owner alone runs the change completion flow and sandbox cleanup after change tasks 4.1-4.3 are done.
 "
 
   write_if_missing "$ROLE_DIR/tasks.md" "# ${role} tasks
 
+## Ownership
+
+- [ ] Claim this role's files in the shared owner branch/worktree before editing.
+- [ ] Record branch, worktree, and scope for this role.
+- [ ] Copy or hand off \`prompt.md\` when another agent joins this role.
+
 ## 1. Spec
 
 - [ ] Define requirements and scope for ${role}
@@ -111,6 +144,15 @@ Role workspace for \`${role}\`.
 ## 4. Checkpoints
 
 - [ ] Publish checkpoint update for this role
+
+## 5. Collaboration
+
+- [ ] Leave a role handoff with files changed, verification, and risks.
+- [ ] Owner records \`accept\`, \`revise\`, or \`reject\` for joined output, or marks \`N/A\` if no helper joined.
+
+## 6. Completion
+
+- [ ] Keep sandbox cleanup blocked until change tasks 4.1-4.3 are complete.
 "
 done