opencode-swarm 7.83.0 → 7.84.0

package/dist/cli/index-a82d6d87.js

@@ -0,0 +1,1241 @@
+// @bun
+import {
+  ALL_AGENT_NAMES,
+  PluginConfigSchema,
+  stripKnownSwarmPrefix
+} from "./index-wg3r6acj.js";
+import {
+  log
+} from "./index-yx44zd0p.js";
+
+// src/services/config-doctor.ts
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+var KNOWN_TOP_LEVEL_KEYS = new Set(Object.keys(PluginConfigSchema.shape));
+var DEPRECATED_FIELDS = new Map([
+  [
+    "skill_improver.model",
+    {
+      message: "deprecated",
+      replacement: "agents.skill_improver.model",
+      isDefaultValue: (v) => v === null
+    }
+  ],
+  [
+    "skill_improver.fallback_models",
+    {
+      message: "deprecated",
+      replacement: "agents.skill_improver.fallback_models",
+      isDefaultValue: (v) => Array.isArray(v) && v.length === 0
+    }
+  ],
+  [
+    "spec_writer.model",
+    {
+      message: "deprecated",
+      replacement: "agents.spec_writer.model",
+      isDefaultValue: (v) => v === null
+    }
+  ],
+  [
+    "spec_writer.fallback_models",
+    {
+      message: "deprecated",
+      replacement: "agents.spec_writer.fallback_models",
+      isDefaultValue: (v) => Array.isArray(v) && v.length === 0
+    }
+  ]
+]);
+function levenshteinDistance(a, b) {
+  const al = a.length;
+  const bl = b.length;
+  const matrix = [];
+  for (let i = 0;i <= al; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0;j <= bl; j++) {
+    matrix[0][j] = j;
+  }
+  for (let i = 1;i <= al; i++) {
+    for (let j = 1;j <= bl; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+    }
+  }
+  return matrix[al][bl];
+}
+function emitObjectTypeMismatch(key, value, findings) {
+  if (value !== undefined && (typeof value !== "object" || Array.isArray(value) || value === null)) {
+    findings.push({
+      id: `invalid-${key}-type`,
+      title: `Invalid ${key} type`,
+      description: `"${key}" must be an object, got ${typeof value}`,
+      severity: "error",
+      path: key,
+      currentValue: value,
+      autoFixable: false
+    });
+  }
+}
+function getUserConfigDir() {
+  return process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+}
+function getConfigPaths(directory) {
+  const userConfigPath = path.join(getUserConfigDir(), "opencode", "opencode-swarm.json");
+  const projectConfigPath = path.join(directory, ".opencode", "opencode-swarm.json");
+  return { userConfigPath, projectConfigPath };
+}
+function computeHash(content) {
+  return crypto.createHash("sha256").update(content, "utf-8").digest("hex");
+}
+function isValidConfigPath(configPath, directory) {
+  const normalizedPath = configPath.replace(/\\/g, "/");
+  const pathParts = normalizedPath.split("/");
+  for (const part of pathParts) {
+    if (part === ".." || part === "") {
+      if (part === "..") {
+        return false;
+      }
+    }
+  }
+  const { userConfigPath, projectConfigPath } = getConfigPaths(directory);
+  try {
+    const resolvedConfig = path.resolve(configPath);
+    const resolvedUser = path.resolve(userConfigPath);
+    const resolvedProject = path.resolve(projectConfigPath);
+    if (resolvedConfig !== resolvedUser && resolvedConfig !== resolvedProject) {
+      return false;
+    }
+    try {
+      if (fs.existsSync(resolvedConfig)) {
+        const realConfig = fs.realpathSync(resolvedConfig);
+        if (realConfig !== resolvedConfig) {
+          return false;
+        }
+      }
+    } catch {}
+    return true;
+  } catch {
+    return false;
+  }
+}
+function atomicWriteFileSync(filePath, content) {
+  const tmpPath = `${filePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmpPath, content, "utf-8");
+  try {
+    fs.renameSync(tmpPath, filePath);
+  } catch {
+    try {
+      fs.unlinkSync(filePath);
+    } catch {}
+    fs.renameSync(tmpPath, filePath);
+  }
+}
+function createConfigBackup(directory) {
+  const { userConfigPath, projectConfigPath } = getConfigPaths(directory);
+  let configPath = projectConfigPath;
+  let content = null;
+  if (fs.existsSync(projectConfigPath)) {
+    try {
+      content = fs.readFileSync(projectConfigPath, "utf-8");
+    } catch (error) {
+      log("[ConfigDoctor] project config read failed", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  if (content === null && fs.existsSync(userConfigPath)) {
+    configPath = userConfigPath;
+    try {
+      content = fs.readFileSync(userConfigPath, "utf-8");
+    } catch (error) {
+      log("[ConfigDoctor] user config read failed", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  if (content === null) {
+    return null;
+  }
+  return {
+    createdAt: Date.now(),
+    configPath,
+    content,
+    contentHash: computeHash(content)
+  };
+}
+function writeBackupArtifact(directory, backup) {
+  const swarmDir = path.join(directory, ".swarm");
+  if (!fs.existsSync(swarmDir)) {
+    fs.mkdirSync(swarmDir, { recursive: true });
+  }
+  const backupFilename = `config-backup-${backup.createdAt}.json`;
+  const backupPath = path.join(swarmDir, backupFilename);
+  const artifact = {
+    createdAt: backup.createdAt,
+    configPath: backup.configPath,
+    contentHash: backup.contentHash,
+    content: backup.content,
+    preview: backup.content.substring(0, 500) + (backup.content.length > 500 ? "..." : "")
+  };
+  atomicWriteFileSync(backupPath, JSON.stringify(artifact, null, 2));
+  return backupPath;
+}
+function restoreFromBackup(backupPath, directory) {
+  if (!fs.existsSync(backupPath)) {
+    return null;
+  }
+  const swarmDir = path.resolve(path.join(directory, ".swarm"));
+  const resolvedBackup = path.resolve(backupPath);
+  if (!resolvedBackup.startsWith(swarmDir + path.sep) && resolvedBackup !== swarmDir) {
+    return null;
+  }
+  try {
+    const artifact = JSON.parse(fs.readFileSync(backupPath, "utf-8"));
+    if (!artifact.content || !artifact.configPath || !artifact.contentHash) {
+      return null;
+    }
+    if (!isValidConfigPath(artifact.configPath, directory)) {
+      return null;
+    }
+    const computedHash = computeHash(artifact.content);
+    const storedHash = artifact.contentHash;
+    const isLegacyHash = /^\d+$/.test(storedHash);
+    if (!isLegacyHash && computedHash !== storedHash) {
+      return null;
+    }
+    log("[ConfigDoctor] Warning: restoring from backup with legacy numeric hash (pre-SHA-256). Consider re-backing up.", {});
+    const targetPath = artifact.configPath;
+    const targetDir = path.dirname(targetPath);
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+    }
+    atomicWriteFileSync(targetPath, artifact.content);
+    return targetPath;
+  } catch {
+    return null;
+  }
+}
+function readConfigFromFile(directory) {
+  const { userConfigPath, projectConfigPath } = getConfigPaths(directory);
+  let configPath = projectConfigPath;
+  let configContent = null;
+  if (fs.existsSync(projectConfigPath)) {
+    configPath = projectConfigPath;
+    configContent = fs.readFileSync(projectConfigPath, "utf-8");
+  } else if (fs.existsSync(userConfigPath)) {
+    configPath = userConfigPath;
+    configContent = fs.readFileSync(userConfigPath, "utf-8");
+  }
+  if (configContent === null) {
+    return null;
+  }
+  try {
+    const config = JSON.parse(configContent);
+    return { config, configPath };
+  } catch (error) {
+    log(`[ConfigDoctor] Failed to parse config file: ${configPath}`, {
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return null;
+  }
+}
+function validateConfigKey(path2, value) {
+  const findings = [];
+  for (const [depPath, depInfo] of DEPRECATED_FIELDS) {
+    if (path2 === depPath && !depInfo.isDefaultValue(value)) {
+      findings.push({
+        id: "deprecated-field",
+        title: `Deprecated config field: ${depPath}`,
+        description: `Config field "${depPath}" is deprecated. Replacement: ${depInfo.replacement}.`,
+        severity: "info",
+        path: depPath,
+        currentValue: value,
+        autoFixable: false
+      });
+    }
+  }
+  switch (path2) {
+    case "agents": {
+      if (value !== undefined) {
+        findings.push({
+          id: "deprecated-agents-config",
+          title: "Deprecated agents configuration",
+          description: 'The "agents" field is deprecated. Use "swarms" instead for multi-swarm support.',
+          severity: "warn",
+          path: "agents",
+          currentValue: value,
+          autoFixable: false,
+          proposedFix: {
+            type: "remove",
+            path: "agents",
+            description: "Remove deprecated agents config - use swarms instead",
+            risk: "low"
+          }
+        });
+      }
+      break;
+    }
+    case "guardrails.enabled": {
+      if (value === false) {
+        findings.push({
+          id: "guardrails-disabled",
+          title: "Guardrails disabled",
+          description: "Guardrails have been explicitly disabled. This removes safety limits.",
+          severity: "error",
+          path: "guardrails.enabled",
+          currentValue: value,
+          autoFixable: false
+        });
+      }
+      break;
+    }
+    case "guardrails.profiles": {
+      const profiles = value;
+      if (profiles) {
+        const validAgents = new Set(ALL_AGENT_NAMES);
+        for (const [agentName, profile] of Object.entries(profiles)) {
+          if (!validAgents.has(agentName)) {
+            findings.push({
+              id: "unknown-agent-profile",
+              title: "Unknown agent profile",
+              description: `Profile for unknown agent "${agentName}" will be ignored.`,
+              severity: "info",
+              path: `guardrails.profiles.${agentName}`,
+              currentValue: profile,
+              autoFixable: true,
+              proposedFix: {
+                type: "remove",
+                path: `guardrails.profiles.${agentName}`,
+                description: `Remove unknown agent profile "${agentName}"`,
+                risk: "low"
+              }
+            });
+          }
+        }
+      }
+      break;
+    }
+    case "automation.mode": {
+      const validModes = ["manual", "hybrid", "auto"];
+      if (value !== undefined && !validModes.includes(value)) {
+        findings.push({
+          id: "invalid-automation-mode",
+          title: "Invalid automation mode",
+          description: `Invalid automation mode "${value}". Valid: ${validModes.join(", ")}`,
+          severity: "error",
+          path: "automation.mode",
+          currentValue: value,
+          autoFixable: true,
+          proposedFix: {
+            type: "update",
+            path: "automation.mode",
+            value: "manual",
+            description: 'Reset to safe default "manual"',
+            risk: "low"
+          }
+        });
+      }
+      break;
+    }
+    case "automation.capabilities": {
+      const caps = value;
+      if (caps) {
+        const capabilityNames = [
+          "plan_sync",
+          "phase_preflight",
+          "config_doctor_on_startup",
+          "evidence_auto_summaries",
+          "decision_drift_detection"
+        ];
+        for (const [name, capValue] of Object.entries(caps)) {
+          if (capabilityNames.includes(name) && typeof capValue !== "boolean") {
+            findings.push({
+              id: "invalid-capability-type",
+              title: "Invalid capability type",
+              description: `Capability "${name}" must be boolean, got ${typeof capValue}`,
+              severity: "error",
+              path: `automation.capabilities.${name}`,
+              currentValue: capValue,
+              autoFixable: true,
+              proposedFix: {
+                type: "update",
+                path: `automation.capabilities.${name}`,
+                value: false,
+                description: `Reset capability "${name}" to false`,
+                risk: "low"
+              }
+            });
+          }
+        }
+      }
+      break;
+    }
+    case "hooks": {
+      emitObjectTypeMismatch("hooks", value, findings);
+      if (value !== undefined && typeof value === "object" && !Array.isArray(value) && value !== null) {
+        const hooks = value;
+        const validHooks = [
+          "system_enhancer",
+          "compaction",
+          "agent_activity",
+          "delegation_tracker",
+          "agent_awareness_max_chars",
+          "delegation_gate",
+          "delegation_max_chars"
+        ];
+        for (const hookName of Object.keys(hooks)) {
+          if (!validHooks.includes(hookName)) {
+            findings.push({
+              id: "unknown-hook-field",
+              title: "Unknown hook configuration",
+              description: `Unknown hook "${hookName}" will be ignored.`,
+              severity: "info",
+              path: `hooks.${hookName}`,
+              currentValue: hooks[hookName],
+              autoFixable: true,
+              proposedFix: {
+                type: "remove",
+                path: `hooks.${hookName}`,
+                description: `Remove unknown hook "${hookName}"`,
+                risk: "low"
+              }
+            });
+          }
+        }
+      }
+      break;
+    }
+    case "max_iterations": {
+      const numValue = value;
+      if (typeof numValue === "number") {
+        if (numValue < 1 || numValue > 10) {
+          findings.push({
+            id: "out-of-bounds-iterations",
+            title: "max_iterations out of bounds",
+            description: `max_iterations must be 1-10, got ${numValue}`,
+            severity: "error",
+            path: "max_iterations",
+            currentValue: numValue,
+            autoFixable: true,
+            proposedFix: {
+              type: "update",
+              path: "max_iterations",
+              value: Math.max(1, Math.min(10, numValue)),
+              description: "Clamp to valid range 1-10",
+              risk: "low"
+            }
+          });
+        }
+      }
+      break;
+    }
+    case "qa_retry_limit": {
+      const numValue = value;
+      if (typeof numValue === "number") {
+        if (numValue < 1 || numValue > 10) {
+          findings.push({
+            id: "out-of-bounds-retry-limit",
+            title: "qa_retry_limit out of bounds",
+            description: `qa_retry_limit must be 1-10, got ${numValue}`,
+            severity: "error",
+            path: "qa_retry_limit",
+            currentValue: numValue,
+            autoFixable: true,
+            proposedFix: {
+              type: "update",
+              path: "qa_retry_limit",
+              value: Math.max(1, Math.min(10, numValue)),
+              description: "Clamp to valid range 1-10",
+              risk: "low"
+            }
+          });
+        }
+      }
+      break;
+    }
+    case "swarms": {
+      if (value !== undefined) {
+        if (typeof value !== "object" || Array.isArray(value) || value === null) {
+          findings.push({
+            id: "invalid-swarms-type",
+            title: "Invalid swarms type",
+            description: `"swarms" must be an object, got ${typeof value}`,
+            severity: "error",
+            path: "swarms",
+            currentValue: value,
+            autoFixable: false
+          });
+          break;
+        }
+        const swarms = value;
+        if (Object.keys(swarms).length === 0) {
+          findings.push({
+            id: "empty-swarms",
+            title: "Empty swarms configuration",
+            description: 'The "swarms" field is an empty object. No swarm configurations are defined.',
+            severity: "info",
+            path: "swarms",
+            autoFixable: false
+          });
+        }
+        for (const swarmId of Object.keys(swarms)) {
+          if (swarmId.includes("..") || swarmId.includes("/") || swarmId.includes("\\") || swarmId.includes("\x00")) {
+            findings.push({
+              id: "swarm-id-path-traversal",
+              title: "Path traversal in swarm ID",
+              description: `Swarm ID "${swarmId}" contains path traversal characters.`,
+              severity: "error",
+              path: `swarms.${swarmId}`,
+              autoFixable: false
+            });
+          }
+        }
+        const validAgents = new Set(ALL_AGENT_NAMES);
+        for (const [swarmId, swarmConfig] of Object.entries(swarms)) {
+          const swarm = swarmConfig;
+          if (swarm.agents && typeof swarm.agents === "object") {
+            for (const [agentName] of Object.entries(swarm.agents)) {
+              const baseName = stripKnownSwarmPrefix(agentName);
+              if (baseName !== agentName && agentName.startsWith(`${swarmId}_`) && validAgents.has(baseName)) {
+                findings.push({
+                  id: "prefixed-swarm-agent-override",
+                  title: "Prefixed agent override is ignored",
+                  description: `Agent "${agentName}" in swarm "${swarmId}" uses a generated agent name. ` + `Per-swarm overrides must use the canonical key "${baseName}", e.g. ` + `"swarms.${swarmId}.agents.${baseName}.model". Otherwise the override is ignored and the agent falls back to its default model.`,
+                  severity: "warn",
+                  path: `swarms.${swarmId}.agents.${agentName}`,
+                  currentValue: swarm.agents[agentName],
+                  autoFixable: false
+                });
+              } else if (!validAgents.has(baseName)) {
+                findings.push({
+                  id: "unknown-swarm-agent",
+                  title: "Unknown agent in swarm",
+                  description: `Agent "${agentName}" in swarm "${swarmId}" may not be recognized.`,
+                  severity: "info",
+                  path: `swarms.${swarmId}.agents.${agentName}`,
+                  currentValue: swarm.agents[agentName],
+                  autoFixable: false
+                });
+              }
+            }
+          }
+        }
+      }
+      break;
+    }
+    case "default_agent": {
+      if (value !== undefined && typeof value !== "string") {
+        findings.push({
+          id: "invalid-default_agent-type",
+          title: "Invalid default_agent type",
+          description: `"default_agent" must be a string, got ${typeof value}`,
+          severity: "error",
+          path: "default_agent",
+          currentValue: value,
+          autoFixable: false
+        });
+      }
+      break;
+    }
+    case "auto_select_architect": {
+      if (value !== undefined && typeof value !== "boolean" && typeof value !== "string") {
+        findings.push({
+          id: "invalid-auto_select_architect-type",
+          title: "Invalid auto_select_architect type",
+          description: `"auto_select_architect" must be a boolean or string, got ${typeof value}`,
+          severity: "error",
+          path: "auto_select_architect",
+          currentValue: value,
+          autoFixable: false
+        });
+      }
+      break;
+    }
+    case "pipeline": {
+      emitObjectTypeMismatch("pipeline", value, findings);
+      break;
+    }
+    case "phase_complete": {
+      emitObjectTypeMismatch("phase_complete", value, findings);
+      break;
+    }
+    case "execution_mode": {
+      const validModes = ["strict", "balanced", "fast"];
+      if (value !== undefined && !validModes.includes(value)) {
+        findings.push({
+          id: "invalid-execution_mode-type",
+          title: "Invalid execution_mode",
+          description: `"execution_mode" must be one of: ${validModes.join(", ")}, got "${value}"`,
+          severity: "error",
+          path: "execution_mode",
+          currentValue: value,
+          autoFixable: false
+        });
+      }
+      break;
+    }
+    case "inject_phase_reminders": {
+      if (value !== undefined && typeof value !== "boolean") {
+        findings.push({
+          id: "invalid-inject_phase_reminders-type",
+          title: "Invalid inject_phase_reminders type",
+          description: `"inject_phase_reminders" must be a boolean, got ${typeof value}`,
+          severity: "error",
+          path: "inject_phase_reminders",
+          currentValue: value,
+          autoFixable: false
+        });
+      }
+      break;
+    }
+    case "gates": {
+      emitObjectTypeMismatch("gates", value, findings);
+      break;
+    }
+    case "context_budget": {
+      emitObjectTypeMismatch("context_budget", value, findings);
+      break;
+    }
+    case "guardrails": {
+      emitObjectTypeMismatch("guardrails", value, findings);
+      break;
+    }
+    case "watchdog": {
+      emitObjectTypeMismatch("watchdog", value, findings);
+      break;
+    }
+    case "self_review": {
+      emitObjectTypeMismatch("self_review", value, findings);
+      break;
+    }
+    case "tool_filter": {
+      emitObjectTypeMismatch("tool_filter", value, findings);
+      break;
+    }
+    case "authority": {
+      emitObjectTypeMismatch("authority", value, findings);
+      break;
+    }
+    case "plan_cursor": {
+      emitObjectTypeMismatch("plan_cursor", value, findings);
+      break;
+    }
+    case "context_map": {
+      emitObjectTypeMismatch("context_map", value, findings);
+      break;
+    }
+    case "evidence": {
+      emitObjectTypeMismatch("evidence", value, findings);
+      break;
+    }
+    case "summaries": {
+      emitObjectTypeMismatch("summaries", value, findings);
+      break;
+    }
+    case "review_passes": {
+      emitObjectTypeMismatch("review_passes", value, findings);
+      break;
+    }
+    case "adversarial_detection": {
+      emitObjectTypeMismatch("adversarial_detection", value, findings);
+      break;
+    }
+    case "adversarial_testing": {
+      emitObjectTypeMismatch("adversarial_testing", value, findings);
+      break;
+    }
+    case "integration_analysis": {
+      emitObjectTypeMismatch("integration_analysis", value, findings);
+      break;
+    }
+    case "docs": {
+      emitObjectTypeMismatch("docs", value, findings);
+      break;
+    }
+    case "design_docs": {
+      emitObjectTypeMismatch("design_docs", value, findings);
+      break;
+    }
+    case "ui_review": {
+      emitObjectTypeMismatch("ui_review", value, findings);
+      break;
+    }
+    case "compaction_advisory": {
+      emitObjectTypeMismatch("compaction_advisory", value, findings);
+      break;
+    }
+    case "lint": {
+      emitObjectTypeMismatch("lint", value, findings);
+      break;
+    }
+    case "secretscan": {
+      emitObjectTypeMismatch("secretscan", value, findings);
+      break;
+    }
+    case "checkpoint": {
+      emitObjectTypeMismatch("checkpoint", value, findings);
+      break;
+    }
+    case "automation": {
+      emitObjectTypeMismatch("automation", value, findings);
+      break;
+    }
+    case "knowledge": {
+      emitObjectTypeMismatch("knowledge", value, findings);
+      break;
+    }
+    case "memory": {
+      emitObjectTypeMismatch("memory", value, findings);
+      break;
+    }
+    case "curator": {
+      emitObjectTypeMismatch("curator", value, findings);
+      break;
+    }
+    case "architectural_supervision": {
+      emitObjectTypeMismatch("architectural_supervision", value, findings);
+      break;
+    }
+    case "knowledge_application": {
+      emitObjectTypeMismatch("knowledge_application", value, findings);
+      break;
+    }
+    case "skillPropagation": {
+      emitObjectTypeMismatch("skillPropagation", value, findings);
+      break;
+    }
+    case "skill_improver": {
+      emitObjectTypeMismatch("skill_improver", value, findings);
+      break;
+    }
+    case "spec_writer": {
+      emitObjectTypeMismatch("spec_writer", value, findings);
+      break;
+    }
+    case "tool_output": {
+      emitObjectTypeMismatch("tool_output", value, findings);
+      break;
+    }
+    case "slop_detector": {
+      emitObjectTypeMismatch("slop_detector", value, findings);
+      break;
+    }
+    case "todo_gate": {
+      emitObjectTypeMismatch("todo_gate", value, findings);
+      break;
+    }
+    case "incremental_verify": {
+      emitObjectTypeMismatch("incremental_verify", value, findings);
+      break;
+    }
+    case "compaction_service": {
+      emitObjectTypeMismatch("compaction_service", value, findings);
+      break;
+    }
+    case "prm": {
+      emitObjectTypeMismatch("prm", value, findings);
+      break;
+    }
+    case "council": {
+      emitObjectTypeMismatch("council", value, findings);
+      break;
+    }
+    case "parallelization": {
+      emitObjectTypeMismatch("parallelization", value, findings);
+      break;
+    }
+    case "worktree": {
+      emitObjectTypeMismatch("worktree", value, findings);
+      break;
+    }
+    case "turbo": {
+      emitObjectTypeMismatch("turbo", value, findings);
+      break;
+    }
+    case "turbo_mode": {
+      if (value !== undefined && typeof value !== "boolean") {
+        findings.push({
+          id: "invalid-turbo_mode-type",
+          title: "Invalid turbo_mode type",
+          description: `"turbo_mode" must be a boolean, got ${typeof value}`,
+          severity: "error",
+          path: "turbo_mode",
+          currentValue: value,
+          autoFixable: false
+        });
+      }
+      break;
+    }
+    case "quiet": {
+      if (value !== undefined && typeof value !== "boolean") {
+        findings.push({
+          id: "invalid-quiet-type",
+          title: "Invalid quiet type",
+          description: `"quiet" must be a boolean, got ${typeof value}`,
+          severity: "error",
+          path: "quiet",
+          currentValue: value,
+          autoFixable: false
+        });
+      }
+      break;
+    }
+    case "version_check": {
+      if (value !== undefined && typeof value !== "boolean") {
+        findings.push({
+          id: "invalid-version_check-type",
+          title: "Invalid version_check type",
+          description: `"version_check" must be a boolean, got ${typeof value}`,
+          severity: "error",
+          path: "version_check",
+          currentValue: value,
+          autoFixable: false
+        });
+      }
+      break;
+    }
+    case "full_auto": {
+      emitObjectTypeMismatch("full_auto", value, findings);
+      break;
+    }
+    case "pr_monitor": {
+      emitObjectTypeMismatch("pr_monitor", value, findings);
+      break;
+    }
+    case "external_skills": {
+      emitObjectTypeMismatch("external_skills", value, findings);
+      break;
+    }
+    default: {
+      const topLevel = path2.split(".")[0];
+      if (KNOWN_TOP_LEVEL_KEYS.has(topLevel)) {
+        break;
+      }
+      const MAX_SUGGESTION_KEY_LENGTH = 100;
+      const lowerTopLevel = topLevel.toLowerCase();
+      let suggestion;
+      let matchCount = 0;
+      if (lowerTopLevel.length <= MAX_SUGGESTION_KEY_LENGTH) {
+        for (const knownKey of KNOWN_TOP_LEVEL_KEYS) {
+          if (levenshteinDistance(lowerTopLevel, knownKey.toLowerCase()) <= 2) {
+            matchCount++;
+            if (matchCount === 1) {
+              suggestion = knownKey;
+            }
+          }
+        }
+      }
+      if (matchCount === 1 && suggestion) {
+        findings.push({
+          id: "unknown-config-key",
+          title: `Unknown config key: ${topLevel}`,
+          description: `Unknown config key "${path2}" is not in the schema. Did you mean "${suggestion}"?`,
+          severity: "warn",
+          path: path2,
+          currentValue: value,
+          autoFixable: false
+        });
+      } else {
+        findings.push({
+          id: "unknown-config-key",
+          title: `Unknown config key: ${topLevel}`,
+          description: `Unknown config key "${path2}" is not in the schema.`,
+          severity: "warn",
+          path: path2,
+          currentValue: value,
+          autoFixable: false
+        });
+      }
+      break;
+    }
+  }
+  return findings;
+}
+function walkConfigAndValidate(obj, path2, findings, visited = new WeakSet) {
+  if (obj === null || obj === undefined) {
+    return;
+  }
+  if (path2 && typeof obj === "object" && !Array.isArray(obj)) {
+    const keyFindings = validateConfigKey(path2, obj);
+    findings.push(...keyFindings);
+  }
+  if (typeof obj !== "object") {
+    const keyFindings = validateConfigKey(path2, obj);
+    findings.push(...keyFindings);
+    return;
+  }
+  if (visited.has(obj)) {
+    findings.push({
+      id: "circular-reference",
+      title: `Circular reference detected at ${path2}`,
+      description: `Config value at "${path2}" contains a circular reference. Validation stopped at this path to prevent stack overflow.`,
+      severity: "error",
+      path: path2,
+      currentValue: "[circular]",
+      autoFixable: false
+    });
+    return;
+  }
+  visited.add(obj);
+  if (Array.isArray(obj)) {
+    const arrayFindings = validateConfigKey(path2, obj);
+    findings.push(...arrayFindings);
+    obj.forEach((item, index) => {
+      walkConfigAndValidate(item, `${path2}[${index}]`, findings, visited);
+    });
+    return;
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    const newPath = path2 ? `${path2}.${key}` : key;
+    walkConfigAndValidate(value, newPath, findings, visited);
+  }
+}
+function runConfigDoctor(config, directory) {
+  const findings = [];
+  walkConfigAndValidate(config, "", findings);
+  const summary = {
+    info: findings.filter((f) => f.severity === "info").length,
+    warn: findings.filter((f) => f.severity === "warn").length,
+    error: findings.filter((f) => f.severity === "error").length
+  };
+  const hasAutoFixableIssues = findings.some((f) => f.autoFixable && f.proposedFix?.risk === "low");
+  const { userConfigPath, projectConfigPath } = getConfigPaths(directory);
+  let configSource = "defaults";
+  if (fs.existsSync(projectConfigPath)) {
+    configSource = projectConfigPath;
+  } else if (fs.existsSync(userConfigPath)) {
+    configSource = userConfigPath;
+  }
+  return {
+    findings,
+    summary,
+    hasAutoFixableIssues,
+    timestamp: Date.now(),
+    configSource
+  };
+}
+var DANGEROUS_PATH_SEGMENTS = new Set([
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
+function isDangerousPathSegment(segment) {
+  return DANGEROUS_PATH_SEGMENTS.has(segment);
+}
+function isPathSafe(fixPath) {
+  const segments = fixPath.split(".");
+  for (const segment of segments) {
+    if (isDangerousPathSegment(segment)) {
+      return false;
+    }
+  }
+  return true;
+}
+function applySafeAutoFixes(directory, result) {
+  const appliedFixes = [];
+  let updatedConfigPath = null;
+  const { userConfigPath, projectConfigPath } = getConfigPaths(directory);
+  let configPath = projectConfigPath;
+  let configContent;
+  if (fs.existsSync(projectConfigPath)) {
+    configPath = projectConfigPath;
+    configContent = fs.readFileSync(projectConfigPath, "utf-8");
+  } else if (fs.existsSync(userConfigPath)) {
+    configPath = userConfigPath;
+    configContent = fs.readFileSync(userConfigPath, "utf-8");
+  } else {
+    return { appliedFixes, updatedConfigPath: null };
+  }
+  let config;
+  try {
+    config = JSON.parse(configContent);
+  } catch {
+    return { appliedFixes, updatedConfigPath: null };
+  }
+  const safeFixes = result.findings.filter((f) => f.autoFixable && f.proposedFix?.risk === "low");
+  for (const finding of safeFixes) {
+    const fix = finding.proposedFix;
+    if (!fix)
+      continue;
+    if (!isPathSafe(fix.path)) {
+      continue;
+    }
+    const pathParts = fix.path.split(".");
+    let current = config;
+    let navigated = true;
+    for (let i = 0;i < pathParts.length - 1; i++) {
+      const part = pathParts[i];
+      if (current === null || current === undefined) {
+        navigated = false;
+        break;
+      }
+      if (typeof current !== "object" || Array.isArray(current)) {
+        navigated = false;
+        break;
+      }
+      const obj = current;
+      if (obj[part] === undefined) {
+        obj[part] = {};
+      } else if (obj[part] === null) {
+        navigated = false;
+        break;
+      } else if (typeof obj[part] !== "object") {
+        navigated = false;
+        break;
+      }
+      current = obj[part];
+    }
+    if (!navigated) {
+      continue;
+    }
+    const lastPart = pathParts[pathParts.length - 1];
+    switch (fix.type) {
+      case "remove":
+        if (current !== null && current !== undefined && typeof current === "object") {
+          delete current[lastPart];
+          appliedFixes.push(fix);
+        }
+        break;
+      case "update":
+        if (current !== null && current !== undefined && typeof current === "object") {
+          current[lastPart] = fix.value;
+          appliedFixes.push(fix);
+        }
+        break;
+      case "add":
+        if (current !== null && current !== undefined && typeof current === "object") {
+          current[lastPart] = fix.value;
+          appliedFixes.push(fix);
+        }
+        break;
+    }
+  }
+  if (appliedFixes.length > 0) {
+    const configDir = path.dirname(configPath);
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+    atomicWriteFileSync(configPath, JSON.stringify(config, null, 2));
+    updatedConfigPath = configPath;
+  }
+  return { appliedFixes, updatedConfigPath };
+}
+function readDoctorArtifact(directory) {
+  try {
+    const artifactPath = path.join(directory, ".swarm", "config-doctor.json");
+    if (!fs.existsSync(artifactPath)) {
+      return null;
+    }
+    const content = fs.readFileSync(artifactPath, "utf-8");
+    const artifact = JSON.parse(content);
+    const summary = artifact.summary;
+    if (!summary || typeof summary !== "object") {
+      return null;
+    }
+    const infoVal = summary.info;
+    const warnVal = summary.warn;
+    const errorVal = summary.error;
+    if (typeof infoVal !== "number" || !Number.isFinite(infoVal) || typeof warnVal !== "number" || !Number.isFinite(warnVal) || typeof errorVal !== "number" || !Number.isFinite(errorVal)) {
+      return null;
+    }
+    const ts = artifact.timestamp;
+    if (typeof ts !== "number" || !Number.isFinite(ts)) {
+      return null;
+    }
+    const findingsCount = infoVal + warnVal + errorVal;
+    const findings = artifact.findings;
+    const autoFixableCount = Array.isArray(findings) ? findings.filter((f) => f.autoFixable === true).length : 0;
+    return {
+      timestamp: new Date(ts).toISOString(),
+      findingsCount,
+      autoFixableCount
+    };
+  } catch {
+    return null;
+  }
+}
+function writeDoctorArtifact(directory, result) {
+  const swarmDir = path.join(directory, ".swarm");
+  if (!fs.existsSync(swarmDir)) {
+    fs.mkdirSync(swarmDir, { recursive: true });
+  }
+  const artifactFilename = "config-doctor.json";
+  const artifactPath = path.join(swarmDir, artifactFilename);
+  const guiOutput = {
+    timestamp: result.timestamp,
+    summary: result.summary,
+    hasAutoFixableIssues: result.hasAutoFixableIssues,
+    configSource: result.configSource,
+    findings: result.findings.map((f) => ({
+      id: f.id,
+      title: f.title,
+      description: f.description,
+      severity: f.severity,
+      path: f.path,
+      autoFixable: f.autoFixable,
+      proposedFix: f.proposedFix ? {
+        type: f.proposedFix.type,
+        path: f.proposedFix.path,
+        description: f.proposedFix.description,
+        risk: f.proposedFix.risk
+      } : null
+    }))
+  };
+  atomicWriteFileSync(artifactPath, JSON.stringify(guiOutput, null, 2));
+  return artifactPath;
+}
+function shouldRunOnStartup(automationConfig) {
+  if (!automationConfig) {
+    return false;
+  }
+  if (automationConfig.mode === "manual") {
+    return false;
+  }
+  return automationConfig.capabilities?.config_doctor_on_startup === true;
+}
+async function runConfigDoctorWithFixes(directory, config, autoFix = false) {
+  const result = runConfigDoctor(config, directory);
+  const artifactPath = writeDoctorArtifact(directory, result);
+  if (!autoFix) {
+    return {
+      result,
+      backupPath: null,
+      appliedFixes: [],
+      updatedConfigPath: null,
+      artifactPath
+    };
+  }
+  const backup = createConfigBackup(directory);
+  let backupPath = null;
+  if (backup) {
+    backupPath = writeBackupArtifact(directory, backup);
+  }
+  const { appliedFixes, updatedConfigPath } = applySafeAutoFixes(directory, result);
+  if (appliedFixes.length > 0) {
+    const freshConfig = readConfigFromFile(directory);
+    if (freshConfig) {
+      const newResult = runConfigDoctor(freshConfig.config, directory);
+      writeDoctorArtifact(directory, newResult);
+    }
+  }
+  return {
+    result,
+    backupPath,
+    appliedFixes,
+    updatedConfigPath,
+    artifactPath
+  };
+}
+function detectStraySwarmDirs(projectRoot) {
+  const findings = [];
+  const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    ".cache",
+    ".next",
+    "coverage",
+    ".turbo",
+    ".vercel",
+    ".terraform",
+    "__pycache__",
+    ".tox"
+  ]);
+  const MAX_DEPTH = 10;
+  const MAX_CONTENTS_ENTRIES = 20;
+  function walk(dir, depth) {
+    if (depth > MAX_DEPTH)
+      return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory())
+        continue;
+      const name = entry.name;
+      const fullPath = path.join(dir, name);
+      if (SKIP_DIRS.has(name))
+        continue;
+      const gitPath = path.join(fullPath, ".git");
+      try {
+        const gitStat = fs.statSync(gitPath);
+        if (gitStat.isFile() || gitStat.isDirectory())
+          continue;
+      } catch {}
+      if (name === ".swarm") {
+        const parentDir = path.dirname(fullPath);
+        if (parentDir === projectRoot)
+          continue;
+        let contents = [];
+        try {
+          contents = fs.readdirSync(fullPath);
+        } catch {
+          contents = ["<unreadable>"];
+        }
+        findings.push({
+          path: path.relative(projectRoot, fullPath).replace(/\\/g, "/"),
+          absolutePath: fullPath,
+          contents: contents.slice(0, MAX_CONTENTS_ENTRIES),
+          totalEntries: contents.length
+        });
+        continue;
+      }
+      walk(fullPath, depth + 1);
+    }
+  }
+  walk(projectRoot, 0);
+  return findings;
+}
+function removeStraySwarmDir(projectRoot, strayPath) {
+  let canonicalRoot;
+  let canonicalStray;
+  try {
+    canonicalRoot = fs.realpathSync(projectRoot);
+    canonicalStray = fs.realpathSync(path.isAbsolute(strayPath) ? strayPath : path.resolve(projectRoot, strayPath));
+  } catch (err) {
+    return {
+      success: false,
+      message: `Failed to resolve paths: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const rootSwarm = path.join(canonicalRoot, ".swarm");
+  if (canonicalStray === rootSwarm || canonicalStray === canonicalRoot) {
+    return {
+      success: false,
+      message: "Refusing to remove root .swarm/ directory"
+    };
+  }
+  if (!canonicalStray.startsWith(canonicalRoot + path.sep)) {
+    return {
+      success: false,
+      message: "Path is outside project root \u2014 refusing to remove"
+    };
+  }
+  const normalizedStray = canonicalStray.replace(/\\/g, "/");
+  if (!normalizedStray.endsWith("/.swarm")) {
+    return {
+      success: false,
+      message: "Path is not a .swarm directory \u2014 refusing to remove"
+    };
+  }
+  try {
+    fs.rmSync(canonicalStray, { recursive: true, force: true });
+    return {
+      success: true,
+      message: `Removed stray .swarm directory: ${canonicalStray}`
+    };
+  } catch (err) {
+    return {
+      success: false,
+      message: `Failed to remove: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
+
+export { getConfigPaths, createConfigBackup, writeBackupArtifact, restoreFromBackup, runConfigDoctor, applySafeAutoFixes, readDoctorArtifact, writeDoctorArtifact, shouldRunOnStartup, runConfigDoctorWithFixes, detectStraySwarmDirs, removeStraySwarmDir };