rafcode 3.2.1 → 3.8.0

package/src/utils/config.ts

@@ -8,16 +8,17 @@ import {
   UserConfig,
   VALID_MODEL_ALIASES,
   VALID_CODEX_MODEL_ALIASES,
-  VALID_HARNESS_PROVIDERS,
+  VALID_HARNESSES,
   FULL_MODEL_ID_PATTERN,
-  ClaudeModelName,
   TaskEffortLevel,
   ModelScenario,
+  ModelEntry,
   CommitFormatType,
   DisplayConfig,
   EffortMappingConfig,
-  HarnessProvider,
+  HarnessName,
 } from '../types/config.js';
+import { logger } from './logger.js';
 
 const CONFIG_DIR = path.join(os.homedir(), '.raf');
 const CONFIG_FILENAME = 'raf.config.json';
@@ -36,11 +37,18 @@ export function getClaudeSettingsPath(): string {
 // ---- Validation ----
 
 const VALID_TOP_LEVEL_KEYS = new Set<string>([
-  'provider', 'models', 'effortMapping', 'codexModels', 'codexEffortMapping',
+  'models', 'effortMapping',
   'timeout', 'maxRetries', 'autoCommit',
   'worktree', 'syncMainBranch', 'commitFormat', 'display',
 ]);
 
+/** Keys that were removed in the schema migration. Rejected with a helpful error. */
+const REMOVED_KEYS: Record<string, string> = {
+  provider: 'Top-level "provider" has been removed. Use "harness" inside each "models" and "effortMapping" entry instead.',
+  codexModels: '"codexModels" has been removed. Use "models" with harness-aware entries (e.g. { "model": "gpt-5.4", "harness": "codex" }) instead.',
+  codexEffortMapping: '"codexEffortMapping" has been removed. Use "effortMapping" with harness-aware entries instead.',
+};
+
 const VALID_MODEL_KEYS = new Set<string>([
   'plan', 'execute', 'nameGeneration', 'failureAnalysis', 'prGeneration', 'config',
 ]);
@@ -51,6 +59,10 @@ const VALID_COMMIT_FORMAT_KEYS = new Set<string>(['task', 'plan', 'amend', 'pref
 
 const VALID_DISPLAY_KEYS = new Set<string>(['showCacheTokens']);
 
+const VALID_MODEL_ENTRY_KEYS = new Set<string>(['model', 'harness', 'reasoningEffort', 'fast']);
+
+const VALID_REASONING_EFFORTS = new Set<string>(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+
 export class ConfigValidationError extends Error {
   constructor(message: string) {
     super(message);
@@ -66,7 +78,7 @@ function checkUnknownKeys(obj: Record<string, unknown>, validKeys: Set<string>,
   }
 }
 
-/** Regex for raw Codex model IDs (e.g., `gpt-5.4`, `gpt-5.3-codex-spark`). Requires dot-separated version. */
+/** Regex for raw Codex model IDs (e.g., `gpt-5.4`, `gpt-5.3-codex`). Requires dot-separated version. */
 const CODEX_MODEL_ID_PATTERN = /^gpt-\d+\.\d+(-.+)*$/;
 
 /**
@@ -74,19 +86,19 @@ const CODEX_MODEL_ID_PATTERN = /^gpt-\d+\.\d+(-.+)*$/;
  * Accepts:
  * - Claude short aliases: sonnet, haiku, opus
  * - Claude full IDs: claude-opus-4-6
- * - Codex short aliases: spark, codex, gpt54
- * - Raw Codex model IDs: gpt-5.4, gpt-5.3-codex-spark
+ * - Codex short aliases: codex, gpt54
+ * - Raw Codex model IDs: gpt-5.4, gpt-5.3-codex
  * - Harness-prefixed format: claude/opus, codex/gpt-5.4
  */
 export function isValidModelName(value: string): boolean {
-  // Harness-prefixed format: provider/model
+  // Harness-prefixed format: harness/model
   const prefixMatch = value.match(/^(claude|codex)\/(.+)$/);
   if (prefixMatch) {
-    const [, provider, model] = prefixMatch;
-    if (provider === 'claude') {
+    const [, harness, model] = prefixMatch;
+    if (harness === 'claude') {
       return (VALID_MODEL_ALIASES as readonly string[]).includes(model!) || FULL_MODEL_ID_PATTERN.test(model!);
     }
-    if (provider === 'codex') {
+    if (harness === 'codex') {
       return (VALID_CODEX_MODEL_ALIASES as readonly string[]).includes(model!) || CODEX_MODEL_ID_PATTERN.test(model!);
     }
   }
@@ -105,25 +117,97 @@ export function isValidModelName(value: string): boolean {
 }
 
 /**
- * Parse a model spec string into its provider and model components.
- * - `codex/gpt-5.4` -> { provider: 'codex', model: 'gpt-5.4' }
- * - `claude/opus` -> { provider: 'claude', model: 'opus' }
- * - `opus` -> { provider: 'claude', model: 'opus' } (defaults to claude)
- * - `gpt-5.4` -> { provider: 'codex', model: 'gpt-5.4' } (inferred from model format)
+ * Parse a model spec string into its harness and model components.
+ * - `codex/gpt-5.4` -> { harness: 'codex', model: 'gpt-5.4' }
+ * - `claude/opus` -> { harness: 'claude', model: 'opus' }
+ * - `opus` -> { harness: 'claude', model: 'opus' } (defaults to claude)
+ * - `gpt-5.4` -> { harness: 'codex', model: 'gpt-5.4' } (inferred from model format)
  */
-export function parseModelSpec(modelSpec: string): { provider: HarnessProvider; model: string } {
+export function parseModelSpec(modelSpec: string): { harness: HarnessName; model: string } {
   const prefixMatch = modelSpec.match(/^(claude|codex)\/(.+)$/);
   if (prefixMatch) {
-    return { provider: prefixMatch[1] as HarnessProvider, model: prefixMatch[2]! };
+    return { harness: prefixMatch[1] as HarnessName, model: prefixMatch[2]! };
   }
 
-  // Infer provider from model format
+  // Infer harness from model format
   if ((VALID_CODEX_MODEL_ALIASES as readonly string[]).includes(modelSpec) || CODEX_MODEL_ID_PATTERN.test(modelSpec)) {
-    return { provider: 'codex', model: modelSpec };
+    return { harness: 'codex', model: modelSpec };
   }
 
   // Default to claude
-  return { provider: 'claude', model: modelSpec };
+  return { harness: 'claude', model: modelSpec };
+}
+
+/**
+ * Validate a model entry object: { model, harness, reasoningEffort? }
+ */
+function validateModelEntry(obj: unknown, prefix: string): void {
+  if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
+    throw new ConfigValidationError(`${prefix} must be a model entry object (e.g. { "model": "opus", "harness": "claude" })`);
+  }
+  const entry = obj as Record<string, unknown>;
+  checkUnknownKeys(entry, VALID_MODEL_ENTRY_KEYS, prefix);
+
+  if (entry.model === undefined) {
+    throw new ConfigValidationError(`${prefix}.model is required`);
+  }
+  if (typeof entry.model !== 'string' || !isValidModelName(entry.model)) {
+    throw new ConfigValidationError(
+      `${prefix}.model must be a valid model name (e.g. opus, sonnet, gpt-5.4, claude-opus-4-6)`
+    );
+  }
+
+  if (entry.harness === undefined) {
+    throw new ConfigValidationError(`${prefix}.harness is required`);
+  }
+  if (typeof entry.harness !== 'string' || !(VALID_HARNESSES as readonly string[]).includes(entry.harness)) {
+    throw new ConfigValidationError(`${prefix}.harness must be one of: ${VALID_HARNESSES.join(', ')}`);
+  }
+
+  if (entry.reasoningEffort !== undefined) {
+    if (typeof entry.reasoningEffort !== 'string' || !VALID_REASONING_EFFORTS.has(entry.reasoningEffort)) {
+      throw new ConfigValidationError(`${prefix}.reasoningEffort must be one of: none, minimal, low, medium, high, xhigh, max`);
+    }
+  }
+
+  if (entry.fast !== undefined) {
+    if (typeof entry.fast !== 'boolean') {
+      throw new ConfigValidationError(`${prefix}.fast must be a boolean`);
+    }
+  }
+}
+
+function getCodexFastWarning(prefix: string): string {
+  return `${prefix}.fast is enabled but ignored because Codex does not support fast mode`;
+}
+
+function collectModelEntryWarnings(obj: unknown, prefix: string, warnings: string[]): void {
+  if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
+    return;
+  }
+
+  const entry = obj as Record<string, unknown>;
+  if (entry.harness === 'codex' && entry.fast === true) {
+    warnings.push(getCodexFastWarning(prefix));
+  }
+}
+
+export function collectConfigValidationWarnings(config: UserConfig): string[] {
+  const warnings: string[] = [];
+
+  if (config.models && typeof config.models === 'object') {
+    for (const [key, value] of Object.entries(config.models)) {
+      collectModelEntryWarnings(value, `models.${key}`, warnings);
+    }
+  }
+
+  if (config.effortMapping && typeof config.effortMapping === 'object') {
+    for (const [key, value] of Object.entries(config.effortMapping)) {
+      collectModelEntryWarnings(value, `effortMapping.${key}`, warnings);
+    }
+  }
+
+  return warnings;
 }
 
 export function validateConfig(config: unknown): UserConfig {
@@ -132,15 +216,16 @@ export function validateConfig(config: unknown): UserConfig {
   }
 
   const obj = config as Record<string, unknown>;
-  checkUnknownKeys(obj, VALID_TOP_LEVEL_KEYS, '');
 
-  // provider
-  if (obj.provider !== undefined) {
-    if (typeof obj.provider !== 'string' || !(VALID_HARNESS_PROVIDERS as readonly string[]).includes(obj.provider)) {
-      throw new ConfigValidationError(`provider must be one of: ${VALID_HARNESS_PROVIDERS.join(', ')}`);
+  // Check for removed keys first (helpful error messages)
+  for (const [key, message] of Object.entries(REMOVED_KEYS)) {
+    if (key in obj) {
+      throw new ConfigValidationError(message);
     }
   }
 
+  checkUnknownKeys(obj, VALID_TOP_LEVEL_KEYS, '');
+
   // models
   if (obj.models !== undefined) {
     if (typeof obj.models !== 'object' || obj.models === null || Array.isArray(obj.models)) {
@@ -149,11 +234,7 @@ export function validateConfig(config: unknown): UserConfig {
     const models = obj.models as Record<string, unknown>;
     checkUnknownKeys(models, VALID_MODEL_KEYS, 'models');
     for (const [key, val] of Object.entries(models)) {
-      if (typeof val !== 'string' || !isValidModelName(val)) {
-        throw new ConfigValidationError(
-          `models.${key} must be a short alias (${VALID_MODEL_ALIASES.join(', ')}) or a full model ID (e.g., claude-sonnet-4-5-20250929)`
-        );
-      }
+      validateModelEntry(val, `models.${key}`);
     }
   }
 
@@ -165,43 +246,7 @@ export function validateConfig(config: unknown): UserConfig {
     const effortMapping = obj.effortMapping as Record<string, unknown>;
     checkUnknownKeys(effortMapping, VALID_EFFORT_MAPPING_KEYS, 'effortMapping');
     for (const [key, val] of Object.entries(effortMapping)) {
-      if (typeof val !== 'string' || !isValidModelName(val)) {
-        throw new ConfigValidationError(
-          `effortMapping.${key} must be a short alias (${VALID_MODEL_ALIASES.join(', ')}) or a full model ID (e.g., claude-sonnet-4-5-20250929)`
-        );
-      }
-    }
-  }
-
-  // codexModels
-  if (obj.codexModels !== undefined) {
-    if (typeof obj.codexModels !== 'object' || obj.codexModels === null || Array.isArray(obj.codexModels)) {
-      throw new ConfigValidationError('codexModels must be an object');
-    }
-    const codexModels = obj.codexModels as Record<string, unknown>;
-    checkUnknownKeys(codexModels, VALID_MODEL_KEYS, 'codexModels');
-    for (const [key, val] of Object.entries(codexModels)) {
-      if (typeof val !== 'string' || !isValidModelName(val)) {
-        throw new ConfigValidationError(
-          `codexModels.${key} must be a valid model name (e.g., gpt-5.4, gpt-5.3-codex-spark)`
-        );
-      }
-    }
-  }
-
-  // codexEffortMapping
-  if (obj.codexEffortMapping !== undefined) {
-    if (typeof obj.codexEffortMapping !== 'object' || obj.codexEffortMapping === null || Array.isArray(obj.codexEffortMapping)) {
-      throw new ConfigValidationError('codexEffortMapping must be an object');
-    }
-    const codexEffortMapping = obj.codexEffortMapping as Record<string, unknown>;
-    checkUnknownKeys(codexEffortMapping, VALID_EFFORT_MAPPING_KEYS, 'codexEffortMapping');
-    for (const [key, val] of Object.entries(codexEffortMapping)) {
-      if (typeof val !== 'string' || !isValidModelName(val)) {
-        throw new ConfigValidationError(
-          `codexEffortMapping.${key} must be a valid model name (e.g., gpt-5.4, gpt-5.3-codex-spark)`
-        );
-      }
+      validateModelEntry(val, `effortMapping.${key}`);
     }
   }
 
@@ -273,21 +318,57 @@ export function validateConfig(config: unknown): UserConfig {
 
 // ---- Deep merge ----
 
+/** Deep-merge a single model entry: user override replaces the default entirely. */
+function mergeModelEntry(defaultEntry: ModelEntry, override: unknown): ModelEntry {
+  const normalizedEntry = (entry: ModelEntry): ModelEntry => {
+    if (entry.harness !== 'codex') {
+      return entry;
+    }
+    const { fast: _ignored, ...rest } = entry;
+    return rest;
+  };
+
+  if (override && typeof override === 'object' && !Array.isArray(override)) {
+    const o = override as Record<string, unknown>;
+    return normalizedEntry({
+      model: typeof o.model === 'string' ? o.model : defaultEntry.model,
+      harness: typeof o.harness === 'string' ? (o.harness as HarnessName) : defaultEntry.harness,
+      ...(o.reasoningEffort !== undefined
+        ? { reasoningEffort: o.reasoningEffort as ModelEntry['reasoningEffort'] }
+        : defaultEntry.reasoningEffort !== undefined
+          ? { reasoningEffort: defaultEntry.reasoningEffort }
+          : {}),
+      ...(o.fast !== undefined
+        ? { fast: o.fast as boolean }
+        : defaultEntry.fast !== undefined
+          ? { fast: defaultEntry.fast }
+          : {}),
+    });
+  }
+  return normalizedEntry(defaultEntry);
+}
+
 function deepMerge(defaults: RafConfig, overrides: UserConfig): RafConfig {
   const result = { ...defaults };
 
-  if (overrides.provider !== undefined) result.provider = overrides.provider;
   if (overrides.models) {
-    result.models = { ...defaults.models, ...overrides.models };
+    const m = overrides.models as Record<string, unknown>;
+    result.models = {
+      plan: m.plan ? mergeModelEntry(defaults.models.plan, m.plan) : { ...defaults.models.plan },
+      execute: m.execute ? mergeModelEntry(defaults.models.execute, m.execute) : { ...defaults.models.execute },
+      nameGeneration: m.nameGeneration ? mergeModelEntry(defaults.models.nameGeneration, m.nameGeneration) : { ...defaults.models.nameGeneration },
+      failureAnalysis: m.failureAnalysis ? mergeModelEntry(defaults.models.failureAnalysis, m.failureAnalysis) : { ...defaults.models.failureAnalysis },
+      prGeneration: m.prGeneration ? mergeModelEntry(defaults.models.prGeneration, m.prGeneration) : { ...defaults.models.prGeneration },
+      config: m.config ? mergeModelEntry(defaults.models.config, m.config) : { ...defaults.models.config },
+    };
   }
   if (overrides.effortMapping) {
-    result.effortMapping = { ...defaults.effortMapping, ...overrides.effortMapping };
-  }
-  if (overrides.codexModels) {
-    result.codexModels = { ...defaults.codexModels, ...overrides.codexModels };
-  }
-  if (overrides.codexEffortMapping) {
-    result.codexEffortMapping = { ...defaults.codexEffortMapping, ...overrides.codexEffortMapping };
+    const e = overrides.effortMapping as Record<string, unknown>;
+    result.effortMapping = {
+      low: e.low ? mergeModelEntry(defaults.effortMapping.low, e.low) : { ...defaults.effortMapping.low },
+      medium: e.medium ? mergeModelEntry(defaults.effortMapping.medium, e.medium) : { ...defaults.effortMapping.medium },
+      high: e.high ? mergeModelEntry(defaults.effortMapping.high, e.high) : { ...defaults.effortMapping.high },
+    };
   }
   if (overrides.commitFormat) {
     result.commitFormat = { ...defaults.commitFormat, ...overrides.commitFormat };
@@ -316,10 +397,19 @@ export function resolveConfig(configPath?: string): RafConfig {
   if (!fs.existsSync(filePath)) {
     return {
       ...DEFAULT_CONFIG,
-      models: { ...DEFAULT_CONFIG.models },
-      effortMapping: { ...DEFAULT_CONFIG.effortMapping },
-      codexModels: { ...DEFAULT_CONFIG.codexModels },
-      codexEffortMapping: { ...DEFAULT_CONFIG.codexEffortMapping },
+      models: {
+        plan: { ...DEFAULT_CONFIG.models.plan },
+        execute: { ...DEFAULT_CONFIG.models.execute },
+        nameGeneration: { ...DEFAULT_CONFIG.models.nameGeneration },
+        failureAnalysis: { ...DEFAULT_CONFIG.models.failureAnalysis },
+        prGeneration: { ...DEFAULT_CONFIG.models.prGeneration },
+        config: { ...DEFAULT_CONFIG.models.config },
+      },
+      effortMapping: {
+        low: { ...DEFAULT_CONFIG.effortMapping.low },
+        medium: { ...DEFAULT_CONFIG.effortMapping.medium },
+        high: { ...DEFAULT_CONFIG.effortMapping.high },
+      },
       commitFormat: { ...DEFAULT_CONFIG.commitFormat },
       display: { ...DEFAULT_CONFIG.display },
     };
@@ -328,6 +418,9 @@ export function resolveConfig(configPath?: string): RafConfig {
   const content = fs.readFileSync(filePath, 'utf-8');
   const parsed: unknown = JSON.parse(content);
   const validated = validateConfig(parsed);
+  for (const warning of collectConfigValidationWarnings(validated)) {
+    logger.warn(`Config validation warning: ${warning}`);
+  }
   return deepMerge(DEFAULT_CONFIG, validated);
 }
 
@@ -365,36 +458,27 @@ export function resetConfigCache(): void {
   _cachedConfig = null;
 }
 
-export function getModel(scenario: ModelScenario, provider?: HarnessProvider): ClaudeModelName {
+/**
+ * Get the model entry for a scenario.
+ */
+export function getModel(scenario: ModelScenario): ModelEntry {
   const config = getResolvedConfig();
-  const effectiveProvider = provider ?? config.provider;
-  if (effectiveProvider === 'codex') {
-    return config.codexModels[scenario];
-  }
   return config.models[scenario];
 }
 
 /**
  * Get the full effort mapping config.
  */
-export function getEffortMapping(provider?: HarnessProvider): EffortMappingConfig {
+export function getEffortMapping(): EffortMappingConfig {
   const config = getResolvedConfig();
-  const effectiveProvider = provider ?? config.provider;
-  if (effectiveProvider === 'codex') {
-    return config.codexEffortMapping;
-  }
   return config.effortMapping;
 }
 
 /**
- * Resolve a task effort level to a model name using the effort mapping config.
+ * Resolve a task effort level to a model entry using the effort mapping config.
  */
-export function resolveEffortToModel(effort: TaskEffortLevel, provider?: HarnessProvider): ClaudeModelName {
+export function resolveEffortToModel(effort: TaskEffortLevel): ModelEntry {
   const config = getResolvedConfig();
-  const effectiveProvider = provider ?? config.provider;
-  if (effectiveProvider === 'codex') {
-    return config.codexEffortMapping[effort];
-  }
   return config.effortMapping[effort];
 }
 
@@ -409,14 +493,12 @@ const MODEL_TIER_ORDER: Record<string, number> = {
   opus: 3,
 };
 
-/** Codex model tier ordering: spark (1) < codex (2) < gpt-5.4 (3) */
+/** Codex model tier ordering: codex (1) < gpt54 (2) */
 const CODEX_MODEL_TIER_ORDER: Record<string, number> = {
-  spark: 1,
-  'gpt-5.3-codex-spark': 1,
-  codex: 2,
-  'gpt-5.3-codex': 2,
-  gpt54: 3,
-  'gpt-5.4': 3,
+  codex: 1,
+  'gpt-5.3-codex': 1,
+  gpt54: 2,
+  'gpt-5.4': 2,
 };
 
 /**
@@ -451,19 +533,20 @@ export function getModelTier(modelName: string): number {
 }
 
 /**
- * Apply ceiling to a model based on the configured models.execute ceiling.
- * Returns the lower-tier model between the input and the ceiling.
+ * Apply ceiling to a model entry based on the configured models.execute ceiling.
+ * Returns the lower-tier entry between the input and the ceiling.
+ * When the input exceeds the ceiling, the ceiling entry is returned (including its harness).
  */
-export function applyModelCeiling(resolvedModel: string, ceiling?: string): string {
-  const ceilingModel = ceiling ?? getModel('execute');
-  const resolvedTier = getModelTier(resolvedModel);
-  const ceilingTier = getModelTier(ceilingModel);
+export function applyModelCeiling(resolved: ModelEntry, ceiling?: ModelEntry): ModelEntry {
+  const ceilingEntry = ceiling ?? getModel('execute');
+  const resolvedTier = getModelTier(resolved.model);
+  const ceilingTier = getModelTier(ceilingEntry.model);
 
   // If resolved model is above ceiling, use ceiling instead
   if (resolvedTier > ceilingTier) {
-    return ceilingModel;
+    return ceilingEntry;
   }
-  return resolvedModel;
+  return resolved;
 }
 
 export function getCommitFormat(type: CommitFormatType): string {
@@ -505,11 +588,10 @@ export function getModelShortName(modelId: string): string {
     return modelId;
   }
   // Codex short aliases
-  if (modelId === 'spark' || modelId === 'codex' || modelId === 'gpt54') {
+  if (modelId === 'codex' || modelId === 'gpt54') {
     return modelId;
   }
   // Codex model IDs -> short names
-  if (modelId === 'gpt-5.3-codex-spark') return 'spark';
   if (modelId === 'gpt-5.3-codex') return 'codex';
   if (modelId === 'gpt-5.4') return 'gpt54';
   // Extract family from full Claude model ID: claude-{family}-{version}
@@ -524,6 +606,10 @@ export function getModelShortName(modelId: string): string {
   return modelId;
 }
 
+function normalizeModelAlias(value: string): string {
+  return value.toLowerCase().replace(/^gpt-/, 'gpt').replace(/[^a-z0-9]/g, '');
+}
+
 /**
  * Mapping of short model aliases to their current full model IDs.
  * These should match the latest Claude model versions.
@@ -532,11 +618,58 @@ const MODEL_ALIAS_TO_FULL_ID: Record<string, string> = {
   opus: 'claude-opus-4-6',
   sonnet: 'claude-sonnet-4-5-20250929',
   haiku: 'claude-haiku-4-5-20251001',
-  spark: 'gpt-5.3-codex-spark',
   codex: 'gpt-5.3-codex',
   gpt54: 'gpt-5.4',
 };
 
+function getPreferredModelDisplayLabel(alias: string): string {
+  const fullId = MODEL_ALIAS_TO_FULL_ID[alias];
+  if (!fullId) {
+    return alias;
+  }
+
+  return normalizeModelAlias(alias) === normalizeModelAlias(fullId) ? fullId : alias;
+}
+
+/**
+ * Get the centralized user-facing display label for a model.
+ * Keeps concise Claude labels, while normalizing compact aliases like gpt54 -> gpt-5.4.
+ */
+export function getModelDisplayName(modelId: string): string {
+  const aliasedDisplay = getPreferredModelDisplayLabel(modelId);
+  if (aliasedDisplay !== modelId) {
+    return aliasedDisplay;
+  }
+
+  const matchingAliases = Object.entries(MODEL_ALIAS_TO_FULL_ID)
+    .filter(([, fullId]) => fullId === modelId)
+    .map(([alias]) => alias);
+  if (matchingAliases.length > 0) {
+    const preferredAlias = matchingAliases[matchingAliases.length - 1]!;
+    return getPreferredModelDisplayLabel(preferredAlias);
+  }
+
+  return getModelShortName(modelId);
+}
+
+interface ModelDisplayOptions {
+  includeHarness?: boolean;
+  fullId?: boolean;
+}
+
+/**
+ * Format a model label for user-facing logs.
+ * Defaults to the centralized display policy, or can opt into explicit full-ID display.
+ */
+export function formatModelDisplay(
+  model: string,
+  harness?: HarnessName,
+  options: ModelDisplayOptions = {},
+): string {
+  const label = options.fullId ? resolveFullModelId(model) : getModelDisplayName(model);
+  return options.includeHarness && harness ? `${label} (${harness})` : label;
+}
+
 /**
  * Resolve a model name to its full model ID.
  * If already a full model ID, returns as-is.

package/src/utils/name-generator.ts

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { logger } from './logger.js';
 import { sanitizeProjectName } from './validation.js';
 import { getModel } from './config.js';
+import type { HarnessName } from '../types/config.js';
 
 const NAME_GENERATION_PROMPT = `Output ONLY the kebab-case name. No introduction, no explanation, no quotes.
 
@@ -29,20 +30,35 @@ Rules:
 
 Project description:`;
 
-/**
- * Run the CLI with the given prompt and return stdout.
- * Uses spawn with --no-session-persistence to avoid cluttering session history.
- */
-function runClaudePrint(prompt: string): Promise<string | null> {
-  return new Promise((resolve) => {
-    const model = getModel('nameGeneration');
-
-    const proc = spawn('claude', [
+function buildNameGenerationArgs(harness: HarnessName, model: string, prompt: string): string[] {
+  if (harness === 'claude') {
+    return [
       '--model', model,
       '--no-session-persistence',
       '-p',
       prompt,
-    ], {
+    ];
+  }
+
+  return [
+    'exec',
+    '--skip-git-repo-check',
+    '--ephemeral',
+    '--color', 'never',
+    '-m', model,
+    prompt,
+  ];
+}
+
+/**
+ * Run the configured name-generation CLI with the given prompt and return stdout.
+ */
+function runNameGenerationPrint(prompt: string): Promise<string | null> {
+  return new Promise((resolve) => {
+    const entry = getModel('nameGeneration');
+    const args = buildNameGenerationArgs(entry.harness, entry.model, prompt);
+
+    const proc = spawn(entry.harness, args, {
       stdio: ['ignore', 'pipe', 'pipe'],
     });
 
@@ -110,7 +126,7 @@ export async function generateProjectName(description: string): Promise<string>
 export async function generateProjectNames(description: string): Promise<string[]> {
   try {
     const names = await callSonnetForMultipleNames(description);
-    if (names.length >= 3) {
+    if (names.length > 0) {
       logger.debug(`Generated ${names.length} project names`);
       return names;
     }
@@ -129,7 +145,7 @@ export async function generateProjectNames(description: string): Promise<string[
  */
 async function callSonnetForName(description: string): Promise<string | null> {
   const fullPrompt = `${NAME_GENERATION_PROMPT}\n${description}`;
-  return runClaudePrint(fullPrompt);
+  return runNameGenerationPrint(fullPrompt);
 }
 
 /**
@@ -137,7 +153,7 @@ async function callSonnetForName(description: string): Promise<string | null> {
  */
 async function callSonnetForMultipleNames(description: string): Promise<string[]> {
   const fullPrompt = `${MULTI_NAME_GENERATION_PROMPT}\n${description}`;
-  const result = await runClaudePrint(fullPrompt);
+  const result = await runNameGenerationPrint(fullPrompt);
 
   if (!result) {
     return [];