@yemi33/minions 0.1.2424 → 0.1.2426

package/engine/settings-validation.js

@@ -0,0 +1,909 @@
+'use strict';
+
+const apiValidation = require('./api-validation');
+const features = require('./features');
+const modelDiscovery = require('./model-discovery');
+const runtimes = require('./runtimes');
+const shared = require('./shared');
+
+const MAX_SETTINGS_ERRORS = 25;
+const SETTINGS_TOP_LEVEL_FIELDS = new Set(['engine', 'claude', 'agents', 'projects', 'features']);
+const CLEAR_SENTINELS = new Set(['', null]);
+const FONT_SIZES = ['small', 'medium', 'large', 'xlarge'];
+const COPILOT_STREAM_MODES = ['on', 'off'];
+const CODEX_SANDBOX_MODES = [...shared.CODEX_SANDBOX_MODES];
+const CC_EFFORT_LEVELS = ['low', 'medium', 'high'];
+const AGENT_FIELDS = new Set([
+  'role',
+  'expertise',
+  'skills',
+  'monthlyBudgetUsd',
+  'cli',
+  'model',
+  'maxBudgetUsd',
+  'bareMode',
+  'workspace_manifest',
+]);
+const WORKSPACE_MANIFEST_FIELDS = new Set([
+  'allowed_tools',
+  'allowed_repos',
+  'allowed_external_urls',
+  'memory_scope',
+]);
+const PROJECT_FIELDS = new Set([
+  'name',
+  'mainBranch',
+  'checkoutMode',
+  'worktreeMode',
+  'liveValidation',
+  'liveCheckoutAutoStash',
+  'createPrsAsDraft',
+  'additionalRepoScopes',
+  'workSources',
+]);
+const WORK_SOURCE_NAMES = new Set(['pullRequests', 'workItems']);
+const WORK_SOURCE_FIELDS = new Set(['enabled', 'cooldownMinutes']);
+const MAX_TURNS_TYPES = new Set(Object.values(shared.WORK_TYPE));
+
+// Bounds retain the public settings contract while defaults remain authoritative
+// in ENGINE_DEFAULTS. Every entry is checked against that registry at load time.
+const ENGINE_NUMERIC_RANGES = Object.freeze({
+  tickInterval: { min: 10000 },
+  maxConcurrent: { min: 1, max: 50 },
+  inboxConsolidateThreshold: { min: 1 },
+  agentTimeout: { min: 60000 },
+  maxTurns: { min: 5, max: 500 },
+  heartbeatTimeout: { min: 60000 },
+  worktreeCreateTimeout: { min: 60000 },
+  worktreeCreateRetries: { min: 0, max: 3 },
+  worktreeMinFreeSpaceBytes: { min: 0, max: 10 * 1024 * 1024 * 1024 * 1024 },
+  assertCleanStatusTimeoutMs: { min: 1000, max: 120000 },
+  restartHealthTimeoutMs: { min: 15000, max: 300000 },
+  orphanHolderScanTimeoutMs: { min: 1000, max: 30000 },
+  statusProbeKillTimeoutMs: { min: 2000, max: 60000 },
+  idleAlertMinutes: { min: 1 },
+  shutdownTimeout: { min: 30000 },
+  restartGracePeriod: { min: 60000 },
+  meetingRoundTimeout: { min: 60000 },
+  steeringDeferredMaxMs: { min: 60000, max: 14400000 },
+  steeringMaxKillRetries: { min: 1, max: 5 },
+  spawnPhaseGraceMs: { min: 10000, max: 1800000 },
+  spawnPhaseMaxCpuSeconds: { min: 0, max: 60 },
+  versionCheckInterval: { min: 60000 },
+  prPollStatusEvery: { min: 1 },
+  prPollCommentsEvery: { min: 1 },
+  agentBusyReassignMs: { min: 0 },
+  maxRetriesPerAgent: { min: 1, max: 20 },
+  ccTurnTimeoutMs: { min: 10000, max: 3600000 },
+  preDispatchEvalConcurrency: { min: 1, max: 20 },
+  memoryRetrievalTopK: { min: 1, max: 30 },
+  memoryRetrievalMaxBytes: { min: 1024, max: 65536 },
+  memoryRetrievalCandidateLimit: { min: 5, max: 200 },
+});
+
+for (const key of Object.keys(ENGINE_NUMERIC_RANGES)) {
+  if (typeof shared.ENGINE_DEFAULTS[key] !== 'number') {
+    throw new Error(`Settings range "${key}" has no numeric ENGINE_DEFAULTS entry`);
+  }
+}
+
+const ENGINE_BOOLEAN_FIELDS = new Set(
+  Object.entries(shared.ENGINE_DEFAULTS)
+    .filter(([, value]) => typeof value === 'boolean')
+    .map(([key]) => key),
+);
+const ENGINE_SPECIAL_FIELDS = new Set([
+  'ccWorkerIdleTimeoutMs',
+  'worktreeRoot',
+  'operatorLogin',
+  'defaultCli',
+  'defaultModel',
+  'ccCli',
+  'ccModel',
+  'claudeFallbackModel',
+  'copilotFallbackModel',
+  'copilotStreamMode',
+  'codexCcSandbox',
+  'fontSize',
+  'maxBudgetUsd',
+  'ccEffort',
+  'maxTurnsByType',
+  'evalMaxCost',
+  'ignoredCommentAuthors',
+]);
+const ENGINE_ALLOWED_FIELDS = new Set([
+  ...Object.keys(ENGINE_NUMERIC_RANGES),
+  ...ENGINE_BOOLEAN_FIELDS,
+  ...ENGINE_SPECIAL_FIELDS,
+]);
+
+class SettingsDiscoveryError extends Error {
+  constructor(runtimeName, cause) {
+    super(`Model discovery is unavailable for runtime "${runtimeName}". Retry when its catalog is available.`);
+    this.name = 'SettingsDiscoveryError';
+    this.code = 'model-discovery-unavailable';
+    this.statusCode = 503;
+    this.runtime = runtimeName;
+    this.cause = cause;
+  }
+}
+
+class SettingsErrorCollector {
+  constructor() {
+    this.details = [];
+  }
+
+  add(path, code, message, rejectedValue, extra = {}) {
+    if (this.details.length >= MAX_SETTINGS_ERRORS) return;
+    this.details.push({
+      path,
+      field: String(path).split('.').pop().replace(/\[\d+\]$/, ''),
+      code,
+      message,
+      expected: extra.expected,
+      rejectedValue,
+      ...(Array.isArray(extra.allowedValues) ? { allowedValues: extra.allowedValues } : {}),
+      ...(Number.isFinite(extra.min) ? { min: extra.min } : {}),
+      ...(Number.isFinite(extra.max) ? { max: extra.max } : {}),
+    });
+  }
+
+  capture(path, rejectedValue, fn) {
+    try {
+      return fn();
+    } catch (error) {
+      this.add(path, 'invalid-setting', error && error.message ? error.message : 'Invalid setting', rejectedValue);
+      return undefined;
+    }
+  }
+
+  throwIfAny() {
+    if (this.details.length === 0) return;
+    throw new apiValidation.ApiInputError('Settings validation failed', {
+      code: 'invalid-settings',
+      statusCode: 422,
+      details: this.details,
+    });
+  }
+}
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function isPlainObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function cloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function ensureCurrentConfig(currentConfig) {
+  if (!isPlainObject(currentConfig)) {
+    throw new Error('Current config.json must contain a JSON object');
+  }
+  return cloneJson(currentConfig);
+}
+
+function validateObject(value, path, errors) {
+  if (isPlainObject(value)) return true;
+  errors.add(path, 'invalid-object', `${path} must be a plain object`, value, { expected: 'plain object' });
+  return false;
+}
+
+function rejectUnknownFields(value, allowed, path, errors) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) {
+      errors.add(`${path}.${key}`, 'unknown-field', `${path}.${key} is not a supported setting`, value[key], {
+        allowedValues: [...allowed],
+      });
+    }
+  }
+}
+
+function parseFiniteNumber(value, path, errors, options = {}) {
+  let parsed;
+  if (typeof value === 'number') {
+    parsed = value;
+  } else if (typeof value === 'string' && value.trim() !== '') {
+    parsed = Number(value);
+  } else {
+    errors.add(path, 'invalid-number', `${path} must be a finite number`, value, { expected: 'finite number' });
+    return undefined;
+  }
+  if (!Number.isFinite(parsed)) {
+    errors.add(path, 'invalid-number', `${path} must be a finite number`, value, { expected: 'finite number' });
+    return undefined;
+  }
+  if (options.integer !== false && !Number.isInteger(parsed)) {
+    errors.add(path, 'invalid-integer', `${path} must be an integer`, value, { expected: 'integer' });
+    return undefined;
+  }
+  if ((Number.isFinite(options.min) && parsed < options.min)
+      || (Number.isFinite(options.max) && parsed > options.max)) {
+    errors.add(path, 'out-of-range', `${path} is outside the allowed range`, value, {
+      expected: 'number in range',
+      min: options.min,
+      max: options.max,
+    });
+    return undefined;
+  }
+  return parsed;
+}
+
+function parseString(value, path, errors, options = {}) {
+  if (typeof value !== 'string') {
+    errors.add(path, 'invalid-string', `${path} must be a string`, value, { expected: 'string' });
+    return undefined;
+  }
+  const parsed = options.trim === false ? value : value.trim();
+  if (options.allowEmpty === false && parsed.length === 0) {
+    errors.add(path, 'invalid-string', `${path} must not be empty`, value, { expected: 'non-empty string' });
+    return undefined;
+  }
+  return parsed;
+}
+
+function parseBoolean(value, path, errors) {
+  if (typeof value !== 'boolean') {
+    errors.add(path, 'invalid-boolean', `${path} must be a boolean`, value, { expected: 'boolean' });
+    return undefined;
+  }
+  return value;
+}
+
+function parseEnum(value, path, values, errors) {
+  if (!values.includes(value)) {
+    errors.add(path, 'invalid-enum', `${path} must be one of the allowed values`, value, {
+      expected: 'enum',
+      allowedValues: values,
+    });
+    return undefined;
+  }
+  return value;
+}
+
+function setOrDelete(target, key, value) {
+  if (value === undefined) delete target[key];
+  else target[key] = value;
+}
+
+function parseClearableString(value, path, errors) {
+  if (CLEAR_SENTINELS.has(value)) return undefined;
+  return parseString(value, path, errors, { allowEmpty: false });
+}
+
+function parseRuntimeName(value, path, errors) {
+  const parsed = parseClearableString(value, path, errors);
+  if (parsed === undefined) return undefined;
+  const names = runtimes.listRuntimes();
+  if (!names.includes(parsed)) {
+    errors.add(path, 'unknown-runtime', `${path} names an unregistered runtime`, value, {
+      expected: 'registered runtime',
+      allowedValues: names,
+    });
+    return undefined;
+  }
+  return parsed;
+}
+
+function applyEngineSettings(candidate, bodyEngine, errors) {
+  if (!validateObject(bodyEngine, 'engine', errors)) return;
+  rejectUnknownFields(bodyEngine, ENGINE_ALLOWED_FIELDS, 'engine', errors);
+  if (!isPlainObject(candidate.engine)) candidate.engine = {};
+  const engine = candidate.engine;
+
+  for (const [key, range] of Object.entries(ENGINE_NUMERIC_RANGES)) {
+    if (!hasOwn(bodyEngine, key)) continue;
+    const value = parseFiniteNumber(bodyEngine[key], `engine.${key}`, errors, range);
+    if (value !== undefined) engine[key] = value;
+  }
+
+  if (hasOwn(bodyEngine, 'ccWorkerIdleTimeoutMs')) {
+    const raw = bodyEngine.ccWorkerIdleTimeoutMs;
+    const value = parseFiniteNumber(raw, 'engine.ccWorkerIdleTimeoutMs', errors, {
+      min: raw === 0 || raw === '0' ? 0 : 60000,
+      max: raw === 0 || raw === '0' ? 0 : 28800000,
+    });
+    if (value !== undefined) engine.ccWorkerIdleTimeoutMs = value;
+  }
+
+  for (const key of ENGINE_BOOLEAN_FIELDS) {
+    if (!hasOwn(bodyEngine, key)) continue;
+    const value = parseBoolean(bodyEngine[key], `engine.${key}`, errors);
+    if (value !== undefined) engine[key] = value;
+  }
+
+  if (hasOwn(bodyEngine, 'worktreeRoot')) {
+    const value = parseString(bodyEngine.worktreeRoot, 'engine.worktreeRoot', errors);
+    if (value !== undefined) engine.worktreeRoot = value || shared.ENGINE_DEFAULTS.worktreeRoot;
+  }
+  if (hasOwn(bodyEngine, 'operatorLogin')) {
+    const value = parseClearableString(bodyEngine.operatorLogin, 'engine.operatorLogin', errors);
+    setOrDelete(engine, 'operatorLogin', value);
+  }
+  for (const key of ['defaultCli', 'ccCli']) {
+    if (!hasOwn(bodyEngine, key)) continue;
+    const value = parseRuntimeName(bodyEngine[key], `engine.${key}`, errors);
+    if (!CLEAR_SENTINELS.has(bodyEngine[key]) && value === undefined) continue;
+    setOrDelete(engine, key, value);
+  }
+  for (const key of ['defaultModel', 'ccModel', 'claudeFallbackModel', 'copilotFallbackModel']) {
+    if (!hasOwn(bodyEngine, key)) continue;
+    const value = parseClearableString(bodyEngine[key], `engine.${key}`, errors);
+    if (!CLEAR_SENTINELS.has(bodyEngine[key]) && value === undefined) continue;
+    setOrDelete(engine, key, value);
+  }
+  if (hasOwn(bodyEngine, 'copilotStreamMode')) {
+    if (CLEAR_SENTINELS.has(bodyEngine.copilotStreamMode)) {
+      delete engine.copilotStreamMode;
+    } else {
+      const value = parseEnum(bodyEngine.copilotStreamMode, 'engine.copilotStreamMode', COPILOT_STREAM_MODES, errors);
+      if (value !== undefined) engine.copilotStreamMode = value;
+    }
+  }
+  if (hasOwn(bodyEngine, 'codexCcSandbox')) {
+    if (CLEAR_SENTINELS.has(bodyEngine.codexCcSandbox)) {
+      delete engine.codexCcSandbox;
+    } else {
+      const value = parseEnum(bodyEngine.codexCcSandbox, 'engine.codexCcSandbox', CODEX_SANDBOX_MODES, errors);
+      if (value !== undefined) engine.codexCcSandbox = value;
+    }
+  }
+  if (hasOwn(bodyEngine, 'fontSize')) {
+    if (CLEAR_SENTINELS.has(bodyEngine.fontSize)) {
+      delete engine.fontSize;
+    } else {
+      const value = parseEnum(bodyEngine.fontSize, 'engine.fontSize', FONT_SIZES, errors);
+      if (value !== undefined) engine.fontSize = value;
+    }
+  }
+  if (hasOwn(bodyEngine, 'maxBudgetUsd')) {
+    if (CLEAR_SENTINELS.has(bodyEngine.maxBudgetUsd)) {
+      delete engine.maxBudgetUsd;
+    } else {
+      const value = parseFiniteNumber(bodyEngine.maxBudgetUsd, 'engine.maxBudgetUsd', errors, {
+        min: 0,
+        integer: false,
+      });
+      if (value !== undefined) engine.maxBudgetUsd = value;
+    }
+  }
+  if (hasOwn(bodyEngine, 'ccEffort')) {
+    if (CLEAR_SENTINELS.has(bodyEngine.ccEffort)) {
+      engine.ccEffort = null;
+    } else {
+      const value = parseEnum(bodyEngine.ccEffort, 'engine.ccEffort', CC_EFFORT_LEVELS, errors);
+      if (value !== undefined) engine.ccEffort = value;
+    }
+  }
+  if (hasOwn(bodyEngine, 'evalMaxCost')) {
+    if (CLEAR_SENTINELS.has(bodyEngine.evalMaxCost)) {
+      engine.evalMaxCost = null;
+    } else {
+      const value = parseFiniteNumber(bodyEngine.evalMaxCost, 'engine.evalMaxCost', errors, {
+        min: 0,
+        integer: false,
+      });
+      if (value !== undefined) engine.evalMaxCost = value;
+    }
+  }
+  if (hasOwn(bodyEngine, 'maxTurnsByType')) {
+    const value = bodyEngine.maxTurnsByType;
+    if (validateObject(value, 'engine.maxTurnsByType', errors)) {
+      const normalized = {};
+      for (const [type, raw] of Object.entries(value)) {
+        const path = `engine.maxTurnsByType.${type}`;
+        if (!MAX_TURNS_TYPES.has(type)) {
+          errors.add(path, 'invalid-enum', `${path} is not a registered work type`, raw, {
+            allowedValues: [...MAX_TURNS_TYPES],
+          });
+          continue;
+        }
+        const parsed = parseFiniteNumber(raw, path, errors, { min: 5, max: 500 });
+        if (parsed !== undefined) normalized[type] = parsed;
+      }
+      engine.maxTurnsByType = normalized;
+    }
+  }
+  if (hasOwn(bodyEngine, 'ignoredCommentAuthors')) {
+    const raw = bodyEngine.ignoredCommentAuthors;
+    let values;
+    if (typeof raw === 'string') values = raw.split(',');
+    else if (Array.isArray(raw)) values = raw;
+    else {
+      errors.add('engine.ignoredCommentAuthors', 'invalid-array',
+        'engine.ignoredCommentAuthors must be a comma-separated string or string array', raw, {
+          expected: 'string or string array',
+        });
+      values = null;
+    }
+    if (values) {
+      const normalized = [];
+      values.forEach((entry, index) => {
+        if (typeof entry !== 'string') {
+          errors.add(`engine.ignoredCommentAuthors[${index}]`, 'invalid-string',
+            'ignored comment authors must be strings', entry, { expected: 'string' });
+          return;
+        }
+        const author = entry.trim().toLowerCase();
+        if (author) normalized.push(author);
+      });
+      engine.ignoredCommentAuthors = [...new Set(normalized)];
+    }
+  }
+}
+
+function applyClaudeSettings(candidate, bodyClaude, errors) {
+  if (!validateObject(bodyClaude, 'claude', errors)) return;
+  rejectUnknownFields(bodyClaude, new Set(['allowedTools']), 'claude', errors);
+  if (!isPlainObject(candidate.claude)) candidate.claude = {};
+  if (hasOwn(bodyClaude, 'allowedTools')) {
+    const value = parseString(bodyClaude.allowedTools, 'claude.allowedTools', errors, { trim: false });
+    if (value !== undefined) candidate.claude.allowedTools = value;
+  }
+}
+
+function normalizeExpertise(value, path, errors) {
+  const entries = Array.isArray(value) ? value : (typeof value === 'string' ? value.split(',') : null);
+  if (!entries) {
+    errors.add(path, 'invalid-array', `${path} must be a comma-separated string or string array`, value, {
+      expected: 'string or string array',
+    });
+    return undefined;
+  }
+  const normalized = [];
+  entries.forEach((entry, index) => {
+    if (typeof entry !== 'string') {
+      errors.add(`${path}[${index}]`, 'invalid-string', `${path} entries must be strings`, entry, {
+        expected: 'string',
+      });
+      return;
+    }
+    const text = entry.trim();
+    if (text) normalized.push(text);
+  });
+  return normalized;
+}
+
+function normalizeWorkspaceManifest(value, path, errors) {
+  if (CLEAR_SENTINELS.has(value)) return undefined;
+  if (!validateObject(value, path, errors)) return undefined;
+  rejectUnknownFields(value, WORKSPACE_MANIFEST_FIELDS, path, errors);
+  const validation = shared.validateWorkspaceManifest(value);
+  if (!validation.ok) {
+    errors.add(path, 'invalid-workspace-manifest', validation.errors.join('; '), value, {
+      expected: 'workspace manifest',
+    });
+    return undefined;
+  }
+  return cloneJson(value);
+}
+
+function applyAgentSettings(candidate, bodyAgents, errors) {
+  if (!validateObject(bodyAgents, 'agents', errors)) return;
+  if (!isPlainObject(candidate.agents)) candidate.agents = {};
+  for (const [id, updates] of Object.entries(bodyAgents)) {
+    const path = `agents.${id}`;
+    if (!hasOwn(candidate.agents, id)) {
+      errors.add(path, 'unknown-agent', `${path} is not a configured agent`, updates, {
+        allowedValues: Object.keys(candidate.agents),
+      });
+      continue;
+    }
+    if (!validateObject(updates, path, errors)) continue;
+    rejectUnknownFields(updates, AGENT_FIELDS, path, errors);
+    if (!isPlainObject(candidate.agents[id])) candidate.agents[id] = {};
+    const agent = candidate.agents[id];
+
+    if (hasOwn(updates, 'role')) {
+      const value = parseString(updates.role, `${path}.role`, errors, { trim: false });
+      if (value !== undefined) agent.role = value;
+    }
+    const expertiseKey = hasOwn(updates, 'expertise') ? 'expertise' : (hasOwn(updates, 'skills') ? 'skills' : null);
+    if (expertiseKey) {
+      const value = normalizeExpertise(updates[expertiseKey], `${path}.${expertiseKey}`, errors);
+      if (value !== undefined) {
+        agent.expertise = value;
+        delete agent.skills;
+      }
+    }
+    for (const key of ['monthlyBudgetUsd', 'maxBudgetUsd']) {
+      if (!hasOwn(updates, key)) continue;
+      if (CLEAR_SENTINELS.has(updates[key])) {
+        delete agent[key];
+      } else {
+        const value = parseFiniteNumber(updates[key], `${path}.${key}`, errors, {
+          min: 0,
+          integer: false,
+        });
+        if (value !== undefined) agent[key] = value;
+      }
+    }
+    if (hasOwn(updates, 'cli')) {
+      const value = parseRuntimeName(updates.cli, `${path}.cli`, errors);
+      if (CLEAR_SENTINELS.has(updates.cli)) delete agent.cli;
+      else if (value !== undefined) agent.cli = value;
+    }
+    if (hasOwn(updates, 'model')) {
+      const value = parseClearableString(updates.model, `${path}.model`, errors);
+      if (CLEAR_SENTINELS.has(updates.model)) delete agent.model;
+      else if (value !== undefined) agent.model = value;
+    }
+    if (hasOwn(updates, 'bareMode')) {
+      if (CLEAR_SENTINELS.has(updates.bareMode)) {
+        delete agent.bareMode;
+      } else {
+        const value = parseBoolean(updates.bareMode, `${path}.bareMode`, errors);
+        if (value !== undefined) agent.bareMode = value;
+      }
+    }
+    if (hasOwn(updates, 'workspace_manifest')) {
+      const value = normalizeWorkspaceManifest(updates.workspace_manifest, `${path}.workspace_manifest`, errors);
+      if (CLEAR_SENTINELS.has(updates.workspace_manifest)) delete agent.workspace_manifest;
+      else if (value !== undefined) agent.workspace_manifest = value;
+    }
+  }
+}
+
+function applyWorkSourceSettings(project, value, path, errors) {
+  if (!validateObject(value, path, errors)) return;
+  rejectUnknownFields(value, WORK_SOURCE_NAMES, path, errors);
+  if (!isPlainObject(project.workSources)) project.workSources = {};
+  for (const sourceName of WORK_SOURCE_NAMES) {
+    if (!hasOwn(value, sourceName)) continue;
+    const sourcePath = `${path}.${sourceName}`;
+    const update = value[sourceName];
+    if (!validateObject(update, sourcePath, errors)) continue;
+    rejectUnknownFields(update, WORK_SOURCE_FIELDS, sourcePath, errors);
+    if (!isPlainObject(project.workSources[sourceName])) {
+      project.workSources[sourceName] = {
+        enabled: true,
+        cooldownMinutes: sourceName === 'pullRequests' ? 30 : 0,
+      };
+    }
+    if (hasOwn(update, 'enabled')) {
+      const enabled = parseBoolean(update.enabled, `${sourcePath}.enabled`, errors);
+      if (enabled !== undefined) project.workSources[sourceName].enabled = enabled;
+    }
+    if (hasOwn(update, 'cooldownMinutes')) {
+      const cooldown = parseFiniteNumber(update.cooldownMinutes, `${sourcePath}.cooldownMinutes`, errors, {
+        min: 0,
+      });
+      if (cooldown !== undefined) project.workSources[sourceName].cooldownMinutes = cooldown;
+    }
+  }
+}
+
+function applyProjectSettings(candidate, bodyProjects, errors) {
+  if (!Array.isArray(bodyProjects)) {
+    errors.add('projects', 'invalid-array', 'projects must be an array', bodyProjects, { expected: 'array' });
+    return;
+  }
+  if (!Array.isArray(candidate.projects)) candidate.projects = [];
+  const seen = new Set();
+  bodyProjects.forEach((update, index) => {
+    const path = `projects[${index}]`;
+    if (!validateObject(update, path, errors)) return;
+    rejectUnknownFields(update, PROJECT_FIELDS, path, errors);
+    const name = parseString(update.name, `${path}.name`, errors, { allowEmpty: false });
+    if (name === undefined) return;
+    const normalizedName = name.toLowerCase();
+    if (seen.has(normalizedName)) {
+      errors.add(`${path}.name`, 'duplicate-project', `Project "${name}" appears more than once`, name);
+      return;
+    }
+    seen.add(normalizedName);
+    const project = shared.findProjectByName(candidate.projects, name);
+    if (!project) {
+      errors.add(`${path}.name`, 'unknown-project', `Project "${name}" is not configured`, name, {
+        allowedValues: candidate.projects.map(entry => entry && entry.name).filter(Boolean),
+      });
+      return;
+    }
+
+    if (hasOwn(update, 'workSources')) {
+      applyWorkSourceSettings(project, update.workSources, `${path}.workSources`, errors);
+    }
+    if (hasOwn(update, 'mainBranch')) {
+      const value = parseClearableString(update.mainBranch, `${path}.mainBranch`, errors);
+      if (CLEAR_SENTINELS.has(update.mainBranch)) delete project.mainBranch;
+      else if (value !== undefined) project.mainBranch = value;
+    }
+
+    const hasCheckoutMode = hasOwn(update, 'checkoutMode');
+    const hasLegacyMode = hasOwn(update, 'worktreeMode');
+    if (hasCheckoutMode && hasLegacyMode) {
+      errors.add(`${path}.checkoutMode`, 'conflicting-alias',
+        'Specify checkoutMode or the deprecated worktreeMode alias, not both', update.checkoutMode);
+    } else if (hasCheckoutMode || hasLegacyMode) {
+      const key = hasCheckoutMode ? 'checkoutMode' : 'worktreeMode';
+      const raw = update[key];
+      const value = errors.capture(`${path}.${key}`, raw, () => shared.validateCheckoutMode(raw));
+      if (value === undefined && CLEAR_SENTINELS.has(raw)) delete project.checkoutMode;
+      else if (value !== undefined) project.checkoutMode = value;
+      delete project.worktreeMode;
+      if (project.checkoutMode !== 'live') delete project.liveValidation;
+    } else if (hasOwn(project, 'worktreeMode')) {
+      project.checkoutMode = shared.resolveCheckoutMode(project);
+      delete project.worktreeMode;
+    }
+
+    if (hasOwn(update, 'liveValidation')) {
+      const raw = update.liveValidation;
+      if (CLEAR_SENTINELS.has(raw)) {
+        delete project.liveValidation;
+      } else {
+        const value = errors.capture(`${path}.liveValidation`, raw, () => (
+          shared.validateLiveValidation(raw, { checkoutMode: shared.resolveCheckoutMode(project) })
+        ));
+        if (value !== undefined) project.liveValidation = value;
+      }
+    }
+    if (hasOwn(update, 'liveCheckoutAutoStash')) {
+      const raw = update.liveCheckoutAutoStash;
+      if (CLEAR_SENTINELS.has(raw)) {
+        delete project.liveCheckoutAutoStash;
+      } else {
+        const value = parseBoolean(raw, `${path}.liveCheckoutAutoStash`, errors);
+        if (value !== undefined) project.liveCheckoutAutoStash = value;
+      }
+    }
+    // W-mrxv648b — per-project "Create PRs as draft" override. null / '' /
+    // undefined clears the override (engine fleet-wide `engine.createPrsAsDraft`
+    // applies); an explicit boolean pins the per-project decision.
+    if (hasOwn(update, 'createPrsAsDraft')) {
+      const raw = update.createPrsAsDraft;
+      if (CLEAR_SENTINELS.has(raw) || raw === undefined) {
+        delete project.createPrsAsDraft;
+      } else {
+        const value = parseBoolean(raw, `${path}.createPrsAsDraft`, errors);
+        if (value !== undefined) project.createPrsAsDraft = value;
+      }
+    }
+    if (hasOwn(update, 'additionalRepoScopes')) {
+      const raw = update.additionalRepoScopes;
+      if (CLEAR_SENTINELS.has(raw) || (Array.isArray(raw) && raw.length === 0)) {
+        delete project.additionalRepoScopes;
+      } else {
+        const value = errors.capture(`${path}.additionalRepoScopes`, raw, () => (
+          shared.validateAdditionalRepoScopes(raw)
+        ));
+        if (value !== undefined) project.additionalRepoScopes = value;
+      }
+    }
+  });
+}
+
+function applyFeatureSettings(candidate, bodyFeatures, errors) {
+  if (!validateObject(bodyFeatures, 'features', errors)) return;
+  if (!isPlainObject(candidate.features)) candidate.features = {};
+  for (const [id, raw] of Object.entries(bodyFeatures)) {
+    const path = `features.${id}`;
+    if (!features.hasFeature(id)) {
+      errors.add(path, 'unknown-feature', `${path} is not registered`, raw, {
+        allowedValues: Object.keys(features.FEATURES),
+      });
+      continue;
+    }
+    const value = parseBoolean(raw, path, errors);
+    if (value !== undefined) candidate.features[id] = value;
+  }
+}
+
+function resolveModelPair(config, agent) {
+  const engine = isPlainObject(config.engine) ? config.engine : {};
+  return {
+    runtime: shared.resolveAgentCli(agent, engine),
+    model: shared.resolveAgentModel(agent, engine),
+  };
+}
+
+function resolveCcModelPair(config) {
+  const engine = isPlainObject(config.engine) ? config.engine : {};
+  return {
+    runtime: shared.resolveCcCli(engine),
+    model: shared.resolveCcModel(engine),
+  };
+}
+
+function collectChangedModelPairs(base, candidate) {
+  const checks = new Map();
+  const add = (before, after, path) => {
+    if (!after.model || (before.runtime === after.runtime && before.model === after.model)) return;
+    const key = `${after.runtime}\u0000${after.model}`;
+    if (!checks.has(key)) checks.set(key, { ...after, path });
+  };
+
+  add(resolveModelPair(base, null), resolveModelPair(candidate, null), 'engine.defaultModel');
+  add(resolveCcModelPair(base), resolveCcModelPair(candidate), 'engine.ccModel');
+
+  const baseAgents = isPlainObject(base.agents) ? base.agents : {};
+  const candidateAgents = isPlainObject(candidate.agents) ? candidate.agents : {};
+  for (const [id, agent] of Object.entries(candidateAgents)) {
+    const before = resolveModelPair(base, baseAgents[id]);
+    const after = resolveModelPair(candidate, agent);
+    const path = agent && agent.model ? `agents.${id}.model` : 'engine.defaultModel';
+    add(before, after, path);
+  }
+  return [...checks.values()];
+}
+
+async function discoverModels(runtimeName, catalogCache, candidate) {
+  if (catalogCache.has(runtimeName)) return catalogCache.get(runtimeName);
+  const adapter = runtimes.resolveRuntime(runtimeName);
+  if (adapter.capabilities && adapter.capabilities.modelDiscovery !== true) {
+    catalogCache.set(runtimeName, null);
+    return null;
+  }
+  let result;
+  try {
+    result = await modelDiscovery.getRuntimeModels(runtimeName, {
+      config: candidate,
+      force: true,
+      persist: false,
+      throwOnUnavailable: true,
+    });
+  } catch (error) {
+    throw new SettingsDiscoveryError(runtimeName, error);
+  }
+  const models = result.models;
+  if (!Array.isArray(models) || models.length === 0) {
+    throw new SettingsDiscoveryError(runtimeName, new Error('Runtime returned no model catalog'));
+  }
+  const ids = new Set();
+  for (const model of models) {
+    if (model && typeof model.id === 'string' && model.id) ids.add(model.id);
+    if (model && typeof model.name === 'string' && model.name) ids.add(model.name);
+  }
+  if (ids.size === 0) {
+    throw new SettingsDiscoveryError(runtimeName, new Error('Runtime returned a malformed model catalog'));
+  }
+  catalogCache.set(runtimeName, ids);
+  return ids;
+}
+
+async function validateModelPairs(base, candidate, errors) {
+  if (candidate.engine && candidate.engine.disableModelDiscovery === true) return;
+  const checks = collectChangedModelPairs(base, candidate);
+  if (checks.length === 0) return;
+  const catalogCache = new Map();
+  const runtimeNames = runtimes.listRuntimes();
+
+  for (const check of checks) {
+    let adapter;
+    try {
+      adapter = runtimes.resolveRuntime(check.runtime);
+    } catch (error) {
+      errors.add(check.path, 'unknown-runtime', error.message, check.runtime, {
+        allowedValues: runtimeNames,
+      });
+      continue;
+    }
+    let normalizedModel = check.model;
+    if (typeof adapter.resolveModel === 'function') {
+      try {
+        normalizedModel = adapter.resolveModel(check.model) || check.model;
+      } catch (error) {
+        errors.add(check.path, 'invalid-runtime-model', error.message, check.model, {
+          expected: `model accepted by ${check.runtime}`,
+        });
+        continue;
+      }
+    }
+    // A runtime's discovered catalog is authoritative — and therefore worth an
+    // enforced membership check — only when the runtime can discover models AND
+    // has not explicitly opted out of strict catalog enforcement. Discovery-
+    // capable runtimes default to strict (Copilot leaves `strictModelCatalog`
+    // unset but its published catalog is authoritative), so an unknown model is
+    // rejected. Runtimes that set `strictModelCatalog: false` (e.g. Codex, which
+    // must accept staged/custom model IDs not yet in its bundled catalog) or
+    // that cannot discover at all accept any model the adapter's own
+    // `resolveModel()` already validated. We never infer ownership from another
+    // runtime's overlapping catalog: catalogs overlap, so membership elsewhere
+    // is not exclusive ownership, and requiring an unrelated runtime's discovery
+    // would surface spurious rejections or 503s for a model that is valid here.
+    const caps = adapter.capabilities || {};
+    const catalogIsAuthoritative = caps.modelDiscovery === true && caps.strictModelCatalog !== false;
+    if (!catalogIsAuthoritative) continue;
+
+    const targetModels = await discoverModels(check.runtime, catalogCache, candidate);
+    if (targetModels && (targetModels.has(check.model) || targetModels.has(normalizedModel))) continue;
+    errors.add(check.path, 'incompatible-runtime-model',
+      `Model "${check.model}" is not available for runtime "${check.runtime}"`, check.model, {
+        expected: `model supported by ${check.runtime}`,
+      });
+  }
+}
+
+function validateCcEffortCapability(candidate, body, errors) {
+  if (!body.engine || !isPlainObject(body.engine)) return;
+  if (!['ccEffort', 'ccCli', 'defaultCli'].some(key => hasOwn(body.engine, key))) return;
+  const effort = candidate.engine && candidate.engine.ccEffort;
+  if (!effort) return;
+  const runtimeName = shared.resolveCcCli(candidate.engine);
+  let adapter;
+  try {
+    adapter = runtimes.resolveRuntime(runtimeName);
+  } catch {
+    return;
+  }
+  if (!adapter.capabilities || adapter.capabilities.effortLevels !== true) {
+    errors.add('engine.ccEffort', 'unsupported-runtime-capability',
+      `Runtime "${runtimeName}" does not support effort levels`, effort, {
+        expected: 'effort-capable runtime',
+      });
+  }
+}
+
+async function buildSettingsCandidate(currentConfig, body) {
+  const errors = new SettingsErrorCollector();
+  if (!validateObject(body, 'settings', errors)) errors.throwIfAny();
+  rejectUnknownFields(body, SETTINGS_TOP_LEVEL_FIELDS, 'settings', errors);
+  const base = ensureCurrentConfig(currentConfig);
+  const candidate = cloneJson(base);
+
+  if (hasOwn(body, 'engine')) applyEngineSettings(candidate, body.engine, errors);
+  if (hasOwn(body, 'claude')) applyClaudeSettings(candidate, body.claude, errors);
+  if (hasOwn(body, 'agents')) applyAgentSettings(candidate, body.agents, errors);
+  if (hasOwn(body, 'projects')) applyProjectSettings(candidate, body.projects, errors);
+  if (hasOwn(body, 'features')) applyFeatureSettings(candidate, body.features, errors);
+  validateCcEffortCapability(candidate, body, errors);
+
+  // Do not start catalog I/O when ordinary validation has already rejected the
+  // request. This preserves both runtime caches and the all-or-nothing contract.
+  errors.throwIfAny();
+  await validateModelPairs(base, candidate, errors);
+  errors.throwIfAny();
+
+  shared.pruneDefaultClaudeConfig(candidate, { trackStrip: false });
+  return {
+    base,
+    candidate,
+    sideEffects: {
+      resetOperatorIdentity: (base.engine && base.engine.operatorLogin)
+        !== (candidate.engine && candidate.engine.operatorLogin),
+    },
+  };
+}
+
+function buildSettingsResetCandidate(currentConfig) {
+  const base = ensureCurrentConfig(currentConfig);
+  const candidate = cloneJson(base);
+  candidate.engine = cloneJson(shared.ENGINE_DEFAULTS);
+  candidate.agents = cloneJson(shared.DEFAULT_AGENTS);
+  delete candidate.claude;
+  return {
+    base,
+    candidate,
+    sideEffects: {
+      resetOperatorIdentity: (base.engine && base.engine.operatorLogin)
+        !== (candidate.engine && candidate.engine.operatorLogin),
+    },
+  };
+}
+
+function buildRoutingCandidate(body) {
+  const errors = new SettingsErrorCollector();
+  if (!validateObject(body, 'routing', errors)) errors.throwIfAny();
+  rejectUnknownFields(body, new Set(['content']), 'routing', errors);
+  if (!hasOwn(body, 'content')) {
+    errors.add('content', 'required-field', 'content is required', undefined, { expected: 'non-empty string' });
+  } else {
+    parseString(body.content, 'content', errors, { allowEmpty: false, trim: false });
+  }
+  errors.throwIfAny();
+  return body.content;
+}
+
+module.exports = {
+  SettingsDiscoveryError,
+  buildSettingsCandidate,
+  buildSettingsResetCandidate,
+  buildRoutingCandidate,
+  ENGINE_NUMERIC_RANGES,
+  MAX_SETTINGS_ERRORS,
+};