@jojonax/codex-copilot 1.5.5 → 1.6.0

package/src/utils/git.js

@@ -1,388 +1,388 @@
-/**
- * Git operations utility module
- */
-
-import { execSync } from 'child_process';
-import { existsSync, statSync, unlinkSync } from 'fs';
-import { resolve } from 'path';
-import { log } from './logger.js';
-
-function exec(cmd, cwd) {
-  return execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
-}
-
-function execSafe(cmd, cwd) {
-  try {
-    return { ok: true, output: exec(cmd, cwd) };
-  } catch (err) {
-    return { ok: false, output: err.stderr || err.message };
-  }
-}
-
-// Validate branch name to prevent shell injection
-function validateBranch(name) {
-  if (!name || typeof name !== 'string') throw new Error('Branch name cannot be empty');
-  if (/[;&|`$(){}[\]!\\<>"'\s]/.test(name)) {
-    throw new Error(`Branch name contains unsafe characters: ${name}`);
-  }
-  return name;
-}
-
-/**
- * Resolve a corrupted git index by aborting any in-progress merge/rebase/cherry-pick.
- *
- * Common causes:
- * - A prior `git rebase` left conflict markers in the index
- * - A `git merge` was interrupted (SIGKILL, power loss, etc.)
- * - A `git cherry-pick` left unresolved conflicts
- *
- * After aborting, the index is reset to HEAD so checkout can proceed.
- *
- * @returns {boolean} true if index was resolved, false if no action needed
- */
-function resolveIndex(cwd) {
-  const gitDir = resolve(cwd, '.git');
-
-  let resolved = false;
-
-  // 1. Abort in-progress rebase (interactive or non-interactive)
-  const rebaseDir = resolve(gitDir, 'rebase-merge');
-  const rebaseApplyDir = resolve(gitDir, 'rebase-apply');
-  if (existsSync(rebaseDir) || existsSync(rebaseApplyDir)) {
-    log.warn('Detected stuck rebase — aborting...');
-    execSafe('git rebase --abort', cwd);
-    resolved = true;
-  }
-
-  // 2. Abort in-progress merge
-  const mergeHeadFile = resolve(gitDir, 'MERGE_HEAD');
-  if (existsSync(mergeHeadFile)) {
-    log.warn('Detected stuck merge — aborting...');
-    execSafe('git merge --abort', cwd);
-    resolved = true;
-  }
-
-  // 3. Abort in-progress cherry-pick
-  const cherryPickFile = resolve(gitDir, 'CHERRY_PICK_HEAD');
-  if (existsSync(cherryPickFile)) {
-    log.warn('Detected stuck cherry-pick — aborting...');
-    execSafe('git cherry-pick --abort', cwd);
-    resolved = true;
-  }
-
-  // 4. If nothing specific was detected but index is still bad, force-reset index to HEAD
-  if (!resolved) {
-    log.warn('Resetting index to HEAD...');
-    execSafe('git reset HEAD', cwd);
-    resolved = true;
-  }
-
-  return resolved;
-}
-
-/**
- * Safely execute a git checkout with auto-recovery for index issues.
- * If checkout fails with "resolve your current index", automatically resolves
- * the index and retries once.
- * @param {string} cmd - The full git checkout command to execute
- * @param {string} cwd - Working directory
- */
-function safeCheckout(cmd, cwd) {
-  const result = execSafe(cmd, cwd);
-  if (result.ok) return;
-
-  const errMsg = result.output || '';
-  if (errMsg.includes('resolve your current index') ||
-      errMsg.includes('needs merge') ||
-      errMsg.includes('not possible because you have unmerged files') ||
-      errMsg.includes('overwritten by checkout')) {
-    log.warn(`Checkout failed: ${errMsg.split('\n')[0]}`);
-    resolveIndex(cwd);
-
-    // After resolving, stash any leftover dirty files to ensure clean state
-    const stillDirty = !isClean(cwd);
-    if (stillDirty) {
-      log.dim('Stashing leftover changes after index resolution...');
-      execSafe('git stash --include-untracked', cwd);
-    }
-
-    // Retry checkout
-    const retry = execSafe(cmd, cwd);
-    if (!retry.ok) {
-      // Last resort: hard reset to HEAD and try once more
-      log.warn('Retry failed — hard resetting to HEAD...');
-      execSafe('git reset --hard HEAD', cwd);
-      exec(cmd, cwd); // This will throw if it still fails — unrecoverable
-    }
-
-    // Restore stashed changes
-    if (stillDirty) {
-      execSafe('git stash pop', cwd);
-    }
-  } else {
-    // Non-index-related error — re-throw
-    throw new Error(`Command failed: ${cmd}\n${errMsg}`);
-  }
-}
-
-/**
- * Check if the git working tree is clean
- */
-export function isClean(cwd) {
-  const result = exec('git status --porcelain', cwd);
-  return result.length === 0;
-}
-
-/**
- * Get current branch name
- */
-export function currentBranch(cwd) {
-  return exec('git branch --show-current', cwd);
-}
-
-/**
- * Get remote owner/repo info
- */
-export function getRepoInfo(cwd) {
-  const url = exec('git remote get-url origin', cwd);
-  // Supports https://github.com/owner/repo.git and git@github.com:owner/repo.git
-  const match = url.match(/github\.com[:/](.+?)\/(.+?)(?:\.git)?$/);
-  if (!match) throw new Error(`Cannot parse GitHub repository URL: ${url}`);
-  return { owner: match[1], repo: match[2] };
-}
-
-export function checkoutBranch(cwd, branch, baseBranch = 'main') {
-  validateBranch(branch);
-  validateBranch(baseBranch);
-  const current = currentBranch(cwd);
-  if (current === branch) return;
-
-  // Pre-flight: resolve any stuck index state before attempting anything
-  const indexCheck = execSafe('git diff --check', cwd);
-  if (!indexCheck.ok && indexCheck.output && indexCheck.output.includes('conflict')) {
-    log.warn('Pre-flight: detected conflict markers in index');
-    resolveIndex(cwd);
-  }
-
-  // Stash any uncommitted changes to allow safe branch switching
-  const hasChanges = !isClean(cwd);
-  if (hasChanges) {
-    const stashResult = execSafe('git stash --include-untracked', cwd);
-    if (!stashResult.ok) {
-      // Stash itself can fail if the index is in a bad state
-      log.warn('Stash failed — resolving index first...');
-      resolveIndex(cwd);
-      execSafe('git stash --include-untracked', cwd);
-    }
-  }
-
-  // Check if the branch already exists locally
-  const branchExists = execSafe(`git rev-parse --verify ${branch}`, cwd).ok;
-
-  if (branchExists) {
-    // Branch exists — just switch to it (preserving all previous work)
-    safeCheckout(`git checkout ${branch}`, cwd);
-
-    // Try to rebase onto latest base to pick up any new changes
-    execSafe(`git fetch origin ${baseBranch}`, cwd);
-    const rebaseResult = execSafe(`git rebase origin/${baseBranch}`, cwd);
-    // If rebase fails (conflicts), abort and continue with existing state
-    if (!rebaseResult.ok) {
-      log.dim('Rebase had conflicts — aborting to preserve current state');
-      execSafe('git rebase --abort', cwd);
-    }
-  } else {
-    // Branch doesn't exist — create from latest base
-    safeCheckout(`git checkout ${baseBranch}`, cwd);
-    execSafe(`git pull origin ${baseBranch}`, cwd);
-    exec(`git checkout -b ${branch}`, cwd);
-  }
-
-  // Restore stashed changes if we stashed earlier
-  if (hasChanges) {
-    execSafe('git stash pop', cwd);
-  }
-}
-
-/**
- * Commit all changes
- */
-export function commitAll(cwd, message) {
-  exec('git add -A', cwd);
-  const result = execSafe(`git diff --cached --quiet`, cwd);
-  if (result.ok) {
-    log.dim('No changes to commit');
-    return false;
-  }
-  exec(`git commit -m ${shellEscape(message)}`, cwd);
-  return true;
-}
-
-function shellEscape(str) {
-  return `'${str.replace(/'/g, "'\\''")}'`
-}
-
-/**
- * Push branch to remote (handles new branches without upstream)
- */
-export function pushBranch(cwd, branch) {
-  validateBranch(branch);
-  const result = execSafe(`git push origin ${branch} --force-with-lease`, cwd);
-  if (!result.ok) {
-    // Force-with-lease fails on new branches — fall back to regular push with upstream
-    exec(`git push -u origin ${branch}`, cwd);
-  }
-}
-
-/**
- * Switch back to main branch (with safe checkout recovery)
- */
-export function checkoutMain(cwd, baseBranch = 'main') {
-  validateBranch(baseBranch);
-  safeCheckout(`git checkout ${baseBranch}`, cwd);
-}
-
-// ──────────────────────────────────────────────
-// Self-Healing Utilities (Layer 2)
-// ──────────────────────────────────────────────
-
-/**
- * A2: Clear stale git lock files left behind by crashed processes.
- * Only removes lock files older than `maxAgeMs` to avoid deleting
- * locks from concurrent, legitimate operations.
- * @param {string} cwd - Working directory
- * @param {number} maxAgeMs - Max age in ms before lock is considered stale (default 5s)
- * @returns {string[]} list of removed lock files
- */
-export function clearStaleLocks(cwd, maxAgeMs = 5000) {
-  const gitDir = resolve(cwd, '.git');
-  const removed = [];
-
-  for (const lockName of ['index.lock', 'HEAD.lock', 'config.lock']) {
-    const lockPath = resolve(gitDir, lockName);
-    if (existsSync(lockPath)) {
-      try {
-        const stats = statSync(lockPath);
-        const age = Date.now() - stats.mtimeMs;
-        if (age > maxAgeMs) {
-          unlinkSync(lockPath);
-          removed.push(lockName);
-          log.warn(`Removed stale lock: ${lockName} (age: ${Math.round(age / 1000)}s)`);
-        }
-      } catch {
-        // If we can't stat, try to remove anyway (it's stale if the process is gone)
-        try {
-          unlinkSync(lockPath);
-          removed.push(lockName);
-          log.warn(`Removed lock file: ${lockName}`);
-        } catch { /* locked by active process — leave it */ }
-      }
-    }
-  }
-
-  return removed;
-}
-
-/**
- * A3: Recover from detached HEAD state.
- * When HEAD is detached (e.g., after interrupted rebase), find
- * the most recent branch that points to HEAD and checkout.
- * @returns {string|null} branch name restored to, or null if not detached
- */
-export function recoverDetachedHead(cwd) {
-  const branch = currentBranch(cwd);
-  if (branch) return null; // Not detached — nothing to do
-
-  log.warn('Detected detached HEAD state');
-
-  // Find branches containing the current commit
-  const result = execSafe('git branch --contains HEAD', cwd);
-  if (!result.ok) {
-    log.warn('Cannot determine branches containing HEAD');
-    return null;
-  }
-
-  // Parse branch list, filter out detached indicator
-  const branches = result.output
-    .split('\n')
-    .map(b => b.replace(/^\*?\s+/, '').trim())
-    .filter(b => b && !b.startsWith('(') && !b.includes('HEAD detached'));
-
-  if (branches.length === 0) {
-    log.warn('No branch contains current HEAD — manual intervention required');
-    return null;
-  }
-
-  // Prefer main/master, then the first branch found
-  const preferred = branches.find(b => b === 'main' || b === 'master') || branches[0];
-  log.warn(`Re-attaching HEAD to branch: ${preferred}`);
-  execSafe(`git checkout ${preferred}`, cwd);
-  return preferred;
-}
-
-/**
- * A4: Check for orphaned stash entries from interrupted codex-copilot operations.
- * Stash entries created by checkoutBranch() may leak if the process is killed
- * between stash push and stash pop.
- * @returns {{ found: boolean, count: number }} stash status
- */
-export function checkOrphanedStash(cwd) {
-  const result = execSafe('git stash list', cwd);
-  if (!result.ok || !result.output.trim()) {
-    return { found: false, count: 0 };
-  }
-
-  const entries = result.output.trim().split('\n');
-  if (entries.length > 0) {
-    log.warn(`Found ${entries.length} stash entry(s) — recent stash(es):`);
-    for (const entry of entries.slice(0, 3)) {
-      log.dim(`   ${entry}`);
-    }
-    // Only warn — automatic pop is risky (may cause merge conflicts)
-    // User can decide to pop or drop
-    if (entries.length > 3) {
-      log.dim(`   ... and ${entries.length - 3} more`);
-    }
-    return { found: true, count: entries.length };
-  }
-
-  return { found: false, count: 0 };
-}
-
-/**
- * A7: Quick git repository integrity check.
- * Runs `git fsck --no-full --no-dangling` for a fast check,
- * then `git gc --auto` if issues are found.
- * @returns {{ ok: boolean, issues: string[] }}
- */
-export function verifyRepo(cwd) {
-  const result = execSafe('git fsck --no-full --no-dangling --connectivity-only 2>&1', cwd);
-  if (result.ok) {
-    return { ok: true, issues: [] };
-  }
-
-  const issues = (result.output || '')
-    .split('\n')
-    .filter(l => l.trim() && !l.includes('notice') && !l.includes('Checking'))
-    .slice(0, 10);
-
-  if (issues.length > 0) {
-    log.warn(`Git integrity issues detected (${issues.length}):`);
-    for (const issue of issues.slice(0, 3)) {
-      log.dim(`   ${issue}`);
-    }
-    // Attempt auto-repair
-    log.info('Running git gc to repair...');
-    execSafe('git gc --auto', cwd);
-  }
-
-  return { ok: issues.length === 0, issues };
-}
-
-export const git = {
-  isClean, currentBranch, getRepoInfo, checkoutBranch,
-  commitAll, pushBranch, checkoutMain, exec, execSafe,
-  resolveIndex, clearStaleLocks, recoverDetachedHead,
-  checkOrphanedStash, verifyRepo,
-};
-
+/**
+ * Git operations utility module
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, statSync, unlinkSync } from 'fs';
+import { resolve } from 'path';
+import { log } from './logger.js';
+
+function exec(cmd, cwd) {
+  return execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+}
+
+function execSafe(cmd, cwd) {
+  try {
+    return { ok: true, output: exec(cmd, cwd) };
+  } catch (err) {
+    return { ok: false, output: err.stderr || err.message };
+  }
+}
+
+// Validate branch name to prevent shell injection
+function validateBranch(name) {
+  if (!name || typeof name !== 'string') throw new Error('Branch name cannot be empty');
+  if (/[;&|`$(){}[\]!\\<>"'\s]/.test(name)) {
+    throw new Error(`Branch name contains unsafe characters: ${name}`);
+  }
+  return name;
+}
+
+/**
+ * Resolve a corrupted git index by aborting any in-progress merge/rebase/cherry-pick.
+ *
+ * Common causes:
+ * - A prior `git rebase` left conflict markers in the index
+ * - A `git merge` was interrupted (SIGKILL, power loss, etc.)
+ * - A `git cherry-pick` left unresolved conflicts
+ *
+ * After aborting, the index is reset to HEAD so checkout can proceed.
+ *
+ * @returns {boolean} true if index was resolved, false if no action needed
+ */
+function resolveIndex(cwd) {
+  const gitDir = resolve(cwd, '.git');
+
+  let resolved = false;
+
+  // 1. Abort in-progress rebase (interactive or non-interactive)
+  const rebaseDir = resolve(gitDir, 'rebase-merge');
+  const rebaseApplyDir = resolve(gitDir, 'rebase-apply');
+  if (existsSync(rebaseDir) || existsSync(rebaseApplyDir)) {
+    log.warn('Detected stuck rebase — aborting...');
+    execSafe('git rebase --abort', cwd);
+    resolved = true;
+  }
+
+  // 2. Abort in-progress merge
+  const mergeHeadFile = resolve(gitDir, 'MERGE_HEAD');
+  if (existsSync(mergeHeadFile)) {
+    log.warn('Detected stuck merge — aborting...');
+    execSafe('git merge --abort', cwd);
+    resolved = true;
+  }
+
+  // 3. Abort in-progress cherry-pick
+  const cherryPickFile = resolve(gitDir, 'CHERRY_PICK_HEAD');
+  if (existsSync(cherryPickFile)) {
+    log.warn('Detected stuck cherry-pick — aborting...');
+    execSafe('git cherry-pick --abort', cwd);
+    resolved = true;
+  }
+
+  // 4. If nothing specific was detected but index is still bad, force-reset index to HEAD
+  if (!resolved) {
+    log.warn('Resetting index to HEAD...');
+    execSafe('git reset HEAD', cwd);
+    resolved = true;
+  }
+
+  return resolved;
+}
+
+/**
+ * Safely execute a git checkout with auto-recovery for index issues.
+ * If checkout fails with "resolve your current index", automatically resolves
+ * the index and retries once.
+ * @param {string} cmd - The full git checkout command to execute
+ * @param {string} cwd - Working directory
+ */
+function safeCheckout(cmd, cwd) {
+  const result = execSafe(cmd, cwd);
+  if (result.ok) return;
+
+  const errMsg = result.output || '';
+  if (errMsg.includes('resolve your current index') ||
+      errMsg.includes('needs merge') ||
+      errMsg.includes('not possible because you have unmerged files') ||
+      errMsg.includes('overwritten by checkout')) {
+    log.warn(`Checkout failed: ${errMsg.split('\n')[0]}`);
+    resolveIndex(cwd);
+
+    // After resolving, stash any leftover dirty files to ensure clean state
+    const stillDirty = !isClean(cwd);
+    if (stillDirty) {
+      log.dim('Stashing leftover changes after index resolution...');
+      execSafe('git stash --include-untracked', cwd);
+    }
+
+    // Retry checkout
+    const retry = execSafe(cmd, cwd);
+    if (!retry.ok) {
+      // Last resort: hard reset to HEAD and try once more
+      log.warn('Retry failed — hard resetting to HEAD...');
+      execSafe('git reset --hard HEAD', cwd);
+      exec(cmd, cwd); // This will throw if it still fails — unrecoverable
+    }
+
+    // Restore stashed changes
+    if (stillDirty) {
+      execSafe('git stash pop', cwd);
+    }
+  } else {
+    // Non-index-related error — re-throw
+    throw new Error(`Command failed: ${cmd}\n${errMsg}`);
+  }
+}
+
+/**
+ * Check if the git working tree is clean
+ */
+export function isClean(cwd) {
+  const result = exec('git status --porcelain', cwd);
+  return result.length === 0;
+}
+
+/**
+ * Get current branch name
+ */
+export function currentBranch(cwd) {
+  return exec('git branch --show-current', cwd);
+}
+
+/**
+ * Get remote owner/repo info
+ */
+export function getRepoInfo(cwd) {
+  const url = exec('git remote get-url origin', cwd);
+  // Supports https://github.com/owner/repo.git and git@github.com:owner/repo.git
+  const match = url.match(/github\.com[:/](.+?)\/(.+?)(?:\.git)?$/);
+  if (!match) throw new Error(`Cannot parse GitHub repository URL: ${url}`);
+  return { owner: match[1], repo: match[2] };
+}
+
+export function checkoutBranch(cwd, branch, baseBranch = 'main') {
+  validateBranch(branch);
+  validateBranch(baseBranch);
+  const current = currentBranch(cwd);
+  if (current === branch) return;
+
+  // Pre-flight: resolve any stuck index state before attempting anything
+  const indexCheck = execSafe('git diff --check', cwd);
+  if (!indexCheck.ok && indexCheck.output && indexCheck.output.includes('conflict')) {
+    log.warn('Pre-flight: detected conflict markers in index');
+    resolveIndex(cwd);
+  }
+
+  // Stash any uncommitted changes to allow safe branch switching
+  const hasChanges = !isClean(cwd);
+  if (hasChanges) {
+    const stashResult = execSafe('git stash --include-untracked', cwd);
+    if (!stashResult.ok) {
+      // Stash itself can fail if the index is in a bad state
+      log.warn('Stash failed — resolving index first...');
+      resolveIndex(cwd);
+      execSafe('git stash --include-untracked', cwd);
+    }
+  }
+
+  // Check if the branch already exists locally
+  const branchExists = execSafe(`git rev-parse --verify ${branch}`, cwd).ok;
+
+  if (branchExists) {
+    // Branch exists — just switch to it (preserving all previous work)
+    safeCheckout(`git checkout ${branch}`, cwd);
+
+    // Try to rebase onto latest base to pick up any new changes
+    execSafe(`git fetch origin ${baseBranch}`, cwd);
+    const rebaseResult = execSafe(`git rebase origin/${baseBranch}`, cwd);
+    // If rebase fails (conflicts), abort and continue with existing state
+    if (!rebaseResult.ok) {
+      log.dim('Rebase had conflicts — aborting to preserve current state');
+      execSafe('git rebase --abort', cwd);
+    }
+  } else {
+    // Branch doesn't exist — create from latest base
+    safeCheckout(`git checkout ${baseBranch}`, cwd);
+    execSafe(`git pull origin ${baseBranch}`, cwd);
+    exec(`git checkout -b ${branch}`, cwd);
+  }
+
+  // Restore stashed changes if we stashed earlier
+  if (hasChanges) {
+    execSafe('git stash pop', cwd);
+  }
+}
+
+/**
+ * Commit all changes
+ */
+export function commitAll(cwd, message) {
+  exec('git add -A', cwd);
+  const result = execSafe(`git diff --cached --quiet`, cwd);
+  if (result.ok) {
+    log.dim('No changes to commit');
+    return false;
+  }
+  exec(`git commit -m ${shellEscape(message)}`, cwd);
+  return true;
+}
+
+function shellEscape(str) {
+  return `'${str.replace(/'/g, "'\\''")}'`
+}
+
+/**
+ * Push branch to remote (handles new branches without upstream)
+ */
+export function pushBranch(cwd, branch) {
+  validateBranch(branch);
+  const result = execSafe(`git push origin ${branch} --force-with-lease`, cwd);
+  if (!result.ok) {
+    // Force-with-lease fails on new branches — fall back to regular push with upstream
+    exec(`git push -u origin ${branch}`, cwd);
+  }
+}
+
+/**
+ * Switch back to main branch (with safe checkout recovery)
+ */
+export function checkoutMain(cwd, baseBranch = 'main') {
+  validateBranch(baseBranch);
+  safeCheckout(`git checkout ${baseBranch}`, cwd);
+}
+
+// ──────────────────────────────────────────────
+// Self-Healing Utilities (Layer 2)
+// ──────────────────────────────────────────────
+
+/**
+ * A2: Clear stale git lock files left behind by crashed processes.
+ * Only removes lock files older than `maxAgeMs` to avoid deleting
+ * locks from concurrent, legitimate operations.
+ * @param {string} cwd - Working directory
+ * @param {number} maxAgeMs - Max age in ms before lock is considered stale (default 5s)
+ * @returns {string[]} list of removed lock files
+ */
+export function clearStaleLocks(cwd, maxAgeMs = 5000) {
+  const gitDir = resolve(cwd, '.git');
+  const removed = [];
+
+  for (const lockName of ['index.lock', 'HEAD.lock', 'config.lock']) {
+    const lockPath = resolve(gitDir, lockName);
+    if (existsSync(lockPath)) {
+      try {
+        const stats = statSync(lockPath);
+        const age = Date.now() - stats.mtimeMs;
+        if (age > maxAgeMs) {
+          unlinkSync(lockPath);
+          removed.push(lockName);
+          log.warn(`Removed stale lock: ${lockName} (age: ${Math.round(age / 1000)}s)`);
+        }
+      } catch {
+        // If we can't stat, try to remove anyway (it's stale if the process is gone)
+        try {
+          unlinkSync(lockPath);
+          removed.push(lockName);
+          log.warn(`Removed lock file: ${lockName}`);
+        } catch { /* locked by active process — leave it */ }
+      }
+    }
+  }
+
+  return removed;
+}
+
+/**
+ * A3: Recover from detached HEAD state.
+ * When HEAD is detached (e.g., after interrupted rebase), find
+ * the most recent branch that points to HEAD and checkout.
+ * @returns {string|null} branch name restored to, or null if not detached
+ */
+export function recoverDetachedHead(cwd) {
+  const branch = currentBranch(cwd);
+  if (branch) return null; // Not detached — nothing to do
+
+  log.warn('Detected detached HEAD state');
+
+  // Find branches containing the current commit
+  const result = execSafe('git branch --contains HEAD', cwd);
+  if (!result.ok) {
+    log.warn('Cannot determine branches containing HEAD');
+    return null;
+  }
+
+  // Parse branch list, filter out detached indicator
+  const branches = result.output
+    .split('\n')
+    .map(b => b.replace(/^\*?\s+/, '').trim())
+    .filter(b => b && !b.startsWith('(') && !b.includes('HEAD detached'));
+
+  if (branches.length === 0) {
+    log.warn('No branch contains current HEAD — manual intervention required');
+    return null;
+  }
+
+  // Prefer main/master, then the first branch found
+  const preferred = branches.find(b => b === 'main' || b === 'master') || branches[0];
+  log.warn(`Re-attaching HEAD to branch: ${preferred}`);
+  execSafe(`git checkout ${preferred}`, cwd);
+  return preferred;
+}
+
+/**
+ * A4: Check for orphaned stash entries from interrupted codex-copilot operations.
+ * Stash entries created by checkoutBranch() may leak if the process is killed
+ * between stash push and stash pop.
+ * @returns {{ found: boolean, count: number }} stash status
+ */
+export function checkOrphanedStash(cwd) {
+  const result = execSafe('git stash list', cwd);
+  if (!result.ok || !result.output.trim()) {
+    return { found: false, count: 0 };
+  }
+
+  const entries = result.output.trim().split('\n');
+  if (entries.length > 0) {
+    log.warn(`Found ${entries.length} stash entry(s) — recent stash(es):`);
+    for (const entry of entries.slice(0, 3)) {
+      log.dim(`   ${entry}`);
+    }
+    // Only warn — automatic pop is risky (may cause merge conflicts)
+    // User can decide to pop or drop
+    if (entries.length > 3) {
+      log.dim(`   ... and ${entries.length - 3} more`);
+    }
+    return { found: true, count: entries.length };
+  }
+
+  return { found: false, count: 0 };
+}
+
+/**
+ * A7: Quick git repository integrity check.
+ * Runs `git fsck --no-full --no-dangling` for a fast check,
+ * then `git gc --auto` if issues are found.
+ * @returns {{ ok: boolean, issues: string[] }}
+ */
+export function verifyRepo(cwd) {
+  const result = execSafe('git fsck --no-full --no-dangling --connectivity-only 2>&1', cwd);
+  if (result.ok) {
+    return { ok: true, issues: [] };
+  }
+
+  const issues = (result.output || '')
+    .split('\n')
+    .filter(l => l.trim() && !l.includes('notice') && !l.includes('Checking'))
+    .slice(0, 10);
+
+  if (issues.length > 0) {
+    log.warn(`Git integrity issues detected (${issues.length}):`);
+    for (const issue of issues.slice(0, 3)) {
+      log.dim(`   ${issue}`);
+    }
+    // Attempt auto-repair
+    log.info('Running git gc to repair...');
+    execSafe('git gc --auto', cwd);
+  }
+
+  return { ok: issues.length === 0, issues };
+}
+
+export const git = {
+  isClean, currentBranch, getRepoInfo, checkoutBranch,
+  commitAll, pushBranch, checkoutMain, exec, execSafe,
+  resolveIndex, clearStaleLocks, recoverDetachedHead,
+  checkOrphanedStash, verifyRepo,
+};
+