@jojonax/codex-copilot 1.5.3 → 1.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jojonax/codex-copilot",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "description": "PRD-driven automated development orchestrator for CodeX / Cursor",
   "bin": {
     "codex-copilot": "./bin/cli.js"

package/src/commands/fix.js

@@ -288,13 +288,61 @@ export async function fix(projectDir) {
     process.exit(1);
   }
 
-  log.info('Scanning .codex-copilot/ for issues...');
+  // Phase 1: JSON file repair
+  log.info('Scanning .codex-copilot/ for JSON issues...');
   log.blank();
 
   const results = runRepairs(copilotDir);
   printReport(results);
+
+  // Phase 2: Git state self-healing
+  log.info('Checking git state...');
+  log.blank();
+
+  try {
+    const { git } = await import('../utils/git.js');
+
+    // Lock files
+    const locks = git.clearStaleLocks(projectDir);
+    if (locks.length > 0) {
+      log.info(`🔧 Removed ${locks.length} stale lock file(s)`);
+    } else {
+      log.info('✅ No stale lock files');
+    }
+
+    // Index state (merge/rebase/cherry-pick)
+    git.resolveIndex(projectDir);
+
+    // Detached HEAD
+    const recovered = git.recoverDetachedHead(projectDir);
+    if (recovered) {
+      log.info(`🔧 Recovered from detached HEAD → ${recovered}`);
+    } else {
+      log.info('✅ HEAD is attached to a branch');
+    }
+
+    // Stash check
+    const stash = git.checkOrphanedStash(projectDir);
+    if (stash.found) {
+      log.warn(`⚠ Found ${stash.count} stash entry(s) — run 'git stash list' to review`);
+    } else {
+      log.info('✅ No orphaned stashes');
+    }
+
+    // Repo integrity
+    const integrity = git.verifyRepo(projectDir);
+    if (integrity.ok) {
+      log.info('✅ Git repository integrity OK');
+    }
+
+    log.blank();
+  } catch (err) {
+    log.warn(`Git state check failed: ${err.message}`);
+    log.blank();
+  }
 }
 
+
 /**
  * Auto-fix — called programmatically by other commands when errors are detected.
  * Returns true if all files are healthy (either clean or successfully repaired).

package/src/commands/retry.js

@@ -14,6 +14,7 @@ import { git } from '../utils/git.js';
 import { github } from '../utils/github.js';
 import { createCheckpoint } from '../utils/checkpoint.js';
 import { readJSON, writeJSON } from '../utils/json.js';
+import { preFlightCheck } from '../utils/self-heal.js';
 
 
 
@@ -45,6 +46,11 @@ export async function retry(projectDir) {
   // Ensure retry context directory exists
   mkdirSync(retryDir, { recursive: true });
 
+  // Pre-flight: resolve any git/environment issues before retrying
+  log.blank();
+  preFlightCheck(projectDir, 'main', {});
+  log.blank();
+
   for (const task of blocked) {
     const reason = task.block_reason || 'unknown';
     log.info(`  #${task.id}: ${task.title}`);
@@ -54,8 +60,14 @@ export async function retry(projectDir) {
       await recoverReviewBlocked(projectDir, task, checkpoint, retryDir);
     } else if (reason === 'merge_failed') {
       recoverMergeBlocked(task, checkpoint);
+    } else if (reason === 'git_checkout_failed') {
+      recoverGitBlocked(projectDir, task, checkpoint, retryDir);
+    } else if (reason === 'ai_timeout') {
+      // AI provider timed out — clear checkpoint so it retries from prompt step
+      checkpoint.clearTask(task.id);
+      log.dim('       Cleared checkpoint — will retry AI execution');
     } else {
-      // dev_failed or unknown
+      // dev_failed, rate_limited, or unknown
       recoverDevBlocked(projectDir, task, checkpoint, retryDir);
     }
 
@@ -151,3 +163,28 @@ function recoverMergeBlocked(task, checkpoint) {
   checkpoint.clearStep(task.id, 'merge', 'merged');
   log.dim('       Reset merge step \u2014 will retry merge on next run');
 }
+
+/**
+ * Git-checkout-blocked: resolve index issues and clear develop checkpoint.
+ * The pre-flight check already resolved most git issues;
+ * here we just reset the checkpoint so the task retries from branch creation.
+ */
+function recoverGitBlocked(projectDir, task, checkpoint, retryDir) {
+  // Resolve any lingering index issues
+  git.resolveIndex(projectDir);
+  git.clearStaleLocks(projectDir);
+
+  // Save context for retry prompt
+  const contextPath = resolve(retryDir, `${task.id}.md`);
+  writeFileSync(contextPath, [
+    `# Retry Context for Task #${task.id}`,
+    '',
+    '## Previous Attempt',
+    'The task failed due to a git checkout error (corrupted index, stuck merge/rebase, or lock file).',
+    'The git state has been automatically repaired. Try again with the same approach.',
+  ].join('\n'));
+  log.dim('       Resolved git state and saved retry context');
+
+  // Clear all checkpoints — restart from scratch
+  checkpoint.clearTask(task.id);
+}

package/src/commands/run.js

@@ -14,6 +14,7 @@ import { closePrompt } from '../utils/prompt.js';
 import { createCheckpoint } from '../utils/checkpoint.js';
 import { provider } from '../utils/provider.js';
 import { readJSON, writeJSON } from '../utils/json.js';
+import { preFlightCheck, releaseLock } from '../utils/self-heal.js';
 
 const maxRateLimitRetries = 3;
 
@@ -105,6 +106,7 @@ export async function run(projectDir) {
     log.warn('Interrupt received — saving checkpoint...');
     // State is already saved at each step, just need to save tasks.json
     writeJSON(tasksPath, tasks);
+    releaseLock(projectDir);
     log.info('✅ Checkpoint saved. Run `codex-copilot run` to resume.');
     log.blank();
     closePrompt();
@@ -119,6 +121,21 @@ export async function run(projectDir) {
   log.info(`Total tasks: ${tasks.total}`);
   log.info(`Base branch: ${baseBranch}`);
 
+  // ===== Pre-flight self-healing =====
+  const health = preFlightCheck(projectDir, baseBranch, { checkpoint, tasks });
+  if (!health.ok) {
+    log.blank();
+    log.error('Pre-flight check failed — cannot proceed:');
+    for (const b of health.blockers) {
+      log.error(`  🛑 ${b}`);
+    }
+    log.blank();
+    releaseLock(projectDir);
+    closePrompt();
+    process.exit(1);
+  }
+  log.blank();
+
   // ===== Pre-flight: ensure base branch is committed & pushed =====
   await ensureBaseReady(projectDir, baseBranch, isPrivate);
 
@@ -329,6 +346,7 @@ export async function run(projectDir) {
   log.blank();
   process.removeListener('SIGINT', gracefulShutdown);
   process.removeListener('SIGTERM', gracefulShutdown);
+  releaseLock(projectDir);
 
   // ===== Auto-evolve: trigger next round if enabled =====
   if (config.auto_evolve !== false) {
@@ -351,14 +369,28 @@ async function developPhase(projectDir, task, baseBranch, checkpoint, providerId
 
   // Step 1: Switch to feature branch
   if (!checkpoint.isStepDone(task.id, 'develop', 'branch_created')) {
-    git.checkoutBranch(projectDir, task.branch, baseBranch);
+    try {
+      git.checkoutBranch(projectDir, task.branch, baseBranch);
+    } catch (err) {
+      log.error(`Failed to switch to branch ${task.branch}: ${err.message}`);
+      task.status = 'blocked';
+      task.block_reason = 'git_checkout_failed';
+      return;
+    }
     log.info(`Switched to branch: ${task.branch}`);
     checkpoint.saveStep(task.id, 'develop', 'branch_created', { branch: task.branch });
   } else {
     // Ensure we're on the right branch
     const current = git.currentBranch(projectDir);
     if (current !== task.branch) {
-      git.checkoutBranch(projectDir, task.branch, baseBranch);
+      try {
+        git.checkoutBranch(projectDir, task.branch, baseBranch);
+      } catch (err) {
+        log.error(`Failed to switch to branch ${task.branch}: ${err.message}`);
+        task.status = 'blocked';
+        task.block_reason = 'git_checkout_failed';
+        return;
+      }
     }
     log.dim('⏩ Branch already created');
   }
@@ -374,13 +406,34 @@ async function developPhase(projectDir, task, baseBranch, checkpoint, providerId
     log.dim('⏩ Prompt already generated');
   }
 
-  // Step 3: Execute via AI Provider (with rate limit auto-retry)
+  // Step 3: Execute via AI Provider (with rate limit auto-retry + timeout protection)
   if (!checkpoint.isStepDone(task.id, 'develop', 'codex_complete')) {
     const promptPath = resolve(projectDir, '.codex-copilot/_current_prompt.md');
     let rateLimitRetries = 0;
+    const AI_TIMEOUT_MS = 30 * 60 * 1000; // D4: 30 minute timeout for AI execution
 
     while (rateLimitRetries < maxRateLimitRetries) {
-      const result = await provider.executePrompt(providerId, promptPath, projectDir);
+      // D4: Race the AI execution against a timeout to prevent infinite hangs
+      const timeoutPromise = new Promise((_, reject) =>
+        setTimeout(() => reject(new Error('AI_TIMEOUT')), AI_TIMEOUT_MS)
+      );
+
+      let result;
+      try {
+        result = await Promise.race([
+          provider.executePrompt(providerId, promptPath, projectDir),
+          timeoutPromise,
+        ]);
+      } catch (timeoutErr) {
+        if (timeoutErr.message === 'AI_TIMEOUT') {
+          log.error(`AI provider timed out after ${AI_TIMEOUT_MS / 60000} minutes — marking task as blocked`);
+          task.status = 'blocked';
+          task.block_reason = 'ai_timeout';
+          return;
+        }
+        throw timeoutErr;
+      }
+
       if (result.ok) {
         log.info('Development complete');
         checkpoint.saveStep(task.id, 'develop', 'codex_complete', { branch: task.branch });

package/src/utils/checkpoint.js

@@ -8,6 +8,14 @@
 import { readFileSync, writeFileSync, renameSync, existsSync } from 'fs';
 import { resolve } from 'path';
 
+const PHASE_ORDER = ['develop', 'pr', 'review', 'merge'];
+const STEP_ORDERS = {
+  develop: ['branch_created', 'prompt_ready', 'codex_complete'],
+  pr: ['committed', 'pushed', 'pr_created'],
+  review: ['waiting_review', 'feedback_received', 'fix_applied'],
+  merge: ['merged'],
+};
+
 /**
  * Create a checkpoint manager for a project
  * @param {string} projectDir - Project root directory
@@ -45,9 +53,34 @@ export function createCheckpoint(projectDir) {
   }
 
   /**
-   * Mark a specific phase & step as reached
+   * Mark a specific phase & step as reached.
+   * Includes monotonic progress guard — prevents regression from a later
+   * phase back to an earlier one (e.g., 'pr' → 'develop' is blocked).
    */
   function saveStep(taskId, phase, phaseStep, extra = {}) {
+    const current = load();
+
+    // Monotonic progress guard: only allow forward movement within the same task
+    if (current.current_task === taskId && current.phase) {
+      const currentPhaseIdx = PHASE_ORDER.indexOf(current.phase);
+      const newPhaseIdx = PHASE_ORDER.indexOf(phase);
+
+      if (newPhaseIdx < currentPhaseIdx) {
+        // Attempting to go backward — ignore silently (likely a stale call)
+        return current;
+      }
+
+      // Same phase: ensure step is not going backward
+      if (newPhaseIdx === currentPhaseIdx) {
+        const steps = STEP_ORDERS[phase] || [];
+        const currentStepIdx = steps.indexOf(current.phase_step);
+        const newStepIdx = steps.indexOf(phaseStep);
+        if (newStepIdx < currentStepIdx) {
+          return current; // Step regression — ignore
+        }
+      }
+    }
+
     return save({
       current_task: taskId,
       phase,
@@ -79,9 +112,8 @@ export function createCheckpoint(projectDir) {
     if (state.current_task !== taskId) return false;
     if (!state.phase) return false;
 
-    const phaseOrder = ['develop', 'pr', 'review', 'merge'];
-    const savedPhaseIdx = phaseOrder.indexOf(state.phase);
-    const targetPhaseIdx = phaseOrder.indexOf(phase);
+    const savedPhaseIdx = PHASE_ORDER.indexOf(state.phase);
+    const targetPhaseIdx = PHASE_ORDER.indexOf(phase);
 
     // If saved phase is ahead, this step is done
     if (savedPhaseIdx > targetPhaseIdx) return true;
@@ -89,14 +121,7 @@ export function createCheckpoint(projectDir) {
     if (savedPhaseIdx < targetPhaseIdx) return false;
 
     // Same phase: compare steps within phase
-    const stepOrders = {
-      develop: ['branch_created', 'prompt_ready', 'codex_complete'],
-      pr: ['committed', 'pushed', 'pr_created'],
-      review: ['waiting_review', 'feedback_received', 'fix_applied'],
-      merge: ['merged'],
-    };
-
-    const steps = stepOrders[phase] || [];
+    const steps = STEP_ORDERS[phase] || [];
     const savedStepIdx = steps.indexOf(state.phase_step);
     const targetStepIdx = steps.indexOf(phaseStep);
 
@@ -143,7 +168,67 @@ export function createCheckpoint(projectDir) {
     return state;
   }
 
-  return { load, save, saveStep, completeTask, isStepDone, reset, clearTask, clearStep };
+  /**
+   * E1/E4: Validate consistency between checkpoint state and tasks status.
+   * Detects and repairs mismatches such as:
+   *  - Task marked 'in_progress' but no checkpoint data for it
+   *  - Checkpoint points to a task that's already completed
+   *  - Multiple tasks marked 'in_progress' simultaneously
+   * @param {object} tasks - The tasks.json data structure
+   * @returns {{ ok: boolean, repairs: string[] }}
+   */
+  function validateConsistency(tasks) {
+    const state = load();
+    const repairs = [];
+
+    if (!tasks?.tasks || !Array.isArray(tasks.tasks)) {
+      return { ok: true, repairs: [] };
+    }
+
+    // Check 1: Multiple in_progress tasks (should only be one at a time)
+    const inProgress = tasks.tasks.filter(t => t.status === 'in_progress');
+    if (inProgress.length > 1) {
+      // Keep the one matching checkpoint, reset others to pending
+      for (const task of inProgress) {
+        if (task.id !== state.current_task) {
+          task.status = 'pending';
+          repairs.push(`Task #${task.id}: was 'in_progress' but not current — reset to 'pending'`);
+        }
+      }
+    }
+
+    // Check 2: Task is in_progress but checkpoint has no data for it
+    if (inProgress.length === 1 && state.current_task !== inProgress[0].id) {
+      if (!state.phase) {
+        // Checkpoint is empty — task was marked in_progress but never started
+        inProgress[0].status = 'pending';
+        repairs.push(`Task #${inProgress[0].id}: marked 'in_progress' but no checkpoint data — reset to 'pending'`);
+      }
+    }
+
+    // Check 3: Checkpoint points to a completed task (stale checkpoint)
+    if (state.current_task > 0 && state.phase) {
+      const checkpointTask = tasks.tasks.find(t => t.id === state.current_task);
+      if (checkpointTask && checkpointTask.status === 'completed') {
+        // Checkpoint is stale — clear it
+        save({ phase: null, phase_step: null, current_pr: null, review_round: 0, branch: null });
+        repairs.push(`Checkpoint for task #${state.current_task} cleared (task already completed)`);
+      }
+    }
+
+    // Check 4: Checkpoint task ID doesn't exist in tasks list
+    if (state.current_task > 0) {
+      const exists = tasks.tasks.find(t => t.id === state.current_task);
+      if (!exists) {
+        save({ current_task: 0, phase: null, phase_step: null, current_pr: null, review_round: 0, branch: null });
+        repairs.push(`Checkpoint referenced non-existent task #${state.current_task} — reset`);
+      }
+    }
+
+    return { ok: repairs.length === 0, repairs };
+  }
+
+  return { load, save, saveStep, completeTask, isStepDone, reset, clearTask, clearStep, validateConsistency };
 }
 
 function getDefaultState() {
@@ -158,3 +243,4 @@ function getDefaultState() {
     last_updated: new Date().toISOString(),
   };
 }
+

package/src/utils/git.js

@@ -3,6 +3,8 @@
  */
 
 import { execSync } from 'child_process';
+import { existsSync, statSync, unlinkSync } from 'fs';
+import { resolve } from 'path';
 import { log } from './logger.js';
 
 function exec(cmd, cwd) {
@@ -26,6 +28,103 @@ function validateBranch(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
  */
@@ -58,10 +157,23 @@ export function checkoutBranch(cwd, branch, baseBranch = 'main') {
   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) {
-    execSafe('git stash --include-untracked', cwd);
+    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
@@ -69,16 +181,19 @@ export function checkoutBranch(cwd, branch, baseBranch = 'main') {
 
   if (branchExists) {
     // Branch exists — just switch to it (preserving all previous work)
-    exec(`git checkout ${branch}`, cwd);
+    safeCheckout(`git checkout ${branch}`, cwd);
 
     // Try to rebase onto latest base to pick up any new changes
     execSafe(`git fetch origin ${baseBranch}`, cwd);
-    execSafe(`git rebase origin/${baseBranch}`, cwd);
+    const rebaseResult = execSafe(`git rebase origin/${baseBranch}`, cwd);
     // If rebase fails (conflicts), abort and continue with existing state
-    execSafe('git rebase --abort', cwd);
+    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
-    execSafe(`git checkout ${baseBranch}`, cwd);
+    safeCheckout(`git checkout ${baseBranch}`, cwd);
     execSafe(`git pull origin ${baseBranch}`, cwd);
     exec(`git checkout -b ${branch}`, cwd);
   }
@@ -120,14 +235,154 @@ export function pushBranch(cwd, branch) {
 }
 
 /**
- * Switch back to main branch
+ * Switch back to main branch (with safe checkout recovery)
  */
 export function checkoutMain(cwd, baseBranch = 'main') {
   validateBranch(baseBranch);
-  execSafe(`git checkout ${baseBranch}`, cwd);
+  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,
 };
+

package/src/utils/github.js

@@ -6,7 +6,12 @@ import { execSync } from 'child_process';
 import { log } from './logger.js';
 
 function gh(cmd, cwd) {
-  return execSync(`gh ${cmd}`, { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  return execSync(`gh ${cmd}`, {
+    cwd,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 30000, // 30s timeout to prevent hanging on network issues
+  }).trim();
 }
 
 function ghSafe(cmd, cwd) {
@@ -378,12 +383,64 @@ export function requestReReview(cwd, prNumber) {
   }
 }
 
+/**
+ * C4: Verify GitHub CLI authentication is valid.
+ * Checks both auth status and token expiry.
+ * @returns {{ ok: boolean, user: string|null, error: string|null }}
+ */
+export function ensureAuth(cwd) {
+  try {
+    const output = execSync('gh auth status 2>&1', {
+      cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 10000,
+    });
+    const userMatch = output.match(/Logged in to .+ as (\S+)/);
+    return { ok: true, user: userMatch?.[1] || 'unknown', error: null };
+  } catch (err) {
+    const msg = err.stderr || err.message || '';
+    if (msg.includes('not logged in') || msg.includes('authentication')) {
+      return { ok: false, user: null, error: 'Not authenticated. Run: gh auth login' };
+    }
+    if (msg.includes('token') && msg.includes('expir')) {
+      return { ok: false, user: null, error: 'Token expired. Run: gh auth refresh' };
+    }
+    return { ok: false, user: null, error: `Auth check failed: ${msg.substring(0, 100)}` };
+  }
+}
+
+/**
+ * C2/C5: Check network connectivity to the git remote.
+ * Verifies that we can reach the origin remote.
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function checkConnectivity(cwd) {
+  try {
+    execSync('git ls-remote --exit-code origin HEAD', {
+      cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 15000,
+    });
+    return { ok: true, error: null };
+  } catch (err) {
+    const msg = err.stderr || err.message || '';
+    if (msg.includes('Could not resolve host') || msg.includes('Network is unreachable')) {
+      return { ok: false, error: 'Network unreachable — check internet connection' };
+    }
+    if (msg.includes('Permission denied') || msg.includes('Authentication failed')) {
+      return { ok: false, error: 'Authentication failed — check SSH keys or GH token' };
+    }
+    if (msg.includes('Repository not found')) {
+      return { ok: false, error: 'Remote repository not found — verify origin URL' };
+    }
+    // Timeout or other error
+    return { ok: false, error: `Cannot reach remote: ${msg.substring(0, 100)}` };
+  }
+}
+
 export const github = {
   checkGhAuth, createPR, createPRWithRecovery, findExistingPR,
   ensureRemoteBranch, hasCommitsBetween,
   getReviews, getReviewComments, getIssueComments,
   getLatestReviewState, mergePR, collectReviewFeedback,
   isPrivateRepo, requestReReview, closePR, deleteBranch, getPRState,
+  ensureAuth, checkConnectivity,
 };
 
 /**

package/src/utils/json.js

@@ -156,8 +156,31 @@ function tryParse(s) {
  */
 export function writeJSON(filePath, data) {
   const tempPath = filePath + '.tmp';
-  writeFileSync(tempPath, JSON.stringify(data, null, 2));
+  const content = JSON.stringify(data, null, 2);
+
+  // B4: Disk space protection — catch ENOSPC/EDQUOT errors with clear message
+  try {
+    writeFileSync(tempPath, content);
+  } catch (writeErr) {
+    if (writeErr.code === 'ENOSPC' || writeErr.code === 'EDQUOT') {
+      throw new Error(`Disk full — cannot write ${filePath}. Free up space and retry.`);
+    }
+    if (writeErr.code === 'EACCES' || writeErr.code === 'EPERM') {
+      throw new Error(`Permission denied — cannot write ${filePath}. Check file/directory permissions.`);
+    }
+    throw writeErr;
+  }
+
   renameSync(tempPath, filePath);
+
+  // Write-back verification: ensure what we wrote is valid and readable
+  try {
+    const readBack = readFileSync(filePath, 'utf-8');
+    JSON.parse(readBack);
+  } catch (verifyErr) {
+    // Write succeeded but verification failed — attempt direct overwrite
+    writeFileSync(filePath, content);
+  }
 }
 
 /**

package/src/utils/self-heal.js

@@ -0,0 +1,330 @@
+/**
+ * Self-Healing Module — Unified recovery and health check entry point
+ *
+ * Layer 3-4 of the self-healing architecture:
+ *   - preFlightCheck():      Full environment validation before run
+ *   - validatePhaseEntry():  Phase-specific guard before each phase starts
+ *
+ * Uses Layer 2 building blocks from git.js and github.js.
+ */
+
+import { existsSync, writeFileSync, readFileSync, unlinkSync, accessSync, constants } from 'fs';
+import { resolve } from 'path';
+import { git } from './git.js';
+import { github } from './github.js';
+import { log } from './logger.js';
+import { readJSON, writeJSON } from './json.js';
+
+/**
+ * Layer 4: Pre-flight health check — run before starting the automation loop.
+ *
+ * Performs comprehensive environment validation and auto-repairs:
+ *   1. Concurrent execution lock (PID file)
+ *   2. Git lock file cleanup
+ *   3. Detached HEAD recovery
+ *   4. Orphaned stash detection
+ *   5. Git repository integrity
+ *   6. GitHub auth verification
+ *   7. Temp file cleanup
+ *   8. Task/Checkpoint consistency validation
+ *
+ * @param {string} projectDir - Project root directory
+ * @param {string} baseBranch - Base branch name (e.g., 'main')
+ * @param {object} [options]
+ * @param {object} [options.checkpoint] - Checkpoint manager instance
+ * @param {object} [options.tasks] - Tasks data from tasks.json
+ * @returns {{ ok: boolean, repairs: string[], warnings: string[], blockers: string[] }}
+ */
+export function preFlightCheck(projectDir, baseBranch, options = {}) {
+  const copilotDir = resolve(projectDir, '.codex-copilot');
+  const repairs = [];
+  const warnings = [];
+  const blockers = [];
+
+  log.dim('Running pre-flight health check...');
+
+  // ── 1. Concurrent execution lock (D3) ──
+  const pidPath = resolve(copilotDir, '.pid');
+  if (existsSync(pidPath)) {
+    try {
+      const pidContent = readFileSync(pidPath, 'utf-8').trim();
+      const [pid, startTime] = pidContent.split(':');
+      const pidNum = parseInt(pid, 10);
+
+      // Check if the process is still running
+      let isRunning = false;
+      try {
+        process.kill(pidNum, 0); // Signal 0: check if process exists
+        isRunning = true;
+      } catch {
+        isRunning = false; // Process doesn't exist
+      }
+
+      if (isRunning) {
+        const age = startTime ? Math.round((Date.now() - parseInt(startTime, 10)) / 1000) : 0;
+        blockers.push(`Another codex-copilot instance is running (PID: ${pidNum}, age: ${age}s). Kill it first or wait.`);
+      } else {
+        // Stale PID file — remove it
+        unlinkSync(pidPath);
+        repairs.push('Removed stale PID lock file from crashed process');
+      }
+    } catch {
+      // Can't read PID file — remove it
+      try { unlinkSync(pidPath); } catch {}
+      repairs.push('Removed unreadable PID lock file');
+    }
+  }
+
+  // Write our PID (even if there are other blockers, we need to own the lock)
+  if (blockers.length === 0) {
+    try {
+      writeFileSync(pidPath, `${process.pid}:${Date.now()}`);
+    } catch { /* non-critical */ }
+  }
+
+  // ── 2. Git lock file cleanup (A2) ──
+  try {
+    const removedLocks = git.clearStaleLocks(projectDir);
+    if (removedLocks.length > 0) {
+      repairs.push(`Cleared ${removedLocks.length} stale git lock file(s): ${removedLocks.join(', ')}`);
+    }
+  } catch (err) {
+    warnings.push(`Lock file check failed: ${err.message}`);
+  }
+
+  // ── 3. Detached HEAD recovery (A3) ──
+  try {
+    const recovered = git.recoverDetachedHead(projectDir);
+    if (recovered) {
+      repairs.push(`Recovered from detached HEAD → ${recovered}`);
+    }
+  } catch (err) {
+    warnings.push(`Detached HEAD check failed: ${err.message}`);
+  }
+
+  // ── 4. Orphaned stash detection (A4) ──
+  try {
+    const stashStatus = git.checkOrphanedStash(projectDir);
+    if (stashStatus.found) {
+      warnings.push(`${stashStatus.count} stash entry(s) found — run 'git stash list' to inspect`);
+    }
+  } catch (err) {
+    // Non-critical
+  }
+
+  // ── 5. Git index health (A1) ──
+  try {
+    const gitDir = resolve(projectDir, '.git');
+    const hasRebase = existsSync(resolve(gitDir, 'rebase-merge')) || existsSync(resolve(gitDir, 'rebase-apply'));
+    const hasMerge = existsSync(resolve(gitDir, 'MERGE_HEAD'));
+    const hasCherryPick = existsSync(resolve(gitDir, 'CHERRY_PICK_HEAD'));
+
+    if (hasRebase || hasMerge || hasCherryPick) {
+      git.resolveIndex(projectDir);
+      const operations = [];
+      if (hasRebase) operations.push('rebase');
+      if (hasMerge) operations.push('merge');
+      if (hasCherryPick) operations.push('cherry-pick');
+      repairs.push(`Resolved stuck git operation(s): ${operations.join(', ')}`);
+    }
+  } catch (err) {
+    warnings.push(`Index health check failed: ${err.message}`);
+  }
+
+  // ── 6. GitHub auth verification (C4) ──
+  try {
+    const authStatus = github.ensureAuth(projectDir);
+    if (!authStatus.ok) {
+      blockers.push(`GitHub auth: ${authStatus.error}`);
+    }
+  } catch (err) {
+    warnings.push(`GitHub auth check failed: ${err.message}`);
+  }
+
+  // ── 7. Temp file cleanup (B3) ──
+  try {
+    const tempFiles = [
+      '_current_prompt.md.tmp',
+      'state.json.tmp',
+      'tasks.json.tmp',
+    ];
+    for (const tmpName of tempFiles) {
+      const tmpPath = resolve(copilotDir, tmpName);
+      if (existsSync(tmpPath)) {
+        unlinkSync(tmpPath);
+        repairs.push(`Cleaned up temp file: ${tmpName}`);
+      }
+    }
+  } catch { /* non-critical */ }
+
+  // ── 8. Disk space check (B4) ──
+  try {
+    const probePath = resolve(copilotDir, '.disk_probe');
+    writeFileSync(probePath, 'probe');
+    unlinkSync(probePath);
+  } catch (err) {
+    if (err.code === 'ENOSPC' || err.code === 'EDQUOT') {
+      blockers.push('Disk full — cannot write to project directory. Free up space before running.');
+    } else if (err.code === 'EACCES' || err.code === 'EPERM') {
+      blockers.push(`Permission denied writing to ${copilotDir}. Check directory permissions.`);
+    }
+    // Other errors are non-critical (e.g., copilotDir doesn't exist yet)
+  }
+
+  // ── 9. File permissions check (B5) ──
+  try {
+    const criticalFiles = ['tasks.json', 'state.json', 'config.json'];
+    for (const fileName of criticalFiles) {
+      const filePath = resolve(copilotDir, fileName);
+      if (existsSync(filePath)) {
+        try {
+          // Verify write access
+          accessSync(filePath, constants.R_OK | constants.W_OK);
+        } catch (permErr) {
+          if (permErr.code === 'EACCES' || permErr.code === 'EPERM') {
+            blockers.push(`No read/write permission on ${fileName}. Fix with: chmod 644 ${filePath}`);
+          }
+        }
+      }
+    }
+  } catch { /* non-critical */ }
+
+  // ── 10. Task/Checkpoint consistency (E1, E4) ──
+  if (options.checkpoint && options.tasks) {
+    try {
+      const consistency = options.checkpoint.validateConsistency(options.tasks);
+      if (!consistency.ok) {
+        repairs.push(...consistency.repairs);
+        // Write back repaired tasks
+        const tasksPath = resolve(copilotDir, 'tasks.json');
+        writeJSON(tasksPath, options.tasks);
+      }
+    } catch (err) {
+      warnings.push(`Consistency check failed: ${err.message}`);
+    }
+  }
+
+  // ── Report ──
+  if (repairs.length > 0) {
+    log.info(`🔧 Pre-flight: ${repairs.length} issue(s) auto-repaired`);
+    for (const r of repairs) {
+      log.dim(`   ✅ ${r}`);
+    }
+  }
+
+  if (warnings.length > 0) {
+    for (const w of warnings) {
+      log.warn(`   ⚠ ${w}`);
+    }
+  }
+
+  if (blockers.length > 0) {
+    for (const b of blockers) {
+      log.error(`   🛑 ${b}`);
+    }
+  }
+
+  if (repairs.length === 0 && warnings.length === 0 && blockers.length === 0) {
+    log.dim('Pre-flight: all checks passed ✓');
+  }
+
+  return { ok: blockers.length === 0, repairs, warnings, blockers };
+}
+
+/**
+ * Layer 3: Phase entry validation — called before each automation phase.
+ *
+ * Ensures the environment is in the correct state for the target phase:
+ *   - develop: correct branch, clean-enough index
+ *   - pr:      has diff to commit, network is reachable
+ *   - review:  PR exists and is in 'open' state
+ *   - merge:   PR is approved or at least not rejected
+ *
+ * @param {string} projectDir - Project root
+ * @param {object} task - Current task object
+ * @param {object} checkpoint - Checkpoint manager
+ * @param {string} targetPhase - 'develop' | 'pr' | 'review' | 'merge'
+ * @param {object} [extra] - Extra context (e.g., prInfo for review/merge)
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function validatePhaseEntry(projectDir, task, checkpoint, targetPhase, extra = {}) {
+  try {
+    switch (targetPhase) {
+      case 'develop': {
+        // Verify we can identify current branch (not detached)
+        const current = git.currentBranch(projectDir);
+        if (!current) {
+          git.recoverDetachedHead(projectDir);
+          const recovered = git.currentBranch(projectDir);
+          if (!recovered) {
+            return { ok: false, error: 'Cannot determine current branch (detached HEAD, recovery failed)' };
+          }
+        }
+        return { ok: true, error: null };
+      }
+
+      case 'pr': {
+        // Verify we're on the task's feature branch
+        const current = git.currentBranch(projectDir);
+        if (current !== task.branch) {
+          return { ok: false, error: `Expected branch '${task.branch}' but on '${current}'` };
+        }
+        return { ok: true, error: null };
+      }
+
+      case 'review': {
+        // Verify PR exists and is open
+        if (!extra.prNumber) {
+          return { ok: false, error: 'No PR number available for review phase' };
+        }
+        const prState = github.getPRState(projectDir, extra.prNumber);
+        if (prState === 'merged') {
+          return { ok: false, error: `PR #${extra.prNumber} is already merged` };
+        }
+        if (prState === 'closed') {
+          return { ok: false, error: `PR #${extra.prNumber} was closed — needs re-creation` };
+        }
+        return { ok: true, error: null };
+      }
+
+      case 'merge': {
+        // Verify PR is in a mergeable state
+        if (!extra.prNumber) {
+          return { ok: false, error: 'No PR number available for merge phase' };
+        }
+        const prState = github.getPRState(projectDir, extra.prNumber);
+        if (prState === 'merged') {
+          // Already merged — this is fine, skip merge
+          return { ok: true, error: null };
+        }
+        if (prState === 'closed') {
+          return { ok: false, error: `PR #${extra.prNumber} is closed — cannot merge` };
+        }
+        return { ok: true, error: null };
+      }
+
+      default:
+        return { ok: true, error: null };
+    }
+  } catch (err) {
+    return { ok: false, error: `Phase validation error: ${err.message}` };
+  }
+}
+
+/**
+ * Remove the PID lock file (called on clean exit).
+ */
+export function releaseLock(projectDir) {
+  const pidPath = resolve(projectDir, '.codex-copilot/.pid');
+  try {
+    if (existsSync(pidPath)) {
+      unlinkSync(pidPath);
+    }
+  } catch { /* best effort */ }
+}
+
+export const selfHeal = {
+  preFlightCheck,
+  validatePhaseEntry,
+  releaseLock,
+};