praxis-sec 1.0.0

package/cli/commands/agent-fix.js

@@ -0,0 +1,1245 @@
+/**
+ * Praxis Security Agent — Interactive Fix Loop
+ * ================================================
+ *
+ * Scans your codebase, then for each affected file:
+ *   1. Generates a precise multi-edit fix plan via LLM (one plan per file,
+ *      addressing every finding in that file at once)
+ *   2. Shows you exactly what it will change (unified diff with line numbers)
+ *   3. Asks you to accept, skip, or quit
+ *   4. Applies the changes atomically
+ *   5. Re-scans to verify the findings are resolved
+ *   6. Logs every change to .praxis/fixes.jsonl
+ *
+ * USAGE:
+ *   praxis agent [path]              Interactive fix loop
+ *   praxis agent . --plan-only       Generate plans, never write
+ *   praxis agent . --severity high   Only fix high+ severity
+ *   praxis agent . --branch fixes    Create a branch, commit per file
+ *   praxis agent . --pr              After fixing, push and open a PR
+ *   praxis agent . --provider deepseek-flash
+ *
+ * SAFETY:
+ *   - Refuses to operate on a dirty git tree (use --allow-dirty to override)
+ *   - Always shows a diff before any write
+ *   - Re-scans after each batch to verify the fix
+ *   - Plans may create new files (e.g., .env.example) but cannot edit
+ *     .env, secrets, lockfiles, or build artifacts
+ *   - Every applied change is logged for audit & undo (`praxis undo`)
+ */
+
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import path, { dirname } from 'path';
+import { createInterface } from 'readline';
+
+const __filename = fileURLToPath(import.meta.url); // praxis-ignore — module's own path via import.meta.url, not user input
+const __dirname = dirname(__filename);
+const praxisDir = path.resolve(__dirname, '../..');
+import { execFileSync } from 'child_process';
+import chalk from 'chalk';
+import ora from 'ora';
+import { autoDetectProvider } from '../providers/llm-provider.js';
+import { auditCommand } from './audit.js';
+import { ASTParser } from '../core/ast/index.js';
+import * as output from '../utils/output.js';
+
+const SEV_RANK   = { critical: 4, high: 3, medium: 2, low: 1, info: 0 };
+const NEVER_EDIT = [
+  /(^|\/)\.env(\.|$)/i,
+  /\.pem$|\.key$|\.p12$|\.pfx$/i,
+  /package-lock\.json$|yarn\.lock$|pnpm-lock\.yaml$/i,
+  /(^|\/)node_modules\//,
+  /(^|\/)dist\//,
+  /(^|\/)build\//,
+  /\.min\.(js|css)$/,
+];
+// Files the agent IS allowed to create or update freely (companions to fixes)
+const SAFE_NEW_FILES = [
+  /(^|\/)\.env\.example$/i,
+  /(^|\/)\.env\.sample$/i,
+  /(^|\/)\.gitignore$/i,
+];
+
+const FIX_LOG_DIR  = '.praxis';
+const FIX_LOG_FILE = 'fixes.jsonl';
+
+// =============================================================================
+// MAIN
+// =============================================================================
+
+export async function agentFixCommand(targetPath = '.', options = {}) {
+  const root = path.resolve(targetPath);
+
+  if (!fs.existsSync(root)) {
+    output.error(`Path does not exist: ${root}`);
+    process.exit(1);
+  }
+
+  console.log();
+  output.header('Praxis — Security Agent');
+  console.log(chalk.gray('  I will scan, plan each fix, ask before changing anything,'));
+  console.log(chalk.gray('  and verify the fix worked. You stay in control.'));
+  console.log();
+
+  // ── Git safety check ─────────────────────────────────────────────────────
+  const initialBranch = getCurrentBranch(root);
+  if (!options.allowDirty) {
+    const state = checkGitState(root);
+    if (state === 'not-a-repo') {
+      console.log(chalk.yellow('  Note: this is not a git repository.'));
+      console.log(chalk.gray('  Changes cannot be reverted automatically.'));
+      if (options.ci) {
+        console.log(chalk.gray('  CI mode active: automatically continuing.'));
+      } else {
+        const ok = await confirm('  Continue anyway?');
+        if (!ok) { console.log(chalk.gray('  Aborted.\n')); return; }
+      }
+    } else if (state === 'dirty') {
+      output.error('Working tree has uncommitted changes.');
+      console.log(chalk.gray('  Commit or stash first, or pass --allow-dirty.'));
+      process.exit(1);
+    }
+  }
+
+  // ── Optional branch isolation ────────────────────────────────────────────
+  let branchCreated = null;
+  if (options.branch) {
+    if (!initialBranch) {
+      console.log(chalk.yellow('  --branch requires a git repository. Skipping branch creation.'));
+    } else {
+      const stamp      = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 16);
+      const branchName = options.branch === true
+        ? `praxis/fixes-${stamp}`
+        : String(options.branch);
+      try {
+        execFileSync('git', ['checkout', '-b', branchName], { cwd: root, stdio: 'pipe' });
+        branchCreated = branchName;
+        console.log(chalk.gray(`  Branch: ${chalk.cyan(branchName)}`));
+      } catch (err) {
+        output.error(`Could not create branch ${branchName}: ${err.message}`);
+        process.exit(1);
+      }
+    }
+  }
+
+  // ── Load LLM provider ────────────────────────────────────────────────────
+  const provider = autoDetectProvider(root, {
+    provider: options.provider,
+    model:    options.model,
+    think:    options.think || false,
+  });
+  if (!provider) {
+    output.error('No LLM provider available.');
+    console.log(chalk.gray('  Set one of: DEEPSEEK_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, MOONSHOT_API_KEY, XAI_API_KEY'));
+    process.exit(1);
+  }
+  console.log(chalk.gray(`  Provider: ${chalk.cyan(provider.name)}`));
+
+  if (options.sandbox) {
+    console.log(chalk.gray('  Sandbox:  ' + chalk.green('active') + ' (verifying fixes in Docker container)'));
+  }
+
+  // ── Run the scan ─────────────────────────────────────────────────────────
+  const scanSpinner = ora({ text: 'Scanning for issues...', color: 'cyan' }).start();
+  let scanResult;
+  try {
+    scanResult = await auditCommand(root, { _agenticInner: true, deep: false, deps: false, noAi: true });
+  } catch (err) {
+    scanSpinner.fail('Scan failed');
+    output.error(err.message);
+    process.exit(1);
+  }
+  scanSpinner.stop();
+
+  // ── Filter findings ──────────────────────────────────────────────────────
+  const minSev  = options.severity || 'low';
+  const minRank = SEV_RANK[minSev] ?? 1;
+
+  const findings = (scanResult.findings ?? []).filter(f => {
+    if (!f.file) return false;
+    if ((SEV_RANK[f.severity] ?? 0) < minRank) return false;
+    const rel = f.file.replace(/\\/g, '/');
+    if (NEVER_EDIT.some(p => p.test(rel))) return false;
+    const abs = path.resolve(root, f.file);
+    return fs.existsSync(abs);
+  });
+
+  if (findings.length === 0) {
+    output.success('No fixable findings at the requested severity.');
+    console.log();
+    return;
+  }
+
+  // ── Group by file ────────────────────────────────────────────────────────
+  const byFile = new Map();
+  for (const f of findings) {
+    const list = byFile.get(f.file) ?? [];
+    list.push(f);
+    byFile.set(f.file, list);
+  }
+
+  console.log(chalk.cyan(`  Found ${findings.length} fixable finding(s) across ${byFile.size} file(s)`));
+  console.log();
+
+  // ── Fix loop ─────────────────────────────────────────────────────────────
+  const applied = []; // { file, plan, verified }
+  const skipped = []; // { file, findings, reason }
+  let stopped   = false;
+  let i         = 0;
+
+  for (const [filePath, fileFindings] of byFile) {
+    i++;
+    if (stopped) break;
+
+    const idx = `[${i}/${byFile.size}]`;
+    console.log();
+    console.log(chalk.bold(`  ${idx} ${chalk.cyan(filePath)} ${chalk.gray(`— ${fileFindings.length} finding(s)`)}`));
+    for (const f of fileFindings) {
+      console.log(`      ${severityLabel(f.severity)} ${f.title}${f.line ? chalk.gray(` (line ${f.line})`) : ''}`);
+    }
+
+    // ── Plan → apply → verify ladder, with one evidence-fed retry ──────────
+    const maxAttempts = options.maxAttempts || 2;
+    let retryEvidence = '';
+    let decision = null;
+    let finalPlan = null;
+    let finalVerified = null;
+    let snapshots = []; // pre-fix file state, captured once on first attempt
+    let ladderFailed = false; // verification failed with nothing resolved
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      if (retryEvidence) {
+        console.log(chalk.yellow(`      Verification failed — retrying plan with failure evidence (attempt ${attempt}/${maxAttempts})`));
+      }
+
+      // Generate plan
+      const planSpinner = ora({ text: retryEvidence ? 'Regenerating fix plan...' : 'Generating fix plan...', color: 'cyan', indent: 6 }).start();
+      const planResult = await generateBatchPlan(provider, root, filePath, fileFindings, retryEvidence);
+      planSpinner.stop();
+
+      if (!planResult.ok) {
+        const detail = describePlanFailure(planResult);
+        console.log(chalk.yellow(`      ${detail.message}`));
+        logFailure(root, { timestamp: new Date().toISOString(), file: filePath, findings: fileFindings.map(f => ({ title: f.title, line: f.line, rule: f.rule })), ...planResult });
+        skipped.push({ file: filePath, findings: fileFindings, reason: detail.reason });
+        finalPlan = null;
+        break;
+      }
+      const plan = planResult.plan;
+
+      // Validate (allows new safe files like .env.example)
+      const validation = validatePlan(root, plan);
+      if (!validation.ok) {
+        console.log(chalk.yellow(`      Plan invalid: ${validation.reason}`));
+        logFailure(root, { timestamp: new Date().toISOString(), file: filePath, findings: fileFindings.map(f => ({ title: f.title, line: f.line, rule: f.rule })), reason: 'validation-rejected', detail: validation.reason, plan });
+        skipped.push({ file: filePath, findings: fileFindings, reason: `plan-invalid: ${validation.reason}` });
+        finalPlan = null;
+        break;
+      }
+
+      // Show plan
+      printPlan(plan, root);
+
+      if (options.planOnly) {
+        console.log(chalk.gray('      (plan-only mode — not applying)'));
+        finalPlan = null;
+        break;
+      }
+
+      // Decision (prompt once; retries reuse the first decision)
+      if (decision === null) {
+        const risk = (plan.risk || 'medium').toLowerCase();
+        if (options.yolo || options.ci) {
+          decision = 'a';
+          console.log(chalk.gray(`      (${options.ci ? 'ci' : 'yolo'}: auto-accepting)`));
+        } else if (options.autoLow && risk === 'low') {
+          decision = 'a';
+          console.log(chalk.gray('      (auto-low: low-risk, auto-accepting)'));
+        } else {
+          decision = await promptDecision(plan, root);
+        }
+      }
+
+      if (decision === 'q' || decision === 'quit') {
+        console.log(chalk.gray('      Stopping.'));
+        stopped = true;
+        finalPlan = null;
+        break;
+      }
+      if (!['a', 'accept', 'y', 'yes'].includes(decision)) {
+        skipped.push({ file: filePath, findings: fileFindings, reason: 'user-skipped' });
+        finalPlan = null;
+        break;
+      }
+
+      // Apply — snapshot file state once (first attempt) so a failed ladder
+      // can restore the repo to its pre-fix state.
+      let applyErr = null;
+      if (attempt === 1) {
+        snapshots = plan.files.map(fc => {
+          const abs = path.resolve(root, fc.path);
+          return { abs, existed: fs.existsSync(abs), content: fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null };
+        });
+      }
+      try {
+        for (const fileChange of plan.files) {
+          applyEdit(root, fileChange);
+        }
+      } catch (err) {
+        applyErr = err.message;
+      }
+
+      if (applyErr) {
+        console.log(chalk.red(`      Apply failed: ${applyErr}`));
+        skipped.push({ file: filePath, findings: fileFindings, reason: `apply-failed: ${applyErr}` });
+        finalPlan = null;
+        break;
+      }
+
+      // Verify — tiered ladder (build → tests → re-scan)
+      const verifySpinner = ora({ text: 'Verifying (build → tests → re-scan)...', color: 'cyan', indent: 6 }).start();
+      const verified = await verifyFile(root, filePath, fileFindings, options);
+      finalPlan = plan;
+      finalVerified = verified;
+
+      if (verified.allResolved) {
+        const ranTiers = (verified.tiers || []).map(t => t.tier);
+        verifySpinner.succeed(chalk.green(`Fix verified — ${fileFindings.length} finding(s) resolved (${[...ranTiers, 're-scan'].join(' → ')})`));
+        ladderFailed = false;
+        break;
+      }
+
+      if (verified.someResolved) {
+        verifySpinner.warn(chalk.yellow(`Partial: ${verified.resolvedCount}/${fileFindings.length} resolved`));
+        ladderFailed = false;
+      } else {
+        verifySpinner.warn(chalk.yellow(`Verification failed at tier "${verified.failedTier}"`));
+        ladderFailed = true;
+      }
+
+      // Evidence-fed retry
+      if (attempt < maxAttempts && verified.evidence) {
+        retryEvidence = verified.evidence;
+        continue;
+      }
+      break;
+    }
+
+    // Revert failed fixes (nothing resolved) so the repo stays consistent —
+    // even when the retry plan itself failed to generate.
+    if (ladderFailed && snapshots.length > 0) {
+      for (const s of snapshots) {
+        try {
+          if (s.existed) fs.writeFileSync(s.abs, s.content, 'utf8');
+          else if (fs.existsSync(s.abs)) fs.unlinkSync(s.abs);
+        } catch { /* best-effort restore */ }
+      }
+      console.log(chalk.yellow('      Reverted failed fix — file(s) restored to pre-fix state.'));
+      logFailure(root, {
+        timestamp: new Date().toISOString(),
+        file: filePath,
+        findings: fileFindings.map(f => ({ title: f.title, line: f.line, rule: f.rule })),
+        reason: 'verification-failed',
+        detail: finalVerified?.evidence || 'verification failed',
+        plan: finalPlan,
+      });
+      skipped.push({ file: filePath, findings: fileFindings, reason: `verification-failed: ${finalVerified?.failedTier || 'unknown'}` });
+      continue;
+    }
+
+    if (!finalPlan || !finalVerified) continue;
+
+    // Per-fix commit (if branch isolation in use)
+    const written = finalPlan.files.map(fc => path.resolve(root, fc.path));
+    let commitHash = null;
+    if (branchCreated) {
+      try {
+        execFileSync('git', ['add', '--', ...written], { cwd: root, stdio: 'pipe' });
+        const titles = fileFindings.slice(0, 3).map(f => f.title).join(', ');
+        const more   = fileFindings.length > 3 ? ` (+${fileFindings.length - 3} more)` : '';
+        const msg    = `fix(security): ${filePath} — ${titles}${more}`;
+        execFileSync('git', ['commit', '-m', msg], { cwd: root, stdio: 'pipe' });
+        commitHash = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf-8' }).trim();
+      } catch {
+        // commit failed — most likely nothing staged because edits were no-ops
+      }
+    }
+
+    // Log
+    logFix(root, {
+      timestamp: new Date().toISOString(),
+      file:      filePath,
+      findings:  fileFindings.map(f => ({ title: f.title, line: f.line, severity: f.severity, rule: f.rule })),
+      plan:      finalPlan,
+      verified:  finalVerified.allResolved,
+      verificationClass: finalVerified.verification,
+      verificationTiers: (finalVerified.tiers || []).map(t => ({ tier: t.tier, command: t.command, ok: t.ok })),
+      branch:    branchCreated,
+      commitHash,
+    });
+
+    applied.push({ file: filePath, plan: finalPlan, verified: finalVerified });
+  }
+
+  // ── Final report ─────────────────────────────────────────────────────────
+  console.log();
+  console.log();
+  output.header('Summary');
+  console.log();
+  console.log(`  ${chalk.green('Applied:')} ${applied.length} file(s)`);
+  console.log(`  ${chalk.gray('Skipped:')} ${skipped.length} file(s)`);
+
+  if (applied.length > 0) {
+    console.log();
+    console.log(chalk.gray('  Applied:'));
+    for (const a of applied) {
+      const mark = a.verified.allResolved ? chalk.green('✓') : chalk.yellow('?');
+      console.log(`    ${mark} ${a.file}`);
+    }
+    console.log();
+    console.log(chalk.gray(`  Audit log: ${path.join(FIX_LOG_DIR, FIX_LOG_FILE)}`));
+    if (branchCreated) {
+      console.log(chalk.gray(`  Branch:    ${chalk.cyan(branchCreated)}`));
+      console.log(chalk.gray(`  Switch back: git checkout ${initialBranch}`));
+    } else {
+      console.log(chalk.gray('  Review:    git diff'));
+      console.log(chalk.gray('  Undo last: praxis undo'));
+    }
+  }
+
+  // ── PR autopilot ─────────────────────────────────────────────────────────
+  if (options.pr && applied.length > 0 && branchCreated) {
+    console.log();
+    await openPullRequest(root, branchCreated, applied);
+  } else if (options.pr && !branchCreated) {
+    console.log();
+    console.log(chalk.yellow('  --pr requires --branch. Skipping PR creation.'));
+  }
+
+  if (skipped.length > 0 && applied.length === 0) {
+    console.log();
+    console.log(chalk.gray('  Tip: try a different provider with --provider, or run with --plan-only'));
+    console.log(chalk.gray('  to inspect what would change.'));
+  }
+
+  console.log();
+}
+
+// =============================================================================
+// PLAN GENERATION
+// =============================================================================
+
+// Generate a fix plan for a file. Returns either:
+//   { ok: true, plan }                       — plan generated successfully
+//   { ok: false, reason, raw, error }        — failed; reason is one of:
+//       'file-read-failed' | 'provider-error' | 'parse-error' |
+//       'llm-declined' | 'empty-response'
+// Caller decides what to do with the failure (log, persist, skip).
+async function generateBatchPlan(provider, root, filePath, fileFindings, retryEvidence = '') {
+  const abs = path.resolve(root, filePath);
+  let content;
+  try {
+    content = fs.readFileSync(abs, 'utf8');
+  } catch (err) {
+    return { ok: false, reason: 'file-read-failed', error: err.message };
+  }
+
+  const fileForPrompt = windowFileContent(content, fileFindings);
+
+  const findingsBlock = fileFindings.map((f, i) => `
+${i + 1}. [${f.severity.toUpperCase()}] ${f.title}${f.line ? ` (line ${f.line})` : ''}
+   Rule: ${f.rule ?? 'N/A'}
+   Description: ${f.description ?? 'N/A'}${f.fix ? `\n   Suggested fix: ${f.fix}` : ''}
+`).join('');
+
+  const systemPrompt = 'You are a security engineer. Produce precise code edits as structured JSON only. Never include prose, markdown, or code fences. Output a single JSON object.';
+
+  const userPrompt = `Fix all of these security findings in a single file by producing one coordinated plan.
+
+FILE: ${filePath}
+
+FINDINGS (${fileFindings.length}):
+${findingsBlock}
+
+CURRENT FILE CONTENT:
+\`\`\`
+${fileForPrompt}
+\`\`\`
+
+OUTPUT this exact JSON shape:
+{
+  "summary": "one short sentence describing what you'll do across all findings",
+  "files": [
+    {
+      "path": "${filePath}",
+      "edits": [
+        { "find": "EXACT verbatim substring", "replace": "new string", "reason": "addresses finding N" }
+      ]
+    }
+  ],
+  "risk": "low"
+}
+
+You MAY also include companion file changes (only these are allowed):
+  - .env.example  — add placeholders for any secrets you moved to env vars
+  - .gitignore    — add patterns for files that should not be committed
+
+For companion files, use this shape (no "find" needed):
+  { "path": ".env.example", "create": true, "content": "FULL FILE CONTENT" }
+or to append:
+  { "path": ".gitignore", "append": "PATTERN_TO_ADD\\n" }
+
+RULES:
+- Each "find" string must appear EXACTLY ONCE in the file. Include enough context (3+ lines) for uniqueness.
+- "replace" must be the corrected code. Preserve indentation and surrounding style.
+- Address each finding listed above with at least one edit (or explain in summary why a finding can't be mechanically fixed).
+- GREP FOR SIBLING CALL SITES: search the file (and clearly-related helper files) for every other instance of the same dangerous pattern and fix all of them, not just the flagged line. A fix that leaves variant call sites behind fails verification.
+- REGRESSION TEST: if this project has a test suite, include a test in your edits that fails before your fix and passes after it.
+- Risk: "low" = mechanical, "medium" = behavior change, "high" = architectural. Use "high" sparingly.
+- If you cannot produce a precise mechanical plan, return {"summary":"requires manual review","files":[],"risk":"high"}
+- JSON only. No prose. No code fences.${retryEvidence ? `
+
+PREVIOUS ATTEMPT FEEDBACK — your earlier plan was applied but automated verification failed:
+
+${retryEvidence}
+
+Produce a corrected plan against the CURRENT file content below. Diagnose the root cause of the
+verification failure (build break, failing test, or finding still present) and fix it.` : ''}`;
+
+  let response;
+  try {
+    response = await provider.complete(systemPrompt, userPrompt, {
+      maxTokens: 3000,
+      jsonMode:  true,
+    });
+  } catch (err) {
+    return { ok: false, reason: 'provider-error', error: err.message };
+  }
+
+  if (!response || !response.trim()) {
+    return { ok: false, reason: 'empty-response', raw: response ?? '' };
+  }
+
+  const plan = parseJsonLoose(response);
+  if (!plan) {
+    return { ok: false, reason: 'parse-error', raw: response };
+  }
+  if (!Array.isArray(plan.files) || plan.files.length === 0) {
+    // The LLM returned valid JSON but explicitly declined to produce edits
+    // (typically with summary like "requires manual review"). This is a
+    // legitimate "I don't know" — not a bug.
+    return { ok: false, reason: 'llm-declined', raw: response, plan };
+  }
+
+  return { ok: true, plan };
+}
+
+function parseJsonLoose(response) {
+  if (!response) return null;
+  const cleaned = response.trim()
+    .replace(/^```(?:json)?\s*/i, '')
+    .replace(/```\s*$/i, '')
+    .trim();
+  try {
+    return JSON.parse(cleaned);
+  } catch {
+    const m = cleaned.match(/\{[\s\S]*\}/);
+    if (m) {
+      try { return JSON.parse(m[0]); } catch { return null; }
+    }
+    return null;
+  }
+}
+
+function windowFileContent(content, fileFindings) {
+  if (content.length <= 8000) return content;
+  if (!Array.isArray(fileFindings) || fileFindings.length === 0) {
+    return content.slice(0, 8000);
+  }
+  
+  const lines = content.split('\n');
+  const RADIUS = 40;
+  
+  const targetLines = [...new Set(fileFindings.map(f => f.line).filter(Boolean))].sort((a, b) => a - b);
+  if (targetLines.length === 0) return content.slice(0, 8000);
+  
+  const ranges = [];
+  for (const line of targetLines) {
+    const start = Math.max(0, line - 1 - RADIUS);
+    const end = Math.min(lines.length - 1, line - 1 + RADIUS);
+    if (ranges.length === 0) {
+      ranges.push({ start, end });
+    } else {
+      const last = ranges[ranges.length - 1];
+      if (start <= last.end + 5) {
+        last.end = Math.max(last.end, end);
+      } else {
+        ranges.push({ start, end });
+      }
+    }
+  }
+  
+  const result = [];
+  let lastEnd = 0;
+  for (const r of ranges) {
+    if (r.start > lastEnd) {
+      result.push(`// ... [lines ${lastEnd + 1}-${r.start} truncated] ...`);
+    }
+    result.push(lines.slice(r.start, r.end + 1).join('\n'));
+    lastEnd = r.end + 1;
+  }
+  if (lastEnd < lines.length) {
+    result.push(`// ... [lines ${lastEnd + 1}-${lines.length} truncated] ...`);
+  }
+  return result.join('\n');
+}
+
+// =============================================================================
+// PLAN VALIDATION
+// =============================================================================
+
+function validatePlan(root, plan) {
+  if (!Array.isArray(plan.files) || plan.files.length === 0) {
+    return { ok: false, reason: 'no files in plan' };
+  }
+
+  for (const f of plan.files) {
+    if (!f.path) return { ok: false, reason: 'file entry missing path' };
+
+    const rel       = f.path.replace(/\\/g, '/');
+    const isSafeNew = SAFE_NEW_FILES.some(p => p.test(rel));
+
+    // Block protected paths unless this is a known-safe companion file
+    if (!isSafeNew && NEVER_EDIT.some(p => p.test(rel))) {
+      return { ok: false, reason: `protected path: ${f.path}` };
+    }
+
+    const abs    = path.resolve(root, f.path);
+    const exists = fs.existsSync(abs);
+
+    // Companion file forms (create / append)
+    if (f.create || f.append !== undefined) {
+      if (!exists && !isSafeNew) {
+        return { ok: false, reason: `cannot create new file at ${f.path}` };
+      }
+      if (f.create && typeof f.content !== 'string') {
+        return { ok: false, reason: 'create entry missing content' };
+      }
+      if (f.append && typeof f.append !== 'string') {
+        return { ok: false, reason: 'append must be a string' };
+      }
+      continue;
+    }
+
+    // Standard edit form
+    if (!exists) return { ok: false, reason: `file not found: ${f.path}` };
+    if (!Array.isArray(f.edits) || f.edits.length === 0) {
+      return { ok: false, reason: `no edits for ${f.path}` };
+    }
+
+    const content = fs.readFileSync(abs, 'utf8');
+    for (const e of f.edits) {
+      if (typeof e.find !== 'string' || typeof e.replace !== 'string') {
+        return { ok: false, reason: 'edit missing find/replace' };
+      }
+      if (e.find === e.replace) {
+        return { ok: false, reason: 'edit is a no-op' };
+      }
+      const match = locateFindString(content, e.find);
+      if (match.kind === 'missing') {
+        return { ok: false, reason: `find string not present in ${f.path}` };
+      }
+      if (match.kind === 'ambiguous') {
+        return { ok: false, reason: `find string is ambiguous (${match.count} matches) in ${f.path}` };
+      }
+      // Annotate the edit with the resolved match for use during apply
+      e._resolvedFind = match.matched;
+    }
+  }
+  return { ok: true };
+}
+
+// Try exact match first, then whitespace-normalized match if exact misses.
+// Returns { kind: 'unique'|'ambiguous'|'missing', matched, count }
+function locateFindString(haystack, needle) {
+  const exact = countOccurrences(haystack, needle);
+  if (exact === 1) return { kind: 'unique', matched: needle, count: 1 };
+  if (exact > 1)   return { kind: 'ambiguous', matched: needle, count: exact };
+
+  // Whitespace-tolerant fallback: collapse whitespace runs and try again
+  const norm = (s) => s.replace(/[ \t]+/g, ' ').replace(/\s*\n\s*/g, '\n').trim();
+  const needleNorm = norm(needle);
+  if (!needleNorm) return { kind: 'missing', matched: null, count: 0 };
+
+  // Walk the haystack and check if any window normalizes to the same string
+  // To keep this cheap, only attempt when needle has at least one newline (likely a code block)
+  const lines = haystack.split('\n');
+  const needleLines = needleNorm.split('\n').length;
+  let foundIdx = -1;
+  let foundCount = 0;
+  for (let i = 0; i + needleLines <= lines.length; i++) {
+    const window = lines.slice(i, i + needleLines).join('\n');
+    if (norm(window) === needleNorm) {
+      foundIdx = i;
+      foundCount++;
+      if (foundCount > 1) break;
+    }
+  }
+  if (foundCount === 1) {
+    const matched = lines.slice(foundIdx, foundIdx + needleLines).join('\n');
+    return { kind: 'unique', matched, count: 1 };
+  }
+  if (foundCount > 1) return { kind: 'ambiguous', matched: null, count: foundCount };
+  return { kind: 'missing', matched: null, count: 0 };
+}
+
+function countOccurrences(haystack, needle) {
+  if (!needle) return 0;
+  let count = 0, idx = 0;
+  while ((idx = haystack.indexOf(needle, idx)) !== -1) { count++; idx += needle.length; }
+  return count;
+}
+
+// =============================================================================
+// PRINTING
+// =============================================================================
+
+function printPlan(plan, _root) {
+  console.log();
+  console.log(chalk.bold('      Plan:'));
+  console.log(chalk.white(`        ${plan.summary || '(no summary)'}`));
+  if (plan.risk) {
+    const riskColor = plan.risk === 'low' ? chalk.green : plan.risk === 'medium' ? chalk.yellow : chalk.red;
+    console.log(`        Risk: ${riskColor(plan.risk)}`);
+  }
+  console.log();
+
+  for (const f of plan.files) {
+    if (f.create) {
+      console.log(chalk.bold(`      ${chalk.green('+ ')}${f.path} ${chalk.gray('(new file)')}`));
+      printNewFilePreview(f.content);
+      continue;
+    }
+    if (f.append !== undefined) {
+      console.log(chalk.bold(`      ${f.path} ${chalk.gray('(append)')}`));
+      for (const l of f.append.split('\n')) {
+        if (l) console.log(chalk.green(`        + ${l}`));
+      }
+      continue;
+    }
+    console.log(chalk.bold(`      ${f.path}`));
+    for (const e of f.edits) {
+      console.log(chalk.gray(`        — ${e.reason || 'edit'}`));
+      printDiff(e._resolvedFind || e.find, e.replace);
+    }
+  }
+  console.log();
+}
+
+function printNewFilePreview(content) {
+  const lines = content.split('\n');
+  const max = 6;
+  const shown = lines.slice(0, max);
+  for (const l of shown) console.log(chalk.green(`        + ${l}`));
+  if (lines.length > max) {
+    console.log(chalk.gray(`        … +${lines.length - max} more line(s)`));
+  }
+}
+
+function printDiff(oldStr, newStr) {
+  const oldLines = oldStr.split('\n');
+  const newLines = newStr.split('\n');
+  for (const l of oldLines) console.log(chalk.red(`        - ${l}`));
+  for (const l of newLines) console.log(chalk.green(`        + ${l}`));
+}
+
+function severityLabel(sev) {
+  switch (sev) {
+    case 'critical': return chalk.red.bold('[CRITICAL]');
+    case 'high':     return chalk.red('[HIGH]');
+    case 'medium':   return chalk.yellow('[MEDIUM]');
+    case 'low':      return chalk.blue('[LOW]');
+    default:         return chalk.gray(`[${(sev || 'INFO').toUpperCase()}]`);
+  }
+}
+
+// =============================================================================
+// APPLY
+// =============================================================================
+
+function applyEdit(root, fileChange) {
+  const abs = path.resolve(root, fileChange.path);
+
+  if (fileChange.create) {
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, fileChange.content, 'utf8');
+    return;
+  }
+
+  if (fileChange.append !== undefined) {
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    const existing = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : '';
+    // Avoid duplicate appends
+    if (existing.includes(fileChange.append.trim())) return;
+    const sep = existing && !existing.endsWith('\n') ? '\n' : '';
+    fs.writeFileSync(abs, existing + sep + fileChange.append, 'utf8');
+    return;
+  }
+
+  let content = fs.readFileSync(abs, 'utf8');
+  for (const e of fileChange.edits) {
+    const find = e._resolvedFind || e.find;
+    if (!content.includes(find)) {
+      throw new Error(`find string drifted in ${fileChange.path} (file changed mid-plan)`);
+    }
+    content = content.replace(find, e.replace);
+  }
+  fs.writeFileSync(abs, content, 'utf8');
+}
+
+// =============================================================================
+// VERIFY — tiered ladder (P-IMP-032)
+// =============================================================================
+// Executable oracles only; no tier is decided by model judgment:
+//   Tier 1  build/lint   — the project's own build (or lint) must still pass
+//   Tier 2  test suite   — the project's test command must still pass
+//   Tier 3  re-scan      — original findings must be gone from the fixed file
+// Failing tier evidence is returned so the caller can feed it into a retry.
+
+function isDockerAvailable() {
+  try {
+    execFileSync('docker', ['info'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function detectBuildCommand(root) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    if (typeof pkg.scripts?.build === 'string') return { label: 'build', command: ['npm', 'run', 'build'] };
+    if (typeof pkg.scripts?.lint === 'string') return { label: 'lint', command: ['npm', 'run', 'lint'] };
+  } catch { /* no package.json */ }
+  if (fs.existsSync(path.join(root, 'Cargo.toml'))) return { label: 'build', command: ['cargo', 'build'] };
+  if (fs.existsSync(path.join(root, 'go.mod'))) return { label: 'build', command: ['go', 'build', './...'] };
+  if (fs.existsSync(path.join(root, 'Makefile'))) return { label: 'build', command: ['make'] };
+  return null;
+}
+
+function detectTestCommand(root) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    if (typeof pkg.scripts?.test === 'string') return { label: 'test', command: ['npm', 'test'] };
+  } catch { /* no package.json */ }
+  if (fs.existsSync(path.join(root, 'Cargo.toml'))) return { label: 'test', command: ['cargo', 'test'] };
+  if (fs.existsSync(path.join(root, 'go.mod'))) return { label: 'test', command: ['go', 'test', './...'] };
+  if (fs.existsSync(path.join(root, 'pyproject.toml')) || fs.existsSync(path.join(root, 'pytest.ini'))) return { label: 'test', command: ['pytest'] };
+  return null;
+}
+
+function runProjectCommand(root, command, timeoutMs = 300000) {
+  const [cmd0, ...args] = command;
+  try {
+    let stdout;
+    if (process.platform === 'win32' && /^npm$/.test(cmd0)) {
+      // npm is a .cmd shim on Windows — spawnSync of .cmd files returns EINVAL
+      // without a shell. Commands are fixed internal strings (no user input).
+      const line = `npm.cmd ${args.map(a => `"${a}"`).join(' ')}`;
+      stdout = execFileSync(line, {
+        cwd: root,
+        shell: true,
+        encoding: 'utf-8',
+        timeout: timeoutMs,
+        maxBuffer: 10 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } else {
+      stdout = execFileSync(cmd0, args, {
+        cwd: root,
+        encoding: 'utf-8',
+        timeout: timeoutMs,
+        maxBuffer: 10 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    }
+    return { ok: true, exitCode: 0, output: String(stdout).slice(-800) };
+  } catch (err) {
+    const output = String((err.stdout || '') + '\n' + (err.stderr || '')).slice(-800);
+    const timedOut = err.killed || /ETIMEDOUT|timed out/i.test(err.message);
+    return { ok: false, exitCode: err.status ?? -1, output, timedOut };
+  }
+}
+
+async function rescanForFile(root, filePath, options) {
+  if (options.sandbox && isDockerAvailable()) {
+    const stdout = execFileSync('docker', [
+      'run', '--rm',
+      '-v', `${root}:/workspace`,
+      '-v', `${praxisDir}:/opt/praxis:ro`,
+      '-w', '/workspace',
+      'node:18-alpine',
+      'node', '/opt/praxis/cli/bin/praxis.js', 'scan', '.', '--json'
+    ], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+
+    const jsonStart = stdout.search(/^\s*\{/m);
+    if (jsonStart === -1) return { findings: [] };
+    try { return JSON.parse(stdout.slice(jsonStart)); } catch { return { findings: [] }; }
+  }
+  return auditCommand(root, { _agenticInner: true, deep: false, deps: false, noAi: true });
+}
+
+export async function verifyFile(root, filePath, originalFindings, options = {}) {
+  const tiers = [];
+
+  try {
+    // Tier 0 — AST syntax verification (P-IMP-010)
+    const ext = path.extname(filePath).toLowerCase();
+    if (['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs', '.py'].includes(ext)) {
+      try {
+        const fileContent = fs.readFileSync(path.resolve(root, filePath), 'utf8');
+        const parsed = ASTParser.parse(fileContent, filePath);
+        const hasValidAST = parsed && parsed.ast && Array.isArray(parsed.ast.body);
+        tiers.push({ tier: 'ast_syntax', ok: hasValidAST });
+        if (!hasValidAST) {
+          return {
+            allResolved: false, someResolved: false, resolvedCount: 0,
+            verification: 'failed', failedTier: 'ast_syntax',
+            evidence: `AST syntax verification failed on fixed file: ${filePath}`,
+            tiers,
+          };
+        }
+      } catch (err) {
+        return {
+          allResolved: false, someResolved: false, resolvedCount: 0,
+          verification: 'failed', failedTier: 'ast_syntax',
+          evidence: `AST syntax verification failed: ${err.message}`,
+          tiers,
+        };
+      }
+    }
+
+    // Tier 1 — build/lint
+    const build = detectBuildCommand(root);
+    if (build) {
+      const r = runProjectCommand(root, build.command);
+      tiers.push({ tier: 'build', command: build.command.join(' '), ok: r.ok, output: r.output });
+      if (!r.ok) {
+        return {
+          allResolved: false, someResolved: false, resolvedCount: 0,
+          verification: 'failed', failedTier: 'build',
+          evidence: `Build failed (${build.label}): ${r.output}`.slice(0, 1200),
+          tiers,
+        };
+      }
+    }
+
+    // Tier 2 — test suite
+    const test = detectTestCommand(root);
+    if (test) {
+      const r = runProjectCommand(root, test.command, 600000);
+      tiers.push({ tier: 'test', command: test.command.join(' '), ok: r.ok, output: r.output });
+      if (!r.ok) {
+        return {
+          allResolved: false, someResolved: false, resolvedCount: 0,
+          verification: 'failed', failedTier: 'test',
+          evidence: `Tests failed (${test.label}): ${r.output}`.slice(0, 1200),
+          tiers,
+        };
+      }
+    }
+
+    // Tier 3 — re-scan: original findings must be gone from the fixed file
+    const result = await rescanForFile(root, filePath, options);
+    const remaining = (result.findings ?? []).filter(f => {
+      const fPath = path.resolve(root, f.file);
+      const targetPath = path.resolve(root, filePath);
+      return fPath === targetPath;
+    });
+
+    let resolvedCount = 0;
+    const survivors = [];
+    for (const orig of originalFindings) {
+      const stillThere = remaining.some(f =>
+        f.rule === orig.rule &&
+        Math.abs((f.line ?? 0) - (orig.line ?? 0)) <= 2,
+      );
+      if (!stillThere) resolvedCount++;
+      else survivors.push(orig.rule);
+    }
+
+    const allResolved = resolvedCount === originalFindings.length;
+    return {
+      allResolved,
+      someResolved: resolvedCount > 0,
+      resolvedCount,
+      verification: allResolved ? 'passed' : (resolvedCount > 0 ? 'partial' : 'failed'),
+      failedTier: allResolved ? null : 'rescan',
+      evidence: allResolved ? '' : `Re-scan still reports: ${survivors.join(', ')}`,
+      tiers,
+    };
+  } catch (err) {
+    return {
+      allResolved: false, someResolved: false, resolvedCount: 0,
+      verification: 'failed', failedTier: 'verify-error',
+      evidence: err.message || 'verification crashed',
+      tiers,
+    };
+  }
+}
+
+// =============================================================================
+// LOGGING
+// =============================================================================
+
+function logFix(root, entry) {
+  const dir  = path.join(root, FIX_LOG_DIR);
+  const file = path.join(dir, FIX_LOG_FILE);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(entry) + '\n', 'utf8');
+}
+
+// Append a structured record for every plan that didn't produce an apply.
+// Useful for debugging regressions (the LLM said X, we rejected because Y).
+function logFailure(root, entry) {
+  const dir  = path.join(root, FIX_LOG_DIR);
+  const file = path.join(dir, 'failures.jsonl');
+  fs.mkdirSync(dir, { recursive: true });
+  // Truncate raw response to keep the log readable
+  const truncated = { ...entry };
+  if (typeof truncated.raw === 'string' && truncated.raw.length > 4000) {
+    truncated.raw = truncated.raw.slice(0, 4000) + '... [truncated]';
+  }
+  fs.appendFileSync(file, JSON.stringify(truncated) + '\n', 'utf8');
+}
+
+// Turn a structured plan failure into a user-facing one-liner.
+function describePlanFailure(failure) {
+  switch (failure.reason) {
+    case 'file-read-failed':
+      return { message: `Could not read source file: ${failure.error}`, reason: 'file-read-failed' };
+    case 'provider-error':
+      return { message: `LLM provider error — ${failure.error}`, reason: 'provider-error' };
+    case 'empty-response':
+      return { message: 'LLM returned an empty response (try again, or switch provider).', reason: 'empty-response' };
+    case 'parse-error':
+      return { message: 'LLM returned unparseable JSON — saved to .praxis/failures.jsonl for inspection.', reason: 'parse-error' };
+    case 'llm-declined': {
+      const summary = failure.plan?.summary;
+      return { message: summary
+        ? `LLM declined to fix this file — ${summary}`
+        : 'LLM declined to fix this file (returned files=[] — needs manual review).',
+        reason: 'llm-declined',
+      };
+    }
+    default:
+      return { message: `Plan failed: ${failure.reason}`, reason: failure.reason };
+  }
+}
+
+// =============================================================================
+// PR AUTOPILOT
+// =============================================================================
+
+async function openPullRequest(root, branch, applied) {
+  const ghAvailable = (() => {
+    try { execFileSync('gh', ['--version'], { stdio: 'pipe' }); return true; }
+    catch { return false; }
+  })();
+  if (!ghAvailable) {
+    console.log(chalk.yellow('  gh CLI not found. Install from https://cli.github.com to enable --pr.'));
+    return;
+  }
+
+  // Push branch
+  console.log(chalk.gray('  Pushing branch...'));
+  try {
+    execFileSync('git', ['push', '-u', 'origin', branch], { cwd: root, stdio: 'pipe' });
+  } catch (err) {
+    console.log(chalk.red(`  Push failed: ${err.message}`));
+    return;
+  }
+
+  // Build PR body
+  const totalFindings = applied.reduce((n, a) => n + (a.plan.files?.[0]?.edits?.length ?? 0), 0);
+  const body = [
+    '## Praxis — Security Fixes',
+    '',
+    `Applied ${applied.length} file(s) of fixes (${totalFindings} edit(s)) generated and verified by the Praxis agent.`,
+    '',
+    '### Files changed',
+    ...applied.map(a => {
+      const mark = a.verified.allResolved ? '✓' : '⚠';
+      return `- ${mark} \`${a.file}\` — ${a.plan.summary || 'security fix'}`;
+    }),
+    '',
+    '### Notes',
+    '- Each fix was generated by an LLM and verified by re-scanning the file.',
+    '- Files marked ⚠ have residual findings; review carefully before merging.',
+    '- Full audit log: `.praxis/fixes.jsonl`',
+    '',
+    'Generated by `praxis agent`.',
+  ].join('\n');
+
+  const title = `Security fixes: ${applied.length} file(s)`;
+
+  console.log(chalk.gray('  Opening PR...'));
+  let prUrl = null;
+  try {
+    prUrl = execFileSync('gh', ['pr', 'create', '--title', title, '--body', body], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+    console.log(chalk.green(`  PR opened: ${prUrl}`));
+  } catch (err) {
+    console.log(chalk.red(`  PR creation failed: ${err.message}`));
+    return;
+  }
+
+  // If we're running inside CI on a PR, leave a comment on the originating PR
+  // pointing at our fix PR. Detect from common GitHub Actions env vars.
+  const originPr = detectOriginPrNumber();
+  if (originPr) {
+    const note = [
+      `### 🛡️ Praxis Agent — fix PR opened`,
+      ``,
+      `The Praxis agent found fixable security issues triggered by this PR and opened **${prUrl}** with proposed fixes.`,
+      ``,
+      `**Files changed:** ${applied.length}`,
+      `**Total edits:** ${totalFindings}`,
+      ``,
+      `Review the fix PR and merge if it looks good.`,
+    ].join('\n');
+    try {
+      execFileSync('gh', ['pr', 'comment', String(originPr), '--body', note], { cwd: root, stdio: 'pipe' });
+      console.log(chalk.green(`  Commented on origin PR #${originPr}`));
+    } catch (err) {
+      console.log(chalk.yellow(`  Could not comment on origin PR #${originPr}: ${err.message}`));
+    }
+  }
+}
+
+// Detect the PR number that triggered this CI run. Supports GitHub Actions'
+// pull_request and pull_request_target events. Returns null when not in CI
+// or when the event isn't a PR event.
+function detectOriginPrNumber() {
+  // Explicit override (handy for testing or non-GHA CI providers)
+  if (process.env.PRAXIS_ORIGIN_PR) return process.env.PRAXIS_ORIGIN_PR;
+
+  // GitHub Actions: GITHUB_REF looks like "refs/pull/<n>/merge" or "refs/pull/<n>/head"
+  const ref = process.env.GITHUB_REF || '';
+  const m = ref.match(/^refs\/pull\/(\d+)\//);
+  if (m) return m[1];
+
+  // GitHub Actions PR event payload also exposes the number via GITHUB_EVENT_PATH
+  const eventPath = process.env.GITHUB_EVENT_PATH;
+  if (eventPath && fs.existsSync(eventPath)) {
+    try {
+      const payload = JSON.parse(fs.readFileSync(eventPath, 'utf8'));
+      if (payload?.pull_request?.number) return String(payload.pull_request.number);
+      if (payload?.number) return String(payload.number);
+    } catch { /* malformed event payload */ }
+  }
+
+  return null;
+}
+
+// =============================================================================
+// GIT
+// =============================================================================
+
+function checkGitState(root) {
+  try {
+    execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: root, stdio: 'pipe' });
+  } catch {
+    return 'not-a-repo';
+  }
+  try {
+    const out = execFileSync('git', ['status', '--porcelain'], { cwd: root, stdio: 'pipe' }).toString();
+    const meaningful = out.split('\n').filter(line => {
+      const path = line.slice(3).trim();
+      if (!path) return false;
+      if (path.startsWith('.praxis/')) return false;
+      if (path === 'praxis-report.html') return false;
+      return true;
+    });
+    return meaningful.length === 0 ? 'clean' : 'dirty';
+  } catch {
+    return 'clean';
+  }
+}
+
+function getCurrentBranch(root) {
+  try {
+    return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: root, stdio: 'pipe' }).toString().trim();
+  } catch {
+    return null;
+  }
+}
+
+// =============================================================================
+// PROMPTS
+// =============================================================================
+
+function prompt(question) {
+  return new Promise(resolve => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, answer => { rl.close(); resolve(answer); });
+  });
+}
+
+async function confirm(question) {
+  const a = (await prompt(`${question} [y/N] `)).trim().toLowerCase();
+  return a === 'y' || a === 'yes';
+}
+
+// Plan decision prompt with [e]dit support: opens the plan in $EDITOR for the
+// user to tweak, then re-validates. Loops until accept/skip/quit.
+async function promptDecision(plan, root) {
+  while (true) {
+    const raw = (await prompt(chalk.cyan('      [a]ccept  [s]kip  [e]dit  [q]uit > '))).trim().toLowerCase();
+    if (['a', 'accept', 'y', 'yes'].includes(raw)) return 'a';
+    if (['s', 'skip', 'n', 'no'].includes(raw))    return 's';
+    if (['q', 'quit'].includes(raw))               return 'q';
+    if (['e', 'edit'].includes(raw)) {
+      const edited = await editPlanInEditor(plan, root);
+      if (!edited) {
+        console.log(chalk.yellow('      Edit cancelled — keeping original plan.'));
+      } else {
+        // Mutate plan in place so the caller's reference picks up the changes
+        plan.summary = edited.summary;
+        plan.files   = edited.files;
+        plan.risk    = edited.risk;
+        // Re-validate then re-show
+        const validation = validatePlan(root, plan);
+        if (!validation.ok) {
+          console.log(chalk.red(`      Edited plan invalid: ${validation.reason}`));
+          console.log(chalk.gray('      Returning to prompt — try editing again, or skip.'));
+          continue;
+        }
+        printPlan(plan, root);
+      }
+      // Loop back and re-prompt
+      continue;
+    }
+    console.log(chalk.gray('      Unknown choice. Type a, s, e, or q.'));
+  }
+}
+
+async function editPlanInEditor(plan, root) {
+  const editor = process.env.EDITOR || process.env.VISUAL || 'vi';
+  const tmpFile = path.join(root, '.praxis', `plan-edit-${Date.now()}.json`);
+  fs.mkdirSync(path.dirname(tmpFile), { recursive: true });
+  // Strip _resolvedFind annotations before showing — they're internal
+  const exportable = JSON.parse(JSON.stringify(plan, (k, v) => k === '_resolvedFind' ? undefined : v));
+  fs.writeFileSync(tmpFile, JSON.stringify(exportable, null, 2), 'utf8');
+
+  try {
+    execFileSync(editor, [tmpFile], { stdio: 'inherit' });
+    const updated = JSON.parse(fs.readFileSync(tmpFile, 'utf8'));
+    fs.unlinkSync(tmpFile);
+    return updated;
+  } catch (err) {
+    try { fs.unlinkSync(tmpFile); } catch { /* best effort */ }
+    console.log(chalk.red(`      Editor failed: ${err.message}`));
+    return null;
+  }
+}