@imdeadpool/guardex 7.0.26 → 7.0.31

package/src/doctor/index.js

@@ -31,6 +31,7 @@ const {
 } = require('../sandbox');
 const { ensureOmxScaffold, configureHooks } = require('../scaffold');
 const { detectRecoverableAutoFinishConflict, printAutoFinishSummary } = require('../output');
+const { autoCommitWorktreeForFinish } = require('../finish');
 
 /**
  * @typedef {Object} SandboxMetadata
@@ -887,23 +888,25 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
     return summary;
   }
 
-  if (!hasOriginRemote(repoRoot)) {
-    summary.enabled = false;
-    summary.details.push('Skipped auto-finish sweep (origin remote missing).');
-    return summary;
-  }
+  const originAvailable = hasOriginRemote(repoRoot);
   const explicitGhBin = Boolean(String(process.env.GUARDEX_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.GUARDEX_GH_BIN || 'gh';
-  if (run(ghBin, ['--version']).status !== 0) {
-    summary.enabled = false;
-    summary.details.push(`Skipped auto-finish sweep (${ghBin} not available).`);
-    return summary;
+  const ghAvailable =
+    originAvailable &&
+    (explicitGhBin || originRemoteLooksLikeGithub(repoRoot)) &&
+    run(ghBin, ['--version']).status === 0;
+
+  let fallbackMode = '';
+  if (!originAvailable) {
+    fallbackMode = 'local';
+    summary.details.push('origin remote missing; falling back to local direct merge (no push, no PR).');
+  } else if (!ghAvailable) {
+    fallbackMode = 'direct';
+    if (!explicitGhBin && !originRemoteLooksLikeGithub(repoRoot)) {
+      summary.details.push('origin remote is not GitHub; falling back to direct merge + push.');
+    } else {
+      summary.details.push(`${ghBin} not available; falling back to direct merge + push.`);
+    }
   }
 
   const branchWorktrees = mapWorktreePathsByBranch(repoRoot);
@@ -936,16 +939,29 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
       continue;
     }
 
+    const branchWorktree = branchWorktrees.get(branch) || '';
+    if (branchWorktree && hasSignificantWorkingTreeChanges(branchWorktree)) {
+      try {
+        const commitResult = autoCommitWorktreeForFinish(repoRoot, branchWorktree, branch, {});
+        if (commitResult.committed) {
+          counts = aheadBehind(repoRoot, branch, baseBranch);
+        }
+      } catch (error) {
+        summary.failed += 1;
+        summary.details.push(`[fail] ${branch}: auto-commit failed (${error.message}).`);
+        continue;
+      }
+    }
+
     if (counts.ahead <= 0) {
       summary.skipped += 1;
       summary.details.push(`[skip] ${branch}: already merged into ${baseBranch}.`);
       continue;
     }
 
-    const branchWorktree = branchWorktrees.get(branch) || '';
     if (branchWorktree && hasSignificantWorkingTreeChanges(branchWorktree)) {
       summary.skipped += 1;
-      summary.details.push(`[skip] ${branch}: dirty worktree (${branchWorktree}).`);
+      summary.details.push(`[skip] ${branch}: dirty worktree after auto-commit (${branchWorktree}).`);
       continue;
     }
 
@@ -955,10 +971,16 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
       branch,
       '--base',
       baseBranch,
-      '--via-pr',
-      waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge',
-      '--cleanup',
     ];
+    if (fallbackMode === 'local') {
+      finishArgs.push('--direct-only', '--no-push');
+    } else if (fallbackMode === 'direct') {
+      finishArgs.push('--direct-only');
+    } else {
+      finishArgs.push('--via-pr');
+    }
+    finishArgs.push(waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge');
+    finishArgs.push('--cleanup');
     const finishResult = runPackageAsset('branchFinish', finishArgs, { cwd: repoRoot });
     const combinedOutput = [finishResult.stdout || '', finishResult.stderr || ''].join('\n').trim();
 

package/src/finish/index.js

@@ -521,4 +521,5 @@ module.exports = {
   merge,
   finish,
   sync,
+  autoCommitWorktreeForFinish,
 };

package/src/output/index.js

@@ -6,6 +6,8 @@ const {
   LEGACY_NAMES,
   GUARDEX_REPO_TOGGLE_ENV,
   CLI_COMMAND_DESCRIPTIONS,
+  CLI_COMMAND_GROUPS,
+  CLI_QUICKSTART_STEPS,
   AGENT_BOT_DESCRIPTIONS,
   DOCTOR_AUTO_FINISH_DETAIL_LIMIT,
   DOCTOR_AUTO_FINISH_BRANCH_LABEL_MAX,
@@ -166,6 +168,41 @@ function commandCatalogLines(indent = '  ') {
   );
 }
 
+// groupedCommandCatalogLines renders CLI_COMMAND_GROUPS as a nested list with
+// group headers separated by blank lines. It accepts an optional `colorize`
+// callback so the caller can decide whether to decorate the group label (tty
+// mode) or leave it plain (non-tty / NO_COLOR). Returns an array of lines;
+// `null` entries mean "emit a blank line" so tree renderers can echo pipe
+// characters on the separator rows.
+function groupedCommandCatalogLines(indent = '  ', options = {}) {
+  const colorizeLabel = typeof options.colorizeLabel === 'function'
+    ? options.colorizeLabel
+    : (text) => text;
+  const maxCommandLength = CLI_COMMAND_DESCRIPTIONS.reduce(
+    (max, [command]) => Math.max(max, command.length),
+    0,
+  );
+  const lines = [];
+  for (let groupIndex = 0; groupIndex < CLI_COMMAND_GROUPS.length; groupIndex += 1) {
+    const group = CLI_COMMAND_GROUPS[groupIndex];
+    const header = group.description
+      ? `${colorizeLabel(group.label)} — ${group.description}`
+      : colorizeLabel(group.label);
+    lines.push(`${indent}${header}`);
+    for (const [command, description] of group.commands) {
+      lines.push(`${indent}  ${command.padEnd(maxCommandLength + 2)}${description}`);
+    }
+    if (groupIndex < CLI_COMMAND_GROUPS.length - 1) {
+      lines.push(null);
+    }
+  }
+  return lines;
+}
+
+function quickstartLines(indent = '  ') {
+  return CLI_QUICKSTART_STEPS.map((step, index) => `${indent}${index + 1}. ${step}`);
+}
+
 function agentBotCatalogLines(indent = '  ') {
   const maxCommandLength = AGENT_BOT_DESCRIPTIONS.reduce(
     (max, [command]) => Math.max(max, command.length),
@@ -182,19 +219,43 @@ function repoToggleLines(indent = '  ') {
   ];
 }
 
-function printToolLogsSummary() {
-  const usageLine = `    $ ${SHORT_TOOL_NAME} <command> [options]`;
-  const commandDetails = commandCatalogLines('    ');
+const KNOWN_CLI_BASENAMES = new Set(['gx', 'gitguardex', 'guardex']);
+
+function getInvokedCliName() {
+  const raw = path.basename(String(process.argv[1] || '')).replace(/\.js$/, '');
+  if (!KNOWN_CLI_BASENAMES.has(raw)) {
+    return SHORT_TOOL_NAME;
+  }
+  return raw;
+}
+
+function printToolLogsSummary(options = {}) {
+  const invoked = options.invokedBasename || getInvokedCliName();
+  const compact = Boolean(options.compact);
+
+  if (compact) {
+    const helpLine = `Try '${invoked} help' for commands, or '${invoked} status --verbose' for full service details.`;
+    console.log(`[${TOOL_NAME}] ${colorize(helpLine, '2')}`);
+    return;
+  }
+
+  const usageLine = `    $ ${invoked} <command> [options]`;
+  const quickstartDetails = quickstartLines('    ');
   const agentBotDetails = agentBotCatalogLines('    ');
   const repoToggleDetails = repoToggleLines('    ');
 
   if (!supportsAnsiColors()) {
-    console.log(`${TOOL_NAME}-tools logs:`);
+    const commandDetails = groupedCommandCatalogLines('    ');
+    console.log(`${invoked} help:`);
     console.log('  USAGE');
     console.log(usageLine);
+    console.log('  QUICKSTART');
+    for (const line of quickstartDetails) {
+      console.log(line);
+    }
     console.log('  COMMANDS');
     for (const line of commandDetails) {
-      console.log(line);
+      console.log(line ?? '');
     }
     console.log('  AGENT BOT');
     for (const line of agentBotDetails) {
@@ -204,24 +265,33 @@ function printToolLogsSummary() {
     for (const line of repoToggleDetails) {
       console.log(line);
     }
+    console.log(`  Try '${invoked} doctor' for one-step repair + verification.`);
     return;
   }
 
-  const title = colorize(`${TOOL_NAME}-tools logs`, '1;36');
+  const title = colorize(`${invoked} help`, '1;36');
   const usageHeader = colorize('USAGE', '1');
+  const quickstartHeader = colorize('QUICKSTART', '1');
   const commandsHeader = colorize('COMMANDS', '1');
   const agentBotHeader = colorize('AGENT BOT', '1');
   const repoToggleHeader = colorize('REPO TOGGLE', '1');
   const pipe = colorize('│', '90');
   const tee = colorize('├', '90');
   const corner = colorize('└', '90');
+  const commandDetails = groupedCommandCatalogLines('    ', {
+    colorizeLabel: (text) => colorize(text, '1;36'),
+  });
 
   console.log(`${title}:`);
   console.log(`  ${tee}─ ${usageHeader}`);
   console.log(`  ${pipe}${usageLine}`);
+  console.log(`  ${tee}─ ${quickstartHeader}`);
+  for (const line of quickstartDetails) {
+    console.log(`  ${pipe}${line.slice(2)}`);
+  }
   console.log(`  ${tee}─ ${commandsHeader}`);
   for (const line of commandDetails) {
-    if (!line) {
+    if (line == null) {
       console.log(`  ${pipe}`);
       continue;
     }
@@ -243,11 +313,18 @@ function printToolLogsSummary() {
     }
     console.log(`  ${pipe}${line.slice(2)}`);
   }
-  console.log(`  ${corner}─ ${colorize(`Try '${TOOL_NAME} doctor' for one-step repair + verification.`, '2')}`);
+  console.log(`  ${corner}─ ${colorize(`Try '${invoked} doctor' for one-step repair + verification.`, '2')}`);
 }
 
 function usage(options = {}) {
   const { outsideGitRepo = false } = options;
+  const invoked = options.invokedBasename || getInvokedCliName();
+
+  const groupedCommandLines = groupedCommandCatalogLines('  ', {
+    colorizeLabel: (text) => colorize(text, '1;36'),
+  })
+    .map((line) => (line == null ? '' : line))
+    .join('\n');
 
   console.log(`A command-line tool that sets up hardened multi-agent safety for git repositories.
 
@@ -255,10 +332,13 @@ VERSION
   ${runtimeVersion()}
 
 USAGE
-  $ ${SHORT_TOOL_NAME} <command> [options]
+  $ ${invoked} <command> [options]
+
+QUICKSTART
+${quickstartLines().join('\n')}
 
 COMMANDS
-${commandCatalogLines().join('\n')}
+${groupedCommandLines}
 
 AGENT BOT
 ${agentBotCatalogLines().join('\n')}
@@ -267,19 +347,20 @@ REPO TOGGLE
 ${repoToggleLines().join('\n')}
 
 NOTES
-  - No command = ${SHORT_TOOL_NAME} status. ${SHORT_TOOL_NAME} init is an alias of ${SHORT_TOOL_NAME} setup.
+  - No command = ${invoked} status (compact in a TTY; pass --verbose for full services + help tree).
+  - ${invoked} init is an alias of ${invoked} setup.
   - Global installs need Y/N approval; GitHub CLI (gh) is required for PR automation.
-  - Target another repo: ${SHORT_TOOL_NAME} <cmd> --target <repo-path>.
+  - Target another repo: ${invoked} <cmd> --target <repo-path>.
   - On protected main, setup/install/fix/doctor auto-sandbox via agent branch + PR flow.
-  - Run '${SHORT_TOOL_NAME} cleanup' to prune merged agent branches/worktrees.
+  - Run '${invoked} cleanup' to prune merged agent branches/worktrees.
   - Legacy aliases: ${LEGACY_NAMES.join(', ')}.`);
 
   if (outsideGitRepo) {
     console.log(`
 [${TOOL_NAME}] No git repository detected in current directory.
 [${TOOL_NAME}] Start from a repo root, or pass an explicit target:
-  ${TOOL_NAME} setup --target <path-to-git-repo>
-  ${TOOL_NAME} doctor --target <path-to-git-repo>`);
+  ${invoked} setup --target <path-to-git-repo>
+  ${invoked} doctor --target <path-to-git-repo>`);
   }
 }
 
@@ -294,6 +375,59 @@ function formatElapsedDuration(ms) {
   return `${Math.round(durationMs / 1000)}s`;
 }
 
+function startTransientSpinner(message, options = {}) {
+  const stream = options.stream || process.stdout;
+  if (!stream || !stream.isTTY || typeof stream.write !== 'function') {
+    return {
+      stop() {},
+    };
+  }
+
+  const frames = supportsAnsiColors()
+    ? ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+    : ['-', '\\', '|', '/'];
+  const intervalMs = Number.isFinite(options.intervalMs) ? Math.max(60, options.intervalMs) : 80;
+  const prefix = String(options.prefix || `[${TOOL_NAME}]`).trim();
+  const text = String(message || '').trim();
+  let frameIndex = 0;
+  let stopped = false;
+
+  const render = () => {
+    const frame = frames[frameIndex % frames.length];
+    frameIndex += 1;
+    const indicator = supportsAnsiColors() ? colorize(frame, '36') : frame;
+    stream.write(`\r${prefix} ${indicator} ${text}`);
+  };
+
+  const clear = () => {
+    stream.write('\r');
+    if (typeof stream.clearLine === 'function') {
+      stream.clearLine(0);
+    }
+    if (typeof stream.cursorTo === 'function') {
+      stream.cursorTo(0);
+    }
+  };
+
+  render();
+  const timer = setInterval(render, intervalMs);
+  if (typeof timer.unref === 'function') {
+    timer.unref();
+  }
+
+  return {
+    stop(finalLine = '') {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      clear();
+      if (finalLine) {
+        stream.write(`${finalLine}\n`);
+      }
+    },
+  };
+}
+
 function truncateMiddle(value, maxLength) {
   const text = String(value || '');
   const limit = Number.isFinite(maxLength) ? Math.max(4, maxLength) : 0;
@@ -454,8 +588,10 @@ module.exports = {
   agentBotCatalogLines,
   repoToggleLines,
   printToolLogsSummary,
+  getInvokedCliName,
   usage,
   formatElapsedDuration,
+  startTransientSpinner,
   truncateMiddle,
   truncateTail,
   compactAutoFinishPathSegments,

package/src/toolchain/index.js

@@ -545,6 +545,10 @@ function installGlobalToolchain(options) {
     };
   }
 
+  return performCompanionInstall(missingPackages, missingLocalTools);
+}
+
+function performCompanionInstall(missingPackages, missingLocalTools) {
   const installed = [];
   if (missingPackages.length > 0) {
     console.log(
@@ -593,6 +597,7 @@ module.exports = {
   formatGlobalToolchainServiceName,
   describeMissingGlobalDependencyWarnings,
   describeCompanionInstallCommands,
+  buildMissingCompanionInstallPrompt,
   detectGlobalToolchainPackages,
   detectRequiredSystemTools,
   detectOptionalLocalCompanionTools,
@@ -600,4 +605,5 @@ module.exports = {
   maybeSelfUpdateBeforeStatus,
   maybeOpenSpecUpdateBeforeStatus,
   installGlobalToolchain,
+  performCompanionInstall,
 };

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

@@ -277,6 +277,10 @@ created_source_probe=0
 source_probe_path=""
 integration_worktree=""
 integration_branch=""
+merge_completed=0
+merge_status="pr"
+direct_push_error=""
+pr_url=""
 
 cleanup() {
   if [[ -n "$integration_worktree" && -d "$integration_worktree" ]]; then
@@ -358,22 +362,6 @@ if [[ "$should_require_sync" -eq 1 ]] && git -C "$repo_root" show-ref --verify -
   fi
 fi
 
-integration_stamp="$(date +%Y%m%d-%H%M%S)"
-integration_worktree_base="${temp_worktree_root}/__integrate-${BASE_BRANCH//\//__}-${integration_stamp}"
-integration_branch_base="__agent_integrate_${BASE_BRANCH//\//_}_$(date +%Y%m%d_%H%M%S)"
-integration_worktree="$integration_worktree_base"
-integration_branch="$integration_branch_base"
-integration_suffix=1
-while [[ -e "$integration_worktree" ]] || git -C "$repo_root" show-ref --verify --quiet "refs/heads/${integration_branch}"; do
-  integration_worktree="${integration_worktree_base}-${integration_suffix}"
-  integration_branch="${integration_branch_base}_${integration_suffix}"
-  integration_suffix=$((integration_suffix + 1))
-done
-mkdir -p "$(dirname "$integration_worktree")"
-
-git -C "$repo_root" worktree add "$integration_worktree" "$start_ref" >/dev/null
-git -C "$integration_worktree" checkout -b "$integration_branch" >/dev/null
-
 if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
   git -C "$source_worktree" fetch origin "$BASE_BRANCH" --quiet
 
@@ -395,16 +383,52 @@ if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRA
   git -C "$source_worktree" merge --abort >/dev/null 2>&1 || true
 fi
 
-if ! git -C "$integration_worktree" merge --no-ff --no-edit "$SOURCE_BRANCH"; then
-  echo "[agent-branch-finish] Merge conflict detected while merging '${SOURCE_BRANCH}' into '${BASE_BRANCH}'." >&2
-  git -C "$integration_worktree" merge --abort >/dev/null 2>&1 || true
-  exit 1
+should_create_integration_helper=1
+if [[ "$MERGE_MODE" == "pr" && "$PUSH_ENABLED" -eq 1 ]]; then
+  should_create_integration_helper=0
 fi
 
-merge_completed=1
-merge_status="direct"
-direct_push_error=""
-pr_url=""
+if [[ "$should_create_integration_helper" -eq 1 ]]; then
+  existing_base_worktree=""
+  if [[ "$PUSH_ENABLED" -eq 0 ]]; then
+    existing_base_worktree="$(get_worktree_for_branch "$BASE_BRANCH")"
+  fi
+
+  if [[ -n "$existing_base_worktree" ]] && is_clean_worktree "$existing_base_worktree"; then
+    if ! git -C "$existing_base_worktree" merge --no-ff --no-edit "$SOURCE_BRANCH"; then
+      echo "[agent-branch-finish] Merge conflict detected while merging '${SOURCE_BRANCH}' into '${BASE_BRANCH}'." >&2
+      git -C "$existing_base_worktree" merge --abort >/dev/null 2>&1 || true
+      exit 1
+    fi
+    merge_completed=1
+    merge_status="direct"
+  else
+    integration_stamp="$(date +%Y%m%d-%H%M%S)"
+    integration_worktree_base="${temp_worktree_root}/__integrate-${BASE_BRANCH//\//__}-${integration_stamp}"
+    integration_branch_base="__agent_integrate_${BASE_BRANCH//\//_}_$(date +%Y%m%d_%H%M%S)"
+    integration_worktree="$integration_worktree_base"
+    integration_branch="$integration_branch_base"
+    integration_suffix=1
+    while [[ -e "$integration_worktree" ]] || git -C "$repo_root" show-ref --verify --quiet "refs/heads/${integration_branch}"; do
+      integration_worktree="${integration_worktree_base}-${integration_suffix}"
+      integration_branch="${integration_branch_base}_${integration_suffix}"
+      integration_suffix=$((integration_suffix + 1))
+    done
+    mkdir -p "$(dirname "$integration_worktree")"
+
+    git -C "$repo_root" worktree add "$integration_worktree" "$start_ref" >/dev/null
+    git -C "$integration_worktree" checkout -b "$integration_branch" >/dev/null
+
+    if ! git -C "$integration_worktree" merge --no-ff --no-edit "$SOURCE_BRANCH"; then
+      echo "[agent-branch-finish] Merge conflict detected while merging '${SOURCE_BRANCH}' into '${BASE_BRANCH}'." >&2
+      git -C "$integration_worktree" merge --abort >/dev/null 2>&1 || true
+      exit 1
+    fi
+
+    merge_completed=1
+    merge_status="direct"
+  fi
+fi
 
 is_local_branch_delete_error() {
   local output="$1"

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

@@ -340,16 +340,30 @@ resolve_openspec_capability_slug() {
   sanitize_slug "$task_slug" "general-behavior"
 }
 
+resolve_repo_prefix() {
+  local root
+  root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+  basename "$root"
+}
+
 resolve_worktree_leaf() {
   local branch_name="$1"
   local agent_slug="$2"
   local masterplan_label=""
   local branch_leaf=""
+  local repo_prefix
+  repo_prefix="$(resolve_repo_prefix)"
 
   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"
+    printf '%s__%s__%s__%s' "$repo_prefix" "$agent_slug" "$masterplan_label" "$branch_leaf"
+    return 0
+  fi
+
+  if [[ "$branch_name" == agent/*/* ]]; then
+    local without_agent="${branch_name#agent/}"
+    printf '%s__%s' "$repo_prefix" "${without_agent//\//__}"
     return 0
   fi
 
@@ -370,6 +384,19 @@ has_local_changes() {
   return 1
 }
 
+resolve_stash_ref_by_message() {
+  local root="$1"
+  local message="$2"
+  local stash_list
+  stash_list="$(git -C "$root" stash list 2>/dev/null || true)"
+  if [[ -z "$stash_list" ]]; then
+    printf ''
+    return 0
+  fi
+
+  awk -v msg="$message" '$0 ~ msg { ref=$1; sub(/:$/, "", ref); print ref; exit }' <<<"$stash_list"
+}
+
 resolve_protected_branches() {
   local root="$1"
   local raw
@@ -616,10 +643,7 @@ if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]] && is_protected_bra
   if has_local_changes "$repo_root"; then
     auto_transfer_message="guardex-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="$(
-        git -C "$repo_root" stash list \
-          | awk -v msg="$auto_transfer_message" '$0 ~ msg { ref=$1; sub(/:$/, "", ref); print ref; exit }'
-      )"
+      auto_transfer_stash_ref="$(resolve_stash_ref_by_message "$repo_root" "$auto_transfer_message")"
       if [[ -n "$auto_transfer_stash_ref" ]]; then
         auto_transfer_source_branch="$current_branch"
         echo "[agent-branch-start] Detected local changes on protected branch '${current_branch}'. Moving them to '${branch_name}'..."

package/templates/scripts/codex-agent.sh

@@ -372,17 +372,32 @@ resolve_openspec_capability_slug() {
   sanitize_slug "$task_slug" "general-behavior"
 }
 
+resolve_repo_prefix() {
+  local root
+  root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+  basename "$root"
+}
+
 resolve_worktree_leaf() {
   local branch_name="$1"
   local masterplan_label=""
   local branch_role=""
   local branch_leaf=""
+  local repo_prefix
+  repo_prefix="$(resolve_repo_prefix)"
 
   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"
+    printf '%s__%s__%s__%s' "$repo_prefix" "$branch_role" "$masterplan_label" "$branch_leaf"
+    return 0
+  fi
+
+  if [[ "$branch_name" =~ ^agent/([^/]+)/(.+)$ ]]; then
+    branch_role="${BASH_REMATCH[1]}"
+    branch_leaf="${BASH_REMATCH[2]}"
+    printf '%s__%s__%s' "$repo_prefix" "$branch_role" "$branch_leaf"
     return 0
   fi