@jojonax/codex-copilot 1.5.1 → 1.5.2

package/bin/cli.js

@@ -24,6 +24,7 @@ import { retry } from '../src/commands/retry.js';
 import { skip } from '../src/commands/skip.js';
 import { usage } from '../src/commands/usage.js';
 import { evolve } from '../src/commands/evolve.js';
+import { fix } from '../src/commands/fix.js';
 import { log } from '../src/utils/logger.js';
 import { checkForUpdates } from '../src/utils/update-check.js';
 
@@ -102,6 +103,12 @@ async function main() {
         process.exit(0);
         break;
 
+      case 'fix':
+      case 'repair':
+        await fix(projectDir);
+        process.exit(0);
+        break;
+
       case 'evolve':
       case 'next':
         if (!existsSync(resolve(projectDir, '.codex-copilot/config.json'))) {
@@ -150,6 +157,7 @@ async function main() {
         console.log('    skip <id> Force-skip a task to unblock dependents');
         console.log('    usage     Show AI token usage for recent sessions');
         console.log('    evolve    Start next PRD iteration round (gap analysis → plan → run)');
+        console.log('    fix       Repair corrupted project files');
         console.log('    update    Update to latest version');
         console.log('');
         console.log('  Workflow:');

package/package.json

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

package/src/commands/evolve.js

@@ -13,15 +13,10 @@ import { log } from '../utils/logger.js';
 import { provider } from '../utils/provider.js';
 import { readPRD } from '../utils/detect-prd.js';
 import { closePrompt } from '../utils/prompt.js';
+import { readJSON, writeJSON } from '../utils/json.js';
 import { run } from './run.js';
 
-function readJSON(path) {
-  return JSON.parse(readFileSync(path, 'utf-8'));
-}
 
-function writeJSON(path, data) {
-  writeFileSync(path, JSON.stringify(data, null, 2));
-}
 
 /**
  * Load or initialize rounds.json

package/src/commands/fix.js

@@ -0,0 +1,399 @@
+/**
+ * codex-copilot fix - Repair corrupted or malformed project files
+ *
+ * Scans and repairs all JSON files in .codex-copilot/:
+ *   - tasks.json:  validates structure, fixes missing fields, re-indexes
+ *   - state.json:  validates checkpoint schema, resets if unrecoverable
+ *   - config.json: validates required fields
+ *   - rounds.json: validates round history structure
+ *
+ * Can also be invoked programmatically via autoFix() for self-healing.
+ */
+
+import { existsSync, readdirSync } from 'fs';
+import { resolve, basename } from 'path';
+import { log } from '../utils/logger.js';
+import { readJSON, writeJSON, repairRawJSON } from '../utils/json.js';
+
+// ─── Schema Validators & Fixers ───────────────────────────
+
+const TASK_REQUIRED_FIELDS = ['id', 'title', 'description', 'branch', 'status'];
+const VALID_TASK_STATUSES = ['pending', 'in_progress', 'completed', 'blocked', 'skipped', 'developed'];
+
+const DEFAULT_STATE = {
+  current_task: 0,
+  phase: null,
+  phase_step: null,
+  current_pr: null,
+  review_round: 0,
+  branch: null,
+  status: 'initialized',
+  last_updated: new Date().toISOString(),
+};
+
+/**
+ * Fix a single JSON file: parse → validate → repair → write back.
+ * Returns { fixed, errors, warnings } report.
+ */
+function fixFile(filePath, validator) {
+  const report = { file: basename(filePath), fixed: false, repairs: [], errors: [] };
+
+  if (!existsSync(filePath)) {
+    report.errors.push('File does not exist');
+    return report;
+  }
+
+  // Step 1: Try to parse (with auto-repair in readJSON)
+  let data;
+  try {
+    data = readJSON(filePath);
+    // readJSON already does basic corruption repair (BOM, trailing commas, etc.)
+  } catch (parseErr) {
+    // readJSON's auto-repair failed — try our deeper repair
+    try {
+      data = repairRawJSON(filePath);
+      report.repairs.push('Recovered from deep corruption via raw repair');
+    } catch {
+      report.errors.push(`Unrecoverable parse error: ${parseErr.message}`);
+      return report;
+    }
+  }
+
+  // Step 2: Run schema validator/fixer
+  if (validator) {
+    const { data: fixedData, repairs } = validator(data);
+    if (repairs.length > 0) {
+      data = fixedData;
+      report.repairs.push(...repairs);
+    }
+  }
+
+  // Step 3: Write back if any repairs were made
+  if (report.repairs.length > 0) {
+    try {
+      writeJSON(filePath, data);
+      report.fixed = true;
+    } catch (writeErr) {
+      report.errors.push(`Failed to write repaired file: ${writeErr.message}`);
+    }
+  }
+
+  return report;
+}
+
+// ─── Validators ───────────────────────────────────────────
+
+function validateTasks(data) {
+  const repairs = [];
+
+  // Ensure top-level structure
+  if (!data || typeof data !== 'object') {
+    return { data: { project: 'unknown', total: 0, tasks: [] }, repairs: ['Rebuilt empty tasks structure'] };
+  }
+
+  if (!Array.isArray(data.tasks)) {
+    if (data.tasks && typeof data.tasks === 'object') {
+      data.tasks = Object.values(data.tasks);
+      repairs.push('Converted tasks from object to array');
+    } else {
+      data.tasks = [];
+      repairs.push('Missing tasks array — initialized empty');
+    }
+  }
+
+  // Validate each task
+  for (let i = 0; i < data.tasks.length; i++) {
+    const task = data.tasks[i];
+
+    // Ensure task is an object
+    if (!task || typeof task !== 'object') {
+      data.tasks[i] = { id: i + 1, title: `Task ${i + 1}`, description: '', branch: `feature/${String(i + 1).padStart(3, '0')}-unknown`, status: 'pending' };
+      repairs.push(`Task at index ${i}: rebuilt from invalid value`);
+      continue;
+    }
+
+    // Fix missing ID
+    if (task.id === undefined || task.id === null) {
+      task.id = i + 1;
+      repairs.push(`Task at index ${i}: assigned missing id=${task.id}`);
+    }
+
+    // Fix missing required fields
+    if (!task.title) { task.title = `Untitled Task ${task.id}`; repairs.push(`Task #${task.id}: added missing title`); }
+    if (!task.description) { task.description = task.title; repairs.push(`Task #${task.id}: added missing description`); }
+    if (!task.branch) {
+      const slug = task.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 30);
+      task.branch = `feature/${String(task.id).padStart(3, '0')}-${slug}`;
+      repairs.push(`Task #${task.id}: generated missing branch name`);
+    }
+
+    // Fix invalid status
+    if (!task.status || !VALID_TASK_STATUSES.includes(task.status)) {
+      const oldStatus = task.status;
+      task.status = 'pending';
+      repairs.push(`Task #${task.id}: invalid status '${oldStatus}' → 'pending'`);
+    }
+
+    // Ensure depends_on is an array
+    if (task.depends_on && !Array.isArray(task.depends_on)) {
+      task.depends_on = [];
+      repairs.push(`Task #${task.id}: fixed invalid depends_on`);
+    }
+
+    // Ensure acceptance is an array
+    if (task.acceptance && !Array.isArray(task.acceptance)) {
+      if (typeof task.acceptance === 'string') {
+        task.acceptance = [task.acceptance];
+        repairs.push(`Task #${task.id}: converted acceptance string to array`);
+      } else {
+        task.acceptance = [];
+        repairs.push(`Task #${task.id}: fixed invalid acceptance`);
+      }
+    }
+  }
+
+  // Check for duplicate IDs
+  const idMap = new Map();
+  for (const task of data.tasks) {
+    if (idMap.has(task.id)) {
+      // Reassign duplicate ID
+      const newId = Math.max(...data.tasks.map(t => t.id)) + 1;
+      repairs.push(`Task #${task.id}: duplicate ID → reassigned to #${newId}`);
+      task.id = newId;
+    }
+    idMap.set(task.id, true);
+  }
+
+  // Fix total count
+  if (data.total !== data.tasks.length) {
+    repairs.push(`total: ${data.total} → ${data.tasks.length}`);
+    data.total = data.tasks.length;
+  }
+
+  // Ensure project name exists
+  if (!data.project) {
+    data.project = 'Unknown Project';
+    repairs.push('Added missing project name');
+  }
+
+  return { data, repairs };
+}
+
+function validateState(data) {
+  const repairs = [];
+
+  if (!data || typeof data !== 'object') {
+    return { data: { ...DEFAULT_STATE }, repairs: ['Rebuilt from scratch — was not an object'] };
+  }
+
+  // Check and fix each expected field
+  if (typeof data.current_task !== 'number') {
+    data.current_task = parseInt(data.current_task, 10) || 0;
+    repairs.push(`current_task: fixed type → ${data.current_task}`);
+  }
+  if (typeof data.review_round !== 'number') {
+    data.review_round = parseInt(data.review_round, 10) || 0;
+    repairs.push(`review_round: fixed type → ${data.review_round}`);
+  }
+
+  // Validate phase
+  const validPhases = ['develop', 'pr', 'review', 'merge', null];
+  if (!validPhases.includes(data.phase)) {
+    repairs.push(`phase: invalid '${data.phase}' → null`);
+    data.phase = null;
+    data.phase_step = null;
+  }
+
+  // Ensure last_updated exists
+  if (!data.last_updated) {
+    data.last_updated = new Date().toISOString();
+    repairs.push('Added missing last_updated');
+  }
+
+  return { data, repairs };
+}
+
+function validateConfig(data) {
+  const repairs = [];
+
+  if (!data || typeof data !== 'object') {
+    return { data: {}, repairs: ['Config was not an object — replaced with empty'] };
+  }
+
+  // Validate provider
+  if (data.provider && typeof data.provider !== 'string') {
+    data.provider = 'codex-cli';
+    repairs.push('Invalid provider — reset to codex-cli');
+  }
+
+  // Validate numeric fields
+  for (const field of ['max_review_rounds', 'review_poll_interval', 'review_wait_timeout']) {
+    if (data[field] !== undefined && typeof data[field] !== 'number') {
+      const parsed = parseInt(data[field], 10);
+      if (!isNaN(parsed)) {
+        data[field] = parsed;
+        repairs.push(`${field}: converted string to number`);
+      } else {
+        delete data[field];
+        repairs.push(`${field}: removed invalid value`);
+      }
+    }
+  }
+
+  return { data, repairs };
+}
+
+function validateRounds(data) {
+  const repairs = [];
+
+  if (!data || typeof data !== 'object') {
+    return { data: { current_round: 0, rounds: [] }, repairs: ['Rebuilt rounds structure'] };
+  }
+
+  if (typeof data.current_round !== 'number') {
+    data.current_round = parseInt(data.current_round, 10) || 0;
+    repairs.push(`current_round: fixed type → ${data.current_round}`);
+  }
+
+  if (!Array.isArray(data.rounds)) {
+    data.rounds = [];
+    repairs.push('Missing rounds array — initialized empty');
+  }
+
+  return { data, repairs };
+}
+
+// ─── File → Validator mapping ─────────────────────────────
+
+const FILE_VALIDATORS = {
+  'tasks.json': validateTasks,
+  'state.json': validateState,
+  'config.json': validateConfig,
+  'rounds.json': validateRounds,
+};
+
+// ─── Public API ───────────────────────────────────────────
+
+/**
+ * Interactive fix command — scans and repairs all project files.
+ * Called when user runs: codex-copilot fix
+ */
+export async function fix(projectDir) {
+  log.title('🔧 Codex-Copilot File Repair');
+  log.blank();
+
+  const copilotDir = resolve(projectDir, '.codex-copilot');
+  if (!existsSync(copilotDir)) {
+    log.error('Project not initialized. Run: codex-copilot init');
+    process.exit(1);
+  }
+
+  log.info('Scanning .codex-copilot/ for issues...');
+  log.blank();
+
+  const results = runRepairs(copilotDir);
+  printReport(results);
+}
+
+/**
+ * Auto-fix — called programmatically by other commands when errors are detected.
+ * Returns true if all files are healthy (either clean or successfully repaired).
+ * @param {string} projectDir - Project root directory
+ * @param {object} [options]
+ * @param {boolean} [options.silent] - Suppress non-error output
+ * @param {string[]} [options.files] - Only fix specific files (e.g. ['tasks.json'])
+ * @returns {{ ok: boolean, repaired: string[] }}
+ */
+export function autoFix(projectDir, options = {}) {
+  const copilotDir = resolve(projectDir, '.codex-copilot');
+  if (!existsSync(copilotDir)) {
+    return { ok: false, repaired: [] };
+  }
+
+  if (!options.silent) {
+    log.info('🔧 Auto-repairing project files...');
+  }
+
+  const results = runRepairs(copilotDir, options.files);
+  const repaired = results.filter(r => r.fixed).map(r => r.file);
+  const failed = results.filter(r => r.errors.length > 0).map(r => r.file);
+
+  if (!options.silent) {
+    for (const r of results) {
+      if (r.fixed) {
+        log.info(`  ✅ ${r.file}: ${r.repairs.length} issue(s) repaired`);
+      }
+      for (const err of r.errors) {
+        log.error(`  ❌ ${r.file}: ${err}`);
+      }
+    }
+  }
+
+  return { ok: failed.length === 0, repaired };
+}
+
+// ─── Internal helpers ─────────────────────────────────────
+
+function runRepairs(copilotDir, filterFiles) {
+  const results = [];
+
+  for (const [fileName, validator] of Object.entries(FILE_VALIDATORS)) {
+    if (filterFiles && !filterFiles.includes(fileName)) continue;
+    const filePath = resolve(copilotDir, fileName);
+    if (!existsSync(filePath)) continue;
+    results.push(fixFile(filePath, validator));
+  }
+
+  // Also scan for any other .json files (e.g. tasks_round_N.json)
+  if (!filterFiles) {
+    try {
+      const files = readdirSync(copilotDir).filter(f =>
+        f.endsWith('.json') &&
+        !f.endsWith('.tmp') &&
+        !f.endsWith('.bak') &&
+        !Object.keys(FILE_VALIDATORS).includes(f)
+      );
+      for (const fileName of files) {
+        const filePath = resolve(copilotDir, fileName);
+        results.push(fixFile(filePath, null)); // Parse-only repair, no schema validation
+      }
+    } catch { /* ignore directory read errors */ }
+  }
+
+  return results;
+}
+
+function printReport(results) {
+  const totalFixed = results.filter(r => r.fixed).length;
+  const totalErrors = results.filter(r => r.errors.length > 0).length;
+  const totalClean = results.filter(r => !r.fixed && r.errors.length === 0).length;
+
+  for (const r of results) {
+    if (r.errors.length > 0) {
+      log.error(`❌ ${r.file}:`);
+      for (const err of r.errors) {
+        log.error(`   ${err}`);
+      }
+    } else if (r.fixed) {
+      log.info(`🔧 ${r.file}: ${r.repairs.length} issue(s) repaired`);
+      for (const repair of r.repairs) {
+        log.dim(`   ↳ ${repair}`);
+      }
+    } else {
+      log.info(`✅ ${r.file}: OK`);
+    }
+    log.blank();
+  }
+
+  // Summary
+  log.blank();
+  if (totalErrors > 0) {
+    log.error(`Summary: ${totalFixed} file(s) repaired, ${totalErrors} file(s) have unrecoverable errors`);
+    log.warn('For unrecoverable files, try: codex-copilot reset');
+  } else if (totalFixed > 0) {
+    log.title(`✅ Repaired ${totalFixed} file(s), ${totalClean} file(s) were already OK`);
+  } else {
+    log.title('✅ All files are healthy — no repairs needed');
+  }
+  log.blank();
+}

package/src/commands/reset.js

@@ -2,11 +2,12 @@
  * codex-copilot reset - Reset state
  */
 
-import { readFileSync, writeFileSync, existsSync, unlinkSync } from 'fs';
+import { existsSync, unlinkSync } from 'fs';
 import { resolve } from 'path';
 import { log } from '../utils/logger.js';
 import { confirm, closePrompt } from '../utils/prompt.js';
 import { createCheckpoint } from '../utils/checkpoint.js';
+import { readJSON, writeJSON } from '../utils/json.js';
 
 export async function reset(projectDir) {
   const statePath = resolve(projectDir, '.codex-copilot/state.json');
@@ -38,11 +39,11 @@ export async function reset(projectDir) {
 
   // Reset task statuses
   if (resetTasks && existsSync(tasksPath)) {
-    const tasks = JSON.parse(readFileSync(tasksPath, 'utf-8'));
+    const tasks = readJSON(tasksPath);
     for (const task of tasks.tasks) {
       task.status = 'pending';
     }
-    writeFileSync(tasksPath, JSON.stringify(tasks, null, 2));
+    writeJSON(tasksPath, tasks);
     log.info('Task statuses reset');
   }
 

package/src/commands/retry.js

@@ -13,14 +13,9 @@ import { log, progressBar } from '../utils/logger.js';
 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';
 
-function readJSON(path) {
-  return JSON.parse(readFileSync(path, 'utf-8'));
-}
 
-function writeJSON(path, data) {
-  writeFileSync(path, JSON.stringify(data, null, 2));
-}
 
 export async function retry(projectDir) {
   const tasksPath = resolve(projectDir, '.codex-copilot/tasks.json');

package/src/commands/run.js

@@ -13,17 +13,10 @@ import { github } from '../utils/github.js';
 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';
 
 const maxRateLimitRetries = 3;
 
-function readJSON(path) {
-  return JSON.parse(readFileSync(path, 'utf-8'));
-}
-
-function writeJSON(path, data) {
-  writeFileSync(path, JSON.stringify(data, null, 2));
-}
-
 export async function run(projectDir) {
   const tasksPath = resolve(projectDir, '.codex-copilot/tasks.json');
   const configPath = resolve(projectDir, '.codex-copilot/config.json');
@@ -31,14 +24,53 @@ export async function run(projectDir) {
 
   let tasks;
   let state;
+
+  // Load tasks.json (required)
   try {
     tasks = readJSON(tasksPath);
-    state = checkpoint.load();
   } catch (err) {
-    log.error(`Failed to read task/state files: ${err.message}`);
-    log.warn('Files may be corrupted. Run: codex-copilot reset');
-    closePrompt();
-    process.exit(1);
+    log.warn(`tasks.json read issue: ${err.message}`);
+    log.info('Attempting auto-repair...');
+
+    // Try auto-fix (deep repair + schema validation)
+    const { autoFix } = await import('./fix.js');
+    const fixResult = autoFix(projectDir, { files: ['tasks.json'] });
+
+    if (fixResult.ok && fixResult.repaired.includes('tasks.json')) {
+      try {
+        tasks = readJSON(tasksPath);
+        log.info('✅ tasks.json auto-repaired successfully');
+      } catch {
+        // Auto-fix wrote the file but it's still not readable (shouldn't happen)
+        log.error('Auto-repair wrote file but it remains unreadable');
+      }
+    }
+
+    // If still no tasks, try backup
+    if (!tasks && existsSync(tasksPath + '.bak')) {
+      log.info('Trying backup file...');
+      try {
+        tasks = readJSON(tasksPath + '.bak');
+        writeJSON(tasksPath, tasks);
+        log.info('✅ Restored tasks.json from backup');
+      } catch {
+        log.error('Backup is also corrupted');
+      }
+    }
+
+    if (!tasks) {
+      log.error('Cannot recover tasks.json. Run: codex-copilot fix');
+      closePrompt();
+      process.exit(1);
+    }
+  }
+
+  // Load state.json (optional — falls back to default)
+  try {
+    state = checkpoint.load();
+  } catch {
+    log.warn('State file corrupted — resetting to initial state');
+    state = checkpoint.reset();
   }
   const config = existsSync(configPath) ? readJSON(configPath) : {};
 
@@ -670,14 +702,14 @@ ${feedback}
   writeFileSync(promptPath, fixPrompt);
 
   let rateLimitRetries = 0;
-  while (rateLimitRetries < 3) {
+  while (rateLimitRetries < maxRateLimitRetries) {
     const result = await provider.executePrompt(providerId, promptPath, projectDir);
     if (result.ok) {
       break;
     }
     if (result.rateLimited && result.retryAt) {
       rateLimitRetries++;
-      if (rateLimitRetries >= 3) {
+      if (rateLimitRetries >= maxRateLimitRetries) {
         log.warn('Max rate limit retries reached during fix phase');
         break;
       }

package/src/commands/skip.js

@@ -6,17 +6,11 @@
  * stuck and downstream work should continue regardless.
  */
 
-import { readFileSync, writeFileSync } from 'fs';
 import { resolve } from 'path';
 import { log } from '../utils/logger.js';
+import { readJSON, writeJSON } from '../utils/json.js';
 
-function readJSON(path) {
-  return JSON.parse(readFileSync(path, 'utf-8'));
-}
 
-function writeJSON(path, data) {
-  writeFileSync(path, JSON.stringify(data, null, 2));
-}
 
 export async function skip(projectDir, taskId) {
   const tasksPath = resolve(projectDir, '.codex-copilot/tasks.json');

package/src/commands/status.js

@@ -2,10 +2,11 @@
  * codex-copilot status - Show current progress
  */
 
-import { readFileSync, existsSync } from 'fs';
+import { existsSync } from 'fs';
 import { resolve } from 'path';
 import { log, progressBar } from '../utils/logger.js';
 import { createCheckpoint } from '../utils/checkpoint.js';
+import { readJSON } from '../utils/json.js';
 
 export async function status(projectDir) {
   const tasksPath = resolve(projectDir, '.codex-copilot/tasks.json');
@@ -13,7 +14,7 @@ export async function status(projectDir) {
 
   let tasks, state;
   try {
-    tasks = JSON.parse(readFileSync(tasksPath, 'utf-8'));
+    tasks = readJSON(tasksPath);
     state = checkpoint.load();
   } catch (err) {
     log.error(`Failed to read files: ${err.message}`);
@@ -28,7 +29,7 @@ export async function status(projectDir) {
   const roundsPath = resolve(projectDir, '.codex-copilot/rounds.json');
   if (existsSync(roundsPath)) {
     try {
-      const rounds = JSON.parse(readFileSync(roundsPath, 'utf-8'));
+      const rounds = readJSON(roundsPath);
       const currentRound = tasks.round || rounds.current_round || 1;
       const totalCompleted = rounds.rounds.reduce((s, r) => s + r.tasks_completed, 0);
       log.info(`📦 Round: ${currentRound}  |  Total across all rounds: ${totalCompleted} tasks`);

package/src/utils/json.js

@@ -0,0 +1,190 @@
+/**
+ * Safe JSON read/write utilities
+ * 
+ * Provides resilient JSON file operations with:
+ * - Auto-repair of common corruption patterns (trailing commas, BOM, control chars)
+ * - Truncation recovery via progressive trimming and bracket closure
+ * - Atomic writes (temp file + rename) to prevent corruption on crash
+ * - Backup creation on auto-repair
+ */
+
+import { readFileSync, writeFileSync, existsSync, renameSync, copyFileSync } from 'fs';
+
+/**
+ * Read and parse a JSON file with auto-repair on corruption.
+ * Creates a .bak backup before overwriting with repaired content.
+ * @param {string} filePath - Path to JSON file
+ * @returns {any} Parsed JSON data
+ * @throws {Error} If JSON is unrecoverable
+ */
+export function readJSON(filePath) {
+  let raw = readFileSync(filePath, 'utf-8');
+  // Strip BOM if present
+  if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+  try {
+    return JSON.parse(raw);
+  } catch (firstErr) {
+    const data = tryRepair(raw);
+    if (data !== null) {
+      // Save repaired version and backup original
+      try {
+        copyFileSync(filePath, filePath + '.bak');
+        writeJSON(filePath, data);
+      } catch { /* best effort */ }
+      return data;
+    }
+    throw new Error(`Invalid JSON in ${filePath}: ${firstErr.message}`);
+  }
+}
+
+/**
+ * Multi-strategy JSON repair pipeline.
+ * @param {string} raw - Raw file content
+ * @returns {any|null} Parsed data or null if all strategies fail
+ */
+function tryRepair(raw) {
+  // Strategy 1: Basic cleanup (trailing commas, control chars)
+  let cleaned = raw
+    .replace(/,\s*([}\]])/g, '$1')
+    .replace(/[\x00-\x08\x0E-\x1F]/g, '')
+    .trim();
+
+  let result = tryParse(cleaned);
+  if (result !== null) return result;
+
+  // Strategy 2: Truncation recovery — find the last complete } or ] and close
+  // Work backwards: try truncating at each } or ] from the end
+  for (let i = cleaned.length - 1; i >= 0; i--) {
+    if (cleaned[i] === '}' || cleaned[i] === ']') {
+      let candidate = cleaned.substring(0, i + 1);
+      candidate = closeBrackets(candidate);
+      result = tryParse(candidate);
+      if (result !== null) return result;
+
+      // Also try stripping garbage prefix (start from first open bracket)
+      const firstOpen = findFirstOpen(candidate);
+      if (firstOpen > 0) {
+        let stripped = candidate.substring(firstOpen);
+        stripped = closeBrackets(stripped);
+        result = tryParse(stripped);
+        if (result !== null) return result;
+      }
+    }
+  }
+
+  // Strategy 3: Extract {…} or […] from garbage-surrounded content
+  const firstOpen = findFirstOpen(cleaned);
+  if (firstOpen >= 0) {
+    // Find the last } or ] in the string
+    const lastClose = Math.max(cleaned.lastIndexOf('}'), cleaned.lastIndexOf(']'));
+    if (lastClose > firstOpen) {
+      let candidate = cleaned.substring(firstOpen, lastClose + 1);
+      candidate = closeBrackets(candidate);
+      result = tryParse(candidate);
+      if (result !== null) return result;
+    }
+    // Also try from firstOpen to end with bracket closing
+    let candidate = cleaned.substring(firstOpen);
+    candidate = closeBrackets(candidate);
+    result = tryParse(candidate);
+    if (result !== null) return result;
+  }
+
+  return null;
+}
+
+/**
+ * Find the first { or [ in a string
+ */
+function findFirstOpen(s) {
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === '{' || s[i] === '[') return i;
+  }
+  return -1;
+}
+
+/**
+ * Close unmatched brackets/braces in a JSON string.
+ * Properly handles strings (doesn't count brackets inside quoted strings).
+ */
+function closeBrackets(s) {
+  const stack = [];
+  let inString = false;
+  let escaped = false;
+
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (escaped) { escaped = false; continue; }
+    if (ch === '\\' && inString) { escaped = true; continue; }
+    if (ch === '"') { inString = !inString; continue; }
+    if (inString) continue;
+    if (ch === '{') stack.push('}');
+    else if (ch === '[') stack.push(']');
+    else if (ch === '}' || ch === ']') {
+      if (stack.length > 0) stack.pop();
+    }
+  }
+
+  // Append closers in reverse order
+  while (stack.length > 0) s += stack.pop();
+  return s;
+}
+
+/**
+ * Try to parse JSON, return data or null.
+ */
+function tryParse(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write JSON data to file atomically (temp file + rename).
+ * Prevents corruption if process is killed mid-write.
+ * @param {string} filePath - Path to JSON file
+ * @param {any} data - Data to serialize
+ */
+export function writeJSON(filePath, data) {
+  const tempPath = filePath + '.tmp';
+  writeFileSync(tempPath, JSON.stringify(data, null, 2));
+  renameSync(tempPath, filePath);
+}
+
+/**
+ * Deep repair of a severely corrupted JSON file.
+ * Tries readJSON's repair pipeline, then falls back to .bak file.
+ * Used by the fix command when readJSON fails.
+ * @param {string} filePath - Path to corrupted JSON file
+ * @returns {any} Parsed JSON data
+ * @throws {Error} If all repair strategies fail
+ */
+export function repairRawJSON(filePath) {
+  let raw = readFileSync(filePath, 'utf-8');
+  if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+
+  // Try the full repair pipeline
+  const data = tryRepair(raw);
+  if (data !== null) {
+    try {
+      copyFileSync(filePath, filePath + '.bak');
+      writeJSON(filePath, data);
+    } catch { /* best effort */ }
+    return data;
+  }
+
+  // Try to recover from .bak file
+  const bakPath = filePath + '.bak';
+  if (existsSync(bakPath)) {
+    try {
+      const bakRaw = readFileSync(bakPath, 'utf-8');
+      const bakData = tryRepair(bakRaw) ?? JSON.parse(bakRaw);
+      writeJSON(filePath, bakData);
+      return bakData;
+    } catch { /* backup also corrupt */ }
+  }
+
+  throw new Error(`All repair strategies failed for ${filePath}`);
+}

package/src/utils/provider.js

@@ -718,7 +718,7 @@ function parseRateLimitError(output) {
  * Check current Codex 7d quota usage before execution.
  * Reads the latest rollout file for quota data.
  * 
- * @param {number} threshold - Percentage at which to block (default 98)
+ * @param {number} threshold - Percentage at which to block (default 97)
  * @returns {{ ok: boolean, quota5h: number|null, quota7d: number|null, warning: boolean }}
  */
 export function checkQuotaBeforeExecution(threshold = 97) {