pan-wizard 3.8.0 → 3.10.0

package/pan-wizard-core/bin/lib/phase.cjs

@@ -10,6 +10,9 @@ const { writeStateMd, readStateSafe } = require('./state.cjs');
 const { enumerateRoadmapPhases } = require('./roadmap.cjs');
 const { PLANNING_DIR, PHASES_DIR, ROADMAP_FILE, REQUIREMENTS_FILE, STATE_FILE, isPlanFile, isSummaryFile, getPlanId, PHASE_DIR_RE, ARCHIVE_DIR_RE } = require('./constants.cjs');
 const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, parsePhaseDir, fileAccessible } = require('./utils.cjs');
+// Phase removal lives in phase-remove.cjs; re-exported below so consumers of
+// phase.cjs are unaffected by the decomposition.
+const { removePhaseFromDisk, renumberDecimalPhases, renumberIntegerPhases, updateRoadmapAfterRemoval, cmdPhaseRemove } = require('./phase-remove.cjs');
 
 /**
  * List phase directories or files within phases, with optional type and archive filtering.
@@ -516,375 +519,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
   output(result, raw, decimalPhase);
 }
 
-// ─── cmdPhaseRemove helpers ─────────────────────────────────────────────────
-
-/**
- * Delete a phase directory from disk.
- * @param {string} phaseDir - Absolute path to the phase directory to remove
- */
-function removePhaseFromDisk(phaseDir) {
-  try {
-    fs.rmSync(phaseDir, { recursive: true, force: true });
-  } catch (e) {
-    return { removed: false, error: e.message };
-  }
-  return { removed: true };
-}
-
-/**
- * Renumber sibling decimal phases after one is removed.
- *
- * Algorithm: When a decimal phase like 06.2 is removed, all higher-numbered
- * siblings under the same base integer (06.3, 06.4, ...) must be decremented
- * by 1 to fill the gap. We process in descending order to avoid directory
- * name collisions during rename (e.g. rename 06.4 -> 06.3 before 06.3 -> 06.2).
- *
- * @param {string} phasesDir - Absolute path to the phases directory
- * @param {string} baseInt - The integer portion of the removed phase (e.g. "06")
- * @param {number} removedDecimal - The decimal portion that was removed (e.g. 2)
- * @returns {{ renamedDirs: Array, renamedFiles: Array }}
- */
-function renumberDecimalPhases(phasesDir, baseInt, removedDecimal) {
-  const renamedDirs = [];
-  const renamedFiles = [];
-
-  try {
-    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-    const dirs = entries.filter(entry => entry.isDirectory()).map(entry => entry.name).sort((left, right) => comparePhaseNum(left, right));
-
-    // Find sibling decimals with higher numbers than the removed one
-    const decPattern = new RegExp(`^${baseInt}\\.(\\d+)-(.+)$`);
-    const toRename = [];
-    for (const dir of dirs) {
-      const decMatch = dir.match(decPattern);
-      if (decMatch && parseInt(decMatch[1], 10) > removedDecimal) {
-        toRename.push({ dir, oldDecimal: parseInt(decMatch[1], 10), slug: decMatch[2] });
-      }
-    }
-
-    // Sort descending so higher-numbered dirs are renamed first,
-    // preventing collisions (e.g. 06.4 -> 06.3 before 06.3 -> 06.2)
-    toRename.sort((left, right) => right.oldDecimal - left.oldDecimal);
-
-    for (const item of toRename) {
-      const newDecimal = item.oldDecimal - 1;
-      const oldPhaseId = `${baseInt}.${item.oldDecimal}`;
-      const newPhaseId = `${baseInt}.${newDecimal}`;
-      const newDirName = `${baseInt}.${newDecimal}-${item.slug}`;
-
-      // Rename the directory itself (e.g. 06.3-foo -> 06.2-foo)
-      fs.renameSync(path.join(phasesDir, item.dir), path.join(phasesDir, newDirName));
-      renamedDirs.push({ from: item.dir, to: newDirName });
-
-      // Rename files inside that contain the old phase ID prefix
-      const dirFiles = fs.readdirSync(path.join(phasesDir, newDirName));
-      for (const file of dirFiles) {
-        // Files may have phase prefix like "06.2-01-plan.md"
-        if (file.includes(oldPhaseId)) {
-          const newFileName = file.replace(oldPhaseId, newPhaseId);
-          fs.renameSync(
-            path.join(phasesDir, newDirName, file),
-            path.join(phasesDir, newDirName, newFileName)
-          );
-          renamedFiles.push({ from: file, to: newFileName });
-        }
-      }
-    }
-  } catch (e) {
-    return { renamedDirs, renamedFiles, error: `Partial rename: ${e.message}` };
-  }
-
-  return { renamedDirs, renamedFiles };
-}
-
-/**
- * Renumber integer phases (and their decimal/letter children) after one is removed.
- *
- * Algorithm: When an integer phase like 05 is removed, all phases with a higher
- * integer base (06, 06.1, 06A, 07, ...) must be decremented by 1. We process
- * in descending order to avoid directory name collisions during the rename
- * cascade (e.g. rename 07 -> 06 before 06 -> 05). Each directory and its
- * contained files with the old phase prefix are renamed to reflect the new number.
- *
- * @param {string} phasesDir - Absolute path to the phases directory
- * @param {number} removedInt - The integer phase number that was removed
- * @returns {{ renamedDirs: Array, renamedFiles: Array }}
- */
-/**
- * Collect phase directories that need renumbering (integer > removedInt).
- * @param {string[]} dirs - Sorted directory names
- * @param {number} removedInt - Removed phase integer
- * @returns {Array} Items to rename, sorted descending to avoid collisions
- */
-function collectDirsToRenumber(dirs, removedInt) {
-  const toRename = [];
-  for (const dir of dirs) {
-    const dirMatch = dir.match(/^(\d+)([A-Z])?(?:\.(\d+))?-(.+)$/i);
-    if (!dirMatch) continue;
-    const dirInt = parseInt(dirMatch[1], 10);
-    if (dirInt > removedInt) {
-      toRename.push({
-        dir, oldInt: dirInt,
-        letter: dirMatch[2] ? dirMatch[2].toUpperCase() : '',
-        decimal: dirMatch[3] ? parseInt(dirMatch[3], 10) : null,
-        slug: dirMatch[4],
-      });
-    }
-  }
-  toRename.sort((left, right) => {
-    if (left.oldInt !== right.oldInt) return right.oldInt - left.oldInt;
-    return (right.decimal || 0) - (left.decimal || 0);
-  });
-  return toRename;
-}
-
-/**
- * Rename a single phase directory and its internal files.
- * @param {string} phasesDir - Phases directory path
- * @param {Object} item - Rename item from collectDirsToRenumber
- * @param {Array} renamedDirs - Accumulator for renamed dirs
- * @param {Array} renamedFiles - Accumulator for renamed files
- */
-function renamePhaseDir(phasesDir, item, renamedDirs, renamedFiles) {
-  const newPadded = String(item.oldInt - 1).padStart(2, '0');
-  const oldPadded = String(item.oldInt).padStart(2, '0');
-  const suffix = (item.letter || '') + (item.decimal !== null ? `.${item.decimal}` : '');
-  const oldPrefix = oldPadded + suffix;
-  const newPrefix = newPadded + suffix;
-  const newDirName = `${newPrefix}-${item.slug}`;
-
-  fs.renameSync(path.join(phasesDir, item.dir), path.join(phasesDir, newDirName));
-  renamedDirs.push({ from: item.dir, to: newDirName });
-
-  for (const file of fs.readdirSync(path.join(phasesDir, newDirName))) {
-    if (file.startsWith(oldPrefix)) {
-      const newFileName = newPrefix + file.slice(oldPrefix.length);
-      fs.renameSync(path.join(phasesDir, newDirName, file), path.join(phasesDir, newDirName, newFileName));
-      renamedFiles.push({ from: file, to: newFileName });
-    }
-  }
-}
-
-function renumberIntegerPhases(phasesDir, removedInt) {
-  const renamedDirs = [];
-  const renamedFiles = [];
-  try {
-    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
-    const toRename = collectDirsToRenumber(dirs, removedInt);
-    for (const item of toRename) renamePhaseDir(phasesDir, item, renamedDirs, renamedFiles);
-  } catch (e) {
-    return { renamedDirs, renamedFiles, error: `Partial rename: ${e.message}` };
-  }
-  return { renamedDirs, renamedFiles };
-}
-
-/**
- * Rewrite roadmap.md after a phase is removed: delete the target section,
- * remove checkbox/table references, and renumber subsequent phase references.
- *
- * @param {string} cwd - Working directory path
- * @param {string} phaseNum - The phase number that was removed (as originally specified)
- * @param {boolean} isDecimal - Whether the removed phase was a decimal phase
- * @param {string} normalized - The zero-padded normalized phase number
- */
-function updateRoadmapAfterRemoval(cwd, phaseNum, isDecimal, normalized) {
-  const roadmapPath = path.join(planningPath(cwd), ROADMAP_FILE);
-  let roadmapContent;
-  try {
-    roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
-  } catch { return; }
-
-  // Remove the target phase section from roadmap.md.
-  // Matches from the phase heading to the next phase heading (or end of file).
-  const targetEscaped = escapeRegex(phaseNum);
-  const sectionPattern = new RegExp(
-    `\\n?#{2,4}\\s*Phase\\s+${targetEscaped}\\s*:[\\s\\S]*?(?=\\n#{2,4}\\s+Phase\\s+\\d|$)`,
-    'i'
-  );
-  roadmapContent = roadmapContent.replace(sectionPattern, '');
-
-  // Remove checkbox list items referencing this phase
-  const checkboxPattern = new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${targetEscaped}[:\\s][^\\n]*`, 'gi');
-  roadmapContent = roadmapContent.replace(checkboxPattern, '');
-
-  // Remove progress table rows referencing this phase
-  const tableRowPattern = new RegExp(`\\n?\\|\\s*${targetEscaped}\\.?\\s[^|]*\\|[^\\n]*`, 'gi');
-  roadmapContent = roadmapContent.replace(tableRowPattern, '');
-
-  // For integer phase removal, renumber all references to subsequent phases.
-  // Walk from highest phase number down to removedInt+1, decrementing each by 1.
-  // This avoids double-renaming (e.g. 8->7 then 7->6 would break if done ascending).
-  if (!isDecimal) {
-    const removedInt = parseInt(normalized, 10);
-
-    // Reasonable upper bound for phase numbers
-    const maxPhase = 99;
-    for (let oldNum = maxPhase; oldNum > removedInt; oldNum--) {
-      const newNum = oldNum - 1;
-      const oldStr = String(oldNum);
-      const newStr = String(newNum);
-      const oldPad = oldStr.padStart(2, '0');
-      const newPad = newStr.padStart(2, '0');
-
-      // Phase headings: ## Phase 18: or ### Phase 18: -> ## Phase 17:
-      roadmapContent = roadmapContent.replace(
-        new RegExp(`(#{2,4}\\s*Phase\\s+)${oldStr}(\\s*:)`, 'gi'),
-        `$1${newStr}$2`
-      );
-
-      // Inline phase references: "Phase 18:" or "Phase 18 " -> "Phase 17:"
-      roadmapContent = roadmapContent.replace(
-        new RegExp(`(Phase\\s+)${oldStr}([:\\s])`, 'g'),
-        `$1${newStr}$2`
-      );
-
-      // Plan references in padded form: 18-01 -> 17-01
-      roadmapContent = roadmapContent.replace(
-        new RegExp(`${oldPad}-(\\d{2})`, 'g'),
-        `${newPad}-$1`
-      );
-
-      // Progress table row numbers: | 18. -> | 17.
-      roadmapContent = roadmapContent.replace(
-        new RegExp(`(\\|\\s*)${oldStr}\\.\\s`, 'g'),
-        `$1${newStr}. `
-      );
-
-      // Depends-on references: "Depends on:** Phase 18" -> "Phase 17"
-      roadmapContent = roadmapContent.replace(
-        new RegExp(`(Depends on:\\*\\*\\s*Phase\\s+)${oldStr}\\b`, 'gi'),
-        `$1${newStr}`
-      );
-    }
-  }
-
-  try { fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8'); } catch { /* best-effort */ }
-}
-
-/**
- * Remove a phase directory, renumber subsequent phases, and update ROADMAP/STATE.
- * @param {string} cwd - Working directory path
- * @param {string} targetPhase - Phase number to remove
- * @param {Object} options - Options (force: skip executed-work check)
- * @param {boolean} raw - If true, output raw value instead of JSON
- * @returns {void}
- */
-function cmdPhaseRemove(cwd, targetPhase, options, raw) {
-  if (!targetPhase) {
-    error('phase number required for phase remove');
-  }
-
-  const roadmapPath = path.join(planningPath(cwd), ROADMAP_FILE);
-  const phasesDir = phasesPath(cwd);
-  const force = options.force || false;
-
-  if (!fileAccessible(roadmapPath)) {
-    error('roadmap.md not found');
-  }
-
-  // Normalize the target
-  const normalized = normalizePhaseName(targetPhase);
-  const isDecimal = targetPhase.includes('.');
-
-  // Find and validate target directory
-  let targetDir = null;
-  try {
-    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-    const dirs = entries.filter(entry => entry.isDirectory()).map(entry => entry.name).sort((left, right) => comparePhaseNum(left, right));
-    targetDir = dirs.find(dir => dir.startsWith(normalized + '-') || dir === normalized);
-  } catch {
-    // Phases directory does not exist; targetDir remains null
-  }
-
-  // Check for executed work (summary.md files)
-  if (targetDir && !force) {
-    const targetPath = path.join(phasesDir, targetDir);
-    const files = fs.readdirSync(targetPath);
-    const summaries = files.filter(isSummaryFile);
-    if (summaries.length > 0) {
-      error(`Phase ${targetPhase} has ${summaries.length} executed plan(s). Use --force to remove anyway.`);
-    }
-  }
-
-  // Delete target directory
-  let removeWarning = null;
-  if (targetDir) {
-    const removeResult = removePhaseFromDisk(path.join(phasesDir, targetDir));
-    if (!removeResult.removed) {
-      removeWarning = removeResult.error;
-    }
-  }
-
-  // Renumber subsequent phases using the appropriate strategy
-  let renamedDirs = [];
-  let renamedFiles = [];
-
-  let renameError = null;
-  if (isDecimal) {
-    // Decimal removal: renumber sibling decimals (e.g., removing 06.2 -> 06.3 becomes 06.2)
-    const baseParts = normalized.split('.');
-    const baseInt = baseParts[0];
-    const removedDecimal = parseInt(baseParts[1], 10);
-    const result = renumberDecimalPhases(phasesDir, baseInt, removedDecimal);
-    renamedDirs = result.renamedDirs;
-    renamedFiles = result.renamedFiles;
-    renameError = result.error || null;
-  } else {
-    // Integer removal: renumber all subsequent integer phases
-    const removedInt = parseInt(normalized, 10);
-    const result = renumberIntegerPhases(phasesDir, removedInt);
-    renamedDirs = result.renamedDirs;
-    renamedFiles = result.renamedFiles;
-    renameError = result.error || null;
-  }
-
-  // Update roadmap.md: remove section and renumber references
-  updateRoadmapAfterRemoval(cwd, targetPhase, isDecimal, normalized);
-
-  // Update state.md phase count
-  const stateUpdated = updateStateAfterPhaseRemoval(cwd);
-
-  const result = {
-    removed: targetPhase,
-    directory_deleted: targetDir || null,
-    renamed_directories: renamedDirs,
-    renamed_files: renamedFiles,
-    roadmap_updated: true,
-    state_updated: stateUpdated,
-  };
-  if (renameError) result.rename_warning = renameError;
-  if (removeWarning) result.remove_warning = removeWarning;
-
-  output(result, raw);
-}
-
-/**
- * Decrement phase count in state.md after a phase is removed.
- * @param {string} cwd - Working directory path
- * @returns {boolean} true if state.md was updated
- */
-function updateStateAfterPhaseRemoval(cwd) {
-  const statePath = path.join(planningPath(cwd), STATE_FILE);
-  const content = readStateSafe(statePath);
-  if (content === null) return false;
-
-  let updated = content;
-  // Decrement "Total Phases" field
-  const totalPattern = /(\*\*Total Phases:\*\*\s*)(\d+)/;
-  const totalMatch = updated.match(totalPattern);
-  if (totalMatch) {
-    updated = updated.replace(totalPattern, `$1${parseInt(totalMatch[2], 10) - 1}`);
-  }
-  // Decrement "Phase: X of Y" pattern
-  const ofPattern = /(\bof\s+)(\d+)(\s*(?:\(|phases?))/i;
-  const ofMatch = updated.match(ofPattern);
-  if (ofMatch) {
-    updated = updated.replace(ofPattern, `$1${parseInt(ofMatch[2], 10) - 1}$3`);
-  }
-  writeStateMd(statePath, updated, cwd);
-  return true;
-}
+// ─── Phase removal — extracted to phase-remove.cjs (re-exported below) ──────
 
 // ─── cmdPhaseComplete helpers ───────────────────────────────────────────────
 

package/pan-wizard-core/bin/lib/runner.cjs

@@ -313,6 +313,11 @@ function runExperiment(slug, opts = {}) {
         output_tokens: envelope.usage?.output_tokens ?? null,
         cache_creation_input_tokens: envelope.usage?.cache_creation_input_tokens ?? null,
         cache_read_input_tokens: envelope.usage?.cache_read_input_tokens ?? null,
+        // Headless `claude -p` usage bills against the Claude Agent SDK
+        // credit pool — separate from interactive subscription limits since
+        // June 15, 2026. Tagged so /pan:learn and billing reconciliation can
+        // separate experiment spend from interactive-session spend.
+        billing_pool: (manifest.runtime === 'claude') ? 'agent_sdk' : null,
       };
       appendEvent(runState, 'metrics_captured', `cost=$${envelope.total_cost_usd ?? '?'}, turns=${envelope.num_turns ?? '?'}`);
     } else {

package/pan-wizard-core/bin/lib/state.cjs

@@ -6,6 +6,7 @@ const fs = require('fs');
 const path = require('path');
 const { loadConfig, getMilestoneInfo, escapeRegex, safeReadFile, output, error } = require('./core.cjs');
 const { extractFrontmatter, reconstructFrontmatter } = require('./frontmatter.cjs');
+const { withFileLock, writeFileAtomic } = require('./lock.cjs');
 const {
   PLANNING_DIR,
   STATE_FILE,
@@ -855,11 +856,19 @@ function syncStateFrontmatter(content, cwd) {
 /**
  * Write state.md with synchronized YAML frontmatter.
  * All state.md writes should use this instead of raw writeFileSync.
+ *
+ * Concurrency (ADR-0030): the write is serialized behind an advisory
+ * state.md.lock and lands atomically (temp + rename), so concurrent agents
+ * cannot tear the file or interleave read-modify-write cycles. Lock
+ * acquisition is best-effort — on timeout the write proceeds unlocked,
+ * preserving single-agent behavior exactly.
  */
 function writeStateMd(statePath, content, cwd) {
   const synced = syncStateFrontmatter(content, cwd);
   try {
-    fs.writeFileSync(statePath, synced, 'utf-8');
+    withFileLock(statePath, () => {
+      writeFileAtomic(statePath, synced);
+    });
   } catch (err) {
     throw new Error('Failed to write state.md: ' + err.message);
   }

package/pan-wizard-core/bin/lib/verify-deploy.cjs

@@ -0,0 +1,181 @@
+/**
+ * Verify / Deployment validation — manifest + settings integrity per runtime.
+ * Extracted from verify.cjs (IMPROVEMENT-TODO P2 module decomposition);
+ * verify.cjs re-exports everything here, so consumers are unaffected.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output } = require('./core.cjs');
+
+/**
+ * Detect which PAN runtimes are installed in cwd.
+ * @param {string} cwd
+ * @returns {Array<{runtime: string, configDir: string}>}
+ */
+function detectInstalledRuntimes(cwd) {
+  const RUNTIME_DIRS = [
+    { runtime: 'claude', configDir: '.claude' },
+    { runtime: 'opencode', configDir: '.opencode' },
+    { runtime: 'gemini', configDir: '.gemini' },
+    { runtime: 'codex', configDir: '.codex' },
+    { runtime: 'copilot', configDir: '.github' },
+  ];
+  const found = [];
+  for (const rt of RUNTIME_DIRS) {
+    const manifestPath = path.join(cwd, rt.configDir, 'pan-file-manifest.json');
+    try {
+      fs.accessSync(manifestPath);
+      found.push(rt);
+    } catch (_) { /* not installed */ }
+  }
+  return found;
+}
+
+/**
+ * Validate a single PAN runtime installation.
+ * Checks: manifest files exist, hashes match, settings integrity.
+ * @param {string} cwd
+ * @param {string} configDir - e.g. '.claude'
+ * @param {string} runtime - e.g. 'claude'
+ * @returns {{ status: string, version: string, total_files: number, missing: string[], modified: string[], orphaned: string[], settings_ok: boolean, settings_issues: string[] }}
+ */
+function validateRuntimeInstall(cwd, configDir, runtime) {
+  const crypto = require('crypto');
+  const baseDir = path.join(cwd, configDir);
+  const manifestPath = path.join(baseDir, 'pan-file-manifest.json');
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (e) {
+    return { status: 'broken', version: null, error: `Cannot read manifest: ${e.message}`, total_files: 0, missing: [], modified: [], orphaned: [], settings_ok: false, settings_issues: ['manifest unreadable'] };
+  }
+
+  const missing = [];
+  const modified = [];
+  const files = manifest.files || {};
+  const totalFiles = Object.keys(files).length;
+
+  for (const [relPath, expectedHash] of Object.entries(files)) {
+    const absPath = path.join(baseDir, relPath);
+    try {
+      const content = fs.readFileSync(absPath);
+      const actualHash = crypto.createHash('sha256').update(content).digest('hex');
+      if (actualHash !== expectedHash) {
+        modified.push(relPath);
+      }
+    } catch (_) {
+      missing.push(relPath);
+    }
+  }
+
+  // Check settings integrity (hook paths resolve to real files).
+  // Copilot's user-editable settings moved to .github/copilot/settings.json
+  // (2026-06; .github/config.json was never a Copilot read path) and the file
+  // is optional — hooks live in .github/hooks/pan.json, so absence is fine.
+  const settingsIssues = [];
+  const settingsPath = runtime === 'copilot'
+    ? path.join(baseDir, 'copilot', 'settings.json')
+    : path.join(baseDir, 'settings.json');
+  const settingsOptional = runtime === 'codex' || runtime === 'opencode' || runtime === 'copilot';
+  let settingsOk = true;
+  try {
+    const settingsContent = fs.readFileSync(settingsPath, 'utf8');
+    const settings = JSON.parse(settingsContent);
+    // Check hook paths in settings
+    // Collect all hook command strings from settings
+    const hookCommands = [];
+    const hooks = settings.hooks;
+    if (hooks && typeof hooks === 'object') {
+      for (const hookArr of Object.values(hooks)) {
+        if (!Array.isArray(hookArr)) continue;
+        for (const hook of hookArr) {
+          if (hook.command) hookCommands.push(hook.command);
+        }
+      }
+    }
+    // Copilot/Gemini statusLine
+    if (settings.statusLine && settings.statusLine.command) {
+      hookCommands.push(settings.statusLine.command);
+    }
+    // Claude statusline
+    if (settings.statusline && settings.statusline.command) {
+      hookCommands.push(settings.statusline.command);
+    }
+    for (const cmd of hookCommands) {
+      const parts = cmd.split(/\s+/);
+      const hookFile = parts.find(p => p.endsWith('.js'));
+      if (hookFile) {
+        // Hook paths are relative to cwd, not to config dir
+        const resolvedPath = path.isAbsolute(hookFile) ? hookFile : path.join(cwd, hookFile);
+        try { fs.accessSync(resolvedPath); } catch (_) {
+          settingsIssues.push(`Hook path not found: ${hookFile}`);
+          settingsOk = false;
+        }
+      }
+    }
+  } catch (_) {
+    // No settings file is OK for runtimes where settings are optional
+    if (!settingsOptional) {
+      settingsIssues.push(`${path.basename(settingsPath)} missing or unreadable`);
+      settingsOk = false;
+    }
+  }
+
+  const status = missing.length > 0 ? 'broken' : modified.length > 0 ? 'modified' : 'clean';
+
+  return {
+    status,
+    version: manifest.version || null,
+    total_files: totalFiles,
+    missing,
+    modified,
+    orphaned: [],
+    settings_ok: settingsOk,
+    settings_issues: settingsIssues,
+  };
+}
+
+/**
+ * CLI command: validate deployment
+ * Validates PAN installations in the current directory.
+ * @param {string} cwd
+ * @param {boolean} raw
+ */
+function cmdValidateDeployment(cwd, raw) {
+  const runtimes = detectInstalledRuntimes(cwd);
+  if (runtimes.length === 0) {
+    output({ error: 'No PAN installations found in this directory' }, raw);
+    return;
+  }
+
+  const results = {};
+  let overallStatus = 'clean';
+
+  for (const { runtime, configDir } of runtimes) {
+    const result = validateRuntimeInstall(cwd, configDir, runtime);
+    results[runtime] = result;
+    if (result.status === 'broken') overallStatus = 'broken';
+    else if (result.status === 'modified' && overallStatus !== 'broken') overallStatus = 'modified';
+  }
+
+  const summary = {
+    status: overallStatus,
+    runtimes_found: runtimes.length,
+    runtimes: results,
+  };
+
+  const rawLines = [`Deployment status: ${overallStatus} (${runtimes.length} runtimes)`];
+  for (const [rt, r] of Object.entries(results)) {
+    rawLines.push(`  ${rt}: ${r.status} (${r.total_files} files, ${r.missing.length} missing, ${r.modified.length} modified)`);
+  }
+
+  output(summary, raw, rawLines.join('\n'));
+}
+
+module.exports = {
+  detectInstalledRuntimes,
+  validateRuntimeInstall,
+  cmdValidateDeployment,
+};