patina-cli 3.11.0 → 4.0.0

package/src/features/stylometry.js

@@ -1,9 +1,89 @@
-// Burstiness CV + MATTR per core/stylometry.md §4 §5.
+// Burstiness CV, MATTR, and dependency-free KO diagnostics per core/stylometry.md.
 // Pure functions over token arrays; no I/O.
 
 export const DEFAULT_BURSTINESS_BANDS = { low: 0.30, high: 0.50 };
 export const DEFAULT_MATTR_BANDS = { low: 0.55, high: 0.70 };
 export const DEFAULT_MATTR_WINDOW = 50;
+export const DEFAULT_MIN_BURSTINESS_SENTENCES = 3;
+export const DEFAULT_KO_DIAGNOSTIC_BANDS = {
+  minSentences: 4,
+  minEojeols: 20,
+  spacing: {
+    maxEojeolLengthCV: 0.38,
+  },
+  comma: {
+    maxPerSentence: 1,
+  },
+  posProxy: {
+    minMatchedCount: 10,
+    maxClassDiversity: 0.26,
+  },
+};
+
+const HANGUL_RE = /[\u3131-\u318e\uac00-\ud7a3]/u;
+const COMMA_RE = /[,，、]/gu;
+
+const KO_SUFFIX_GROUPS = [
+  { className: 'quote', suffixes: ['라고', '이라고'] },
+  { className: 'source', suffixes: ['에게서', '한테서', '으로부터', '로부터'] },
+  { className: 'instrument', suffixes: ['으로써', '로써'] },
+  { className: 'standard', suffixes: ['으로서', '로서'] },
+  { className: 'topic', suffixes: ['은', '는'] },
+  { className: 'subject', suffixes: ['이', '가', '께서'] },
+  { className: 'object', suffixes: ['을', '를'] },
+  { className: 'genitive', suffixes: ['의'] },
+  { className: 'location', suffixes: ['에서', '에게', '한테', '께', '에'] },
+  { className: 'direction', suffixes: ['으로', '로'] },
+  { className: 'conjunction', suffixes: ['와', '과', '하고', '랑'] },
+  { className: 'additive', suffixes: ['도', '또한'] },
+  { className: 'delimiter', suffixes: ['만', '까지', '부터', '마다'] },
+  { className: 'comparison', suffixes: ['보다', '처럼'] },
+  { className: 'formal_ending', suffixes: ['습니다', '습니까', '합니다', '합니까', '입니다'] },
+  { className: 'polite_ending', suffixes: ['어요', '아요', '예요', '이에요', '네요', '군요', '지요'] },
+  { className: 'casual_ending', suffixes: ['죠', '네', '군'] },
+  { className: 'declarative_ending', suffixes: ['한다', '된다', '했다', '였다', '이다', '있다', '없다'] },
+];
+
+const KO_SUFFIX_MATCHERS = KO_SUFFIX_GROUPS
+  .flatMap((group) =>
+    group.suffixes.map((suffix) => ({
+      className: group.className,
+      suffix,
+      length: Array.from(suffix).length,
+    }))
+  )
+  .sort((a, b) => b.length - a.length);
+
+function mean(values) {
+  if (!Array.isArray(values) || values.length === 0) return null;
+  return values.reduce((a, b) => a + b, 0) / values.length;
+}
+
+function coefficientOfVariation(values) {
+  if (!Array.isArray(values) || values.length < 2) return null;
+  const avg = mean(values);
+  if (!avg) return null;
+  const variance = values.reduce((acc, x) => acc + (x - avg) ** 2, 0) / values.length;
+  return Math.sqrt(variance) / avg;
+}
+
+function cleanKoreanEojeol(chunk) {
+  return chunk
+    .normalize('NFC')
+    .replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, '');
+}
+
+function koreanEojeols(paragraph) {
+  if (!paragraph) return [];
+  return paragraph
+    .split(/\s+/u)
+    .map(cleanKoreanEojeol)
+    .filter((token) => HANGUL_RE.test(token));
+}
+
+function koreanLength(token) {
+  return Array.from(token.replace(/[^\u3131-\u318e\uac00-\ud7a3]/gu, '')).length;
+}
 
 // Coefficient of variation of sentence token counts.
 // Returns null when the paragraph has fewer than 2 sentences or mean is 0.
@@ -35,6 +115,116 @@ export function mattr(tokens, window = DEFAULT_MATTR_WINDOW) {
   return sum / count;
 }
 
+export function koreanSpacingFeatures(paragraph) {
+  const eojeols = koreanEojeols(paragraph);
+  const lengths = eojeols.map(koreanLength).filter((length) => length > 0);
+  const eojeolCount = lengths.length;
+
+  return {
+    eojeolCount,
+    meanEojeolLength: mean(lengths),
+    eojeolLengthCV: coefficientOfVariation(lengths),
+    singleSyllableRatio:
+      eojeolCount > 0 ? lengths.filter((length) => length === 1).length / eojeolCount : null,
+    longEojeolRatio:
+      eojeolCount > 0 ? lengths.filter((length) => length >= 7).length / eojeolCount : null,
+  };
+}
+
+export function commaDensity(paragraph, sentenceCount = null) {
+  const commaCount = (paragraph.match(COMMA_RE) ?? []).length;
+  const charCount = Array.from(paragraph.replace(/\s+/gu, '')).length;
+
+  return {
+    count: commaCount,
+    perSentence: sentenceCount > 0 ? commaCount / sentenceCount : null,
+    per100Chars: charCount > 0 ? (commaCount / charCount) * 100 : null,
+  };
+}
+
+export function koreanPosDiversityProxy(paragraph) {
+  const eojeols = koreanEojeols(paragraph);
+  const matches = [];
+
+  for (const token of eojeols) {
+    const match = KO_SUFFIX_MATCHERS.find(
+      (candidate) => token.length > candidate.suffix.length && token.endsWith(candidate.suffix)
+    );
+    if (match) {
+      matches.push({ className: match.className, suffix: match.suffix });
+    }
+  }
+
+  const matchedCount = matches.length;
+  const classes = [...new Set(matches.map((match) => match.className))].sort();
+  const suffixes = [...new Set(matches.map((match) => match.suffix))].sort();
+
+  return {
+    proxy: 'suffix',
+    eojeolCount: eojeols.length,
+    matchedCount,
+    coverage: eojeols.length > 0 ? matchedCount / eojeols.length : null,
+    distinctClassCount: classes.length,
+    classDiversity: matchedCount > 0 ? classes.length / matchedCount : null,
+    distinctSuffixCount: suffixes.length,
+    suffixDiversity: matchedCount > 0 ? suffixes.length / matchedCount : null,
+    classes,
+  };
+}
+
+/**
+ * @param {{ sentenceCount?: number, spacing?: object, comma?: object, posDiversity?: object }} [features]
+ * @param {object} [bands]
+ */
+export function classifyKoreanDiagnostics({
+  sentenceCount = 0,
+  spacing,
+  comma,
+  posDiversity,
+} = {}, bands = DEFAULT_KO_DIAGNOSTIC_BANDS) {
+  const thresholds = mergeKoreanDiagnosticBands(bands);
+  const reasons = [];
+
+  const hasEnoughText =
+    sentenceCount >= thresholds.minSentences &&
+    (spacing?.eojeolCount ?? 0) >= thresholds.minEojeols;
+  if (!hasEnoughText) {
+    return { hot: false, strength: 0, reasons, thresholds };
+  }
+
+  const spacingStrength = lowThresholdStrength(
+    spacing?.eojeolLengthCV,
+    thresholds.spacing.maxEojeolLengthCV
+  );
+  if (spacingStrength > 0) reasons.push('regular-eojeol-length');
+
+  const commaStrength = lowThresholdStrength(
+    comma?.perSentence,
+    thresholds.comma.maxPerSentence
+  );
+  if (commaStrength > 0) reasons.push('low-comma-density');
+
+  const posHasCoverage =
+    (posDiversity?.matchedCount ?? 0) >= thresholds.posProxy.minMatchedCount;
+  const posStrength = posHasCoverage
+    ? lowThresholdStrength(
+        posDiversity?.classDiversity,
+        thresholds.posProxy.maxClassDiversity
+      )
+    : 0;
+  if (posStrength > 0) reasons.push('low-suffix-class-diversity');
+
+  const componentStrengths = [spacingStrength, commaStrength, posStrength];
+  const hot = componentStrengths.every((value) => value > 0);
+
+  return {
+    hot,
+    strength: hot ? Math.min(...componentStrengths) : 0,
+    reasons: hot ? reasons : [],
+    thresholds,
+  };
+}
+
 export function classifyBurstiness(cv, bands = DEFAULT_BURSTINESS_BANDS) {
   if (cv == null) return null;
   if (cv < bands.low) return 'low';
@@ -48,3 +238,43 @@ export function classifyMattr(value, bands = DEFAULT_MATTR_BANDS) {
   if (value > bands.high) return 'high';
   return 'mid';
 }
+
+function mergeKoreanDiagnosticBands(bands = {}) {
+  return {
+    minSentences: resolveNumber(bands.minSentences, DEFAULT_KO_DIAGNOSTIC_BANDS.minSentences),
+    minEojeols: resolveNumber(bands.minEojeols, DEFAULT_KO_DIAGNOSTIC_BANDS.minEojeols),
+    spacing: {
+      maxEojeolLengthCV: resolveNumber(
+        bands.spacing?.maxEojeolLengthCV,
+        DEFAULT_KO_DIAGNOSTIC_BANDS.spacing.maxEojeolLengthCV
+      ),
+    },
+    comma: {
+      maxPerSentence: resolveNumber(
+        bands.comma?.maxPerSentence,
+        DEFAULT_KO_DIAGNOSTIC_BANDS.comma.maxPerSentence
+      ),
+    },
+    posProxy: {
+      minMatchedCount: resolveNumber(
+        bands.posProxy?.minMatchedCount,
+        DEFAULT_KO_DIAGNOSTIC_BANDS.posProxy.minMatchedCount
+      ),
+      maxClassDiversity: resolveNumber(
+        bands.posProxy?.maxClassDiversity,
+        DEFAULT_KO_DIAGNOSTIC_BANDS.posProxy.maxClassDiversity
+      ),
+    },
+  };
+}
+
+function resolveNumber(value, fallback) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+function lowThresholdStrength(value, threshold) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return 0;
+  if (threshold === 0) return value <= 0 ? 100 : 0;
+  if (!threshold || threshold < 0 || value > threshold) return 0;
+  return Math.max(0, Math.min(100, (1 - value / threshold) * 100));
+}

package/src/features/translationese.js

@@ -0,0 +1,127 @@
+// Korean translationese (번역투 / calque) detector. The stylometry + lexicon
+// signals catch STRUCTURE (sentence rhythm, AI lexicon); they do NOT catch
+// lexical calques — phrasings that are grammatical Korean but read as
+// translated-from-English ("커맨드 기둥" for "command pillars", "~에 의해" passives,
+// "당신" for "you"). This deterministic, auditable detector fills that gap.
+//
+// IMPORTANT — precision first. Most of these constructions ALSO appear in good
+// native Korean (formal/technical prose especially). So this is a DENSITY-GATED
+// SUSPICION signal, not proof: a single "~에 의해" means nothing. It is surfaced
+// as its own `translationese` signal and does NOT flip the document `hot`
+// verdict (so it cannot regress benchmark false positives); the SKILL / callers
+// decide what to do with it. Each rule ships a before→after example.
+//
+// ko-only for now (calques are language-specific).
+import { splitProseSentences } from './segment.js';
+
+// strong: rarer in good Korean, weighted higher. weak: common, advisory only.
+// Each rule: { id, label, strong, re() -> fresh global RegExp, example:{before,after} }
+const RULES = [
+  {
+    id: 'noun-calque',
+    label: '직역 명사구 (pillar/layer 류 calque)',
+    strong: true,
+    re: () => /커맨드 기둥|명령(?:어)? 기둥|기둥 커맨드|[가-힣]+ 레이어로서/g,
+    example: { before: '세 가지 커맨드 기둥을 설치합니다.', after: '핵심 커맨드 세 가지를 설치합니다.' },
+  },
+  {
+    id: 'dummy-subject',
+    label: '가주어 "그것은/이것은" (English "it is")',
+    strong: true,
+    re: () => /(?:^|[.!?。]\s+|\n)\s*(?:그것은|이것은|그것이|이것이)\s/g,
+    example: { before: '그것은 매우 중요하다.', after: '매우 중요하다.' },
+  },
+  {
+    id: 'direct-address-you',
+    label: '"당신" 직접 호칭 (English "you")',
+    strong: true,
+    re: () => /당신(?:은|이|의|에게|을|를|께서|께)?/g,
+    example: { before: '당신은 이것을 설정할 수 있습니다.', after: '이건 설정할 수 있다.' },
+  },
+  {
+    id: 'passive-e-uihae',
+    label: '"~에 의해" 피동 (English by-passive)',
+    strong: false,
+    re: () => /에 의해/g,
+    example: { before: '작업은 에이전트에 의해 처리됩니다.', after: '에이전트가 작업을 처리합니다.' },
+  },
+  {
+    id: 'have-overuse',
+    label: '"~을 가지고 있다" (English "have")',
+    strong: false,
+    re: () => /(?:을|를)\s*가지(?:고 있|고 있습니다|고 있다)/g,
+    example: { before: '이 도구는 유연성을 가지고 있습니다.', after: '이 도구는 유연합니다.' },
+  },
+  {
+    id: 'one-of',
+    label: '"~중 하나" (English "one of the")',
+    strong: false,
+    re: () => /중\s*하나(?:이다|입니다|인|로|다|예요)?/g,
+    example: { before: '가장 빠른 도구 중 하나입니다.', after: '손꼽히게 빠릅니다.' },
+  },
+  {
+    id: 'provides',
+    label: '"~을 제공합니다" (English "provides")',
+    strong: false,
+    re: () => /(?:을|를)\s*제공(?:합니다|한다|해 줍니다|해준다)/g,
+    example: { before: '다양한 기능을 제공합니다.', after: '여러 기능을 쓸 수 있다.' },
+  },
+  {
+    id: 'as-follows',
+    label: '"다음과 같습니다" (English "as follows")',
+    strong: false,
+    re: () => /다음과\s*같(?:습니다|다|은|이)/g,
+    example: { before: '사용법은 다음과 같습니다.', after: '사용법은 이렇다.' },
+  },
+  {
+    id: 'make-easy',
+    label: '"~하게 만들어 준다" (English "make it ~")',
+    strong: false,
+    re: () => /(?:쉽게|가능하게|간단하게|편하게)\s*(?:만들어\s*(?:줍니다|준다|줘)|만듭니다|만든다)/g,
+    example: { before: '설치를 쉽게 만들어 줍니다.', after: '설치가 쉬워진다.' },
+  },
+];
+
+const ABS_MIN = 4;      // need at least this many total calque hits, and
+const DENSITY_MIN = 0.5; // at least this many hits per prose sentence, to call it hot.
+
+/**
+ * Scan ko text for translationese (calque) markers.
+ * @param {string} text
+ * @param {{lang?: string}} [opts]
+ * @returns {{count:number, density:number, sentences:number, byRule:Array, hits:string[], hot:boolean, thresholds:{count:number,density:number}}}
+ */
+export function detectTranslationese(text, opts = {}) {
+  const lang = opts.lang ?? 'ko';
+  const str = typeof text === 'string' ? text : '';
+  if (lang !== 'ko' || !str) {
+    return { count: 0, density: 0, sentences: 0, byRule: [], hits: [], hot: false, thresholds: { count: ABS_MIN, density: DENSITY_MIN } };
+  }
+  const byRule = [];
+  const hits = [];
+  let count = 0;
+  for (const rule of RULES) {
+    const matches = str.match(rule.re());
+    if (matches && matches.length) {
+      count += matches.length;
+      byRule.push({ id: rule.id, label: rule.label, strong: rule.strong, count: matches.length, example: rule.example });
+      hits.push(...new Set(matches.map((m) => m.trim()).filter(Boolean)));
+    }
+  }
+  const sentences = Math.max(1, splitProseSentences(str).length);
+  const density = count / sentences;
+  // Conservative: needs both an absolute floor AND a per-sentence density, so
+  // long legit docs with a few calques never trip it.
+  const hot = count >= ABS_MIN && density >= DENSITY_MIN;
+  return {
+    count,
+    density: Number(density.toFixed(3)),
+    sentences,
+    byRule: byRule.sort((a, b) => b.count - a.count),
+    hits: [...new Set(hits)].slice(0, 8),
+    hot,
+    thresholds: { count: ABS_MIN, density: DENSITY_MIN },
+  };
+}
+
+export { RULES as TRANSLATIONESE_RULES, ABS_MIN, DENSITY_MIN };

package/src/loader.js

@@ -3,10 +3,28 @@ import { resolve, sep } from 'node:path';
 import yaml from 'js-yaml';
 import { validateProfileName } from './security.js';
 
+/**
+ * Read a UTF-8 text file.
+ *
+ * @param {string} path File path to read.
+ * @returns {string} File contents.
+ * @throws {Error} When the file cannot be read.
+ * @example
+ * const markdown = loadFile('README.md');
+ */
 export function loadFile(path) {
   return readFileSync(path, 'utf8');
 }
 
+/**
+ * Split Markdown-style YAML frontmatter from a document body.
+ *
+ * @param {string} content File contents.
+ * @returns {{frontmatter: object|null, body: string}} Parsed frontmatter and trimmed body.
+ * @throws {Error} When YAML frontmatter is invalid.
+ * @example
+ * const { frontmatter, body } = splitFrontmatter('---\ntitle: x\n---\nBody');
+ */
 export function splitFrontmatter(content) {
   const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
   if (!match) {
@@ -18,6 +36,17 @@ export function splitFrontmatter(content) {
   };
 }
 
+/**
+ * Load language-specific pattern packs from patterns/{lang}-*.md.
+ *
+ * @param {string} repoRoot Repository root path.
+ * @param {string} lang Language code, such as ko, en, zh, or ja.
+ * @param {string[]} [skipPatterns=[]] Pack names to omit, without .md.
+ * @returns {Array<{file: string, frontmatter: object|null, body: string, isStructure: boolean, isScoreOnly: boolean}>} Pattern packs.
+ * @throws {Error} When the patterns directory or a pattern file cannot be read.
+ * @example
+ * const patterns = loadPatterns(getRepoRoot(), 'en');
+ */
 export function loadPatterns(repoRoot, lang, skipPatterns = []) {
   const patternsDir = resolve(repoRoot, 'patterns');
   const files = readdirSync(patternsDir)
@@ -43,6 +72,16 @@ export function loadPatterns(repoRoot, lang, skipPatterns = []) {
   return packs;
 }
 
+/**
+ * Load a named profile from profiles/{profileName}.md after path validation.
+ *
+ * @param {string} repoRoot Repository root path.
+ * @param {string} profileName Profile file stem.
+ * @returns {{frontmatter: object|null, body: string}} Parsed profile document.
+ * @throws {Error} When the profile name is invalid or the file cannot be read.
+ * @example
+ * const profile = loadProfile(getRepoRoot(), 'default');
+ */
 export function loadProfile(repoRoot, profileName) {
   validateProfileName(profileName);
   const profilesDir = resolve(repoRoot, 'profiles');
@@ -54,16 +93,44 @@ export function loadProfile(repoRoot, profileName) {
   return splitFrontmatter(content);
 }
 
+/**
+ * Load a Markdown file from the core/ directory.
+ *
+ * @param {string} repoRoot Repository root path.
+ * @param {string} filename Core filename, such as scoring.md.
+ * @returns {{frontmatter: object|null, body: string}} Parsed core document.
+ * @throws {Error} When the file cannot be read or frontmatter is invalid.
+ * @example
+ * const scoring = loadCoreFile(getRepoRoot(), 'scoring.md');
+ */
 export function loadCoreFile(repoRoot, filename) {
   const path = resolve(repoRoot, 'core', filename);
   const content = loadFile(path);
   return splitFrontmatter(content);
 }
 
+/**
+ * Read user input text from disk.
+ *
+ * @param {string} path Input file path.
+ * @returns {string} UTF-8 input text.
+ * @throws {Error} When the file cannot be read.
+ * @example
+ * const text = loadInputText('draft.md');
+ */
 export function loadInputText(path) {
   return readFileSync(path, 'utf8');
 }
 
+/**
+ * Load up to three non-empty paragraphs from a voice sample file.
+ *
+ * @param {string} path Voice sample file path.
+ * @returns {{path: string, paragraphs: string[], body: string, truncated: boolean}} Voice sample payload.
+ * @throws {Error} When the file is unreadable or has no non-empty paragraphs.
+ * @example
+ * const sample = loadVoiceSample('voice.md');
+ */
 export function loadVoiceSample(path) {
   const content = loadFile(path);
   const paragraphs = content
@@ -98,6 +165,15 @@ const TONE_BACKBONE = {
   instructional: 'instructional',
 };
 
+/**
+ * Map a resolved named tone to its primary backbone profile.
+ *
+ * @param {string} tone Tone name.
+ * @returns {string|null} Profile name, or null when no mapping exists.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const profile = toneToBackboneProfile('casual'); // blog
+ */
 export function toneToBackboneProfile(tone) {
   return TONE_BACKBONE[tone] || null;
 }

package/src/logger.js

@@ -6,10 +6,22 @@ const LEVELS = {
   silent: Infinity,
 };
 
+/**
+ * Create a small stderr logger with text and progress modes.
+ *
+ * @param {object} [options] Logger options.
+ * @param {string} [options.level=info] Minimum log level.
+ * @param {boolean} [options.quiet=false] Suppress all log output.
+ * @param {NodeJS.WritableStream} [options.stream=process.stderr] Progress stream.
+ * @returns {{debug: Function, info: Function, warn: Function, error: Function, progress: Function, closeProgress: Function, child: Function}} Logger facade.
+ * @throws {Error} Propagates stream write errors from the configured output stream.
+ * @example
+ * const logger = createLogger();
+ * logger.info('event', { message: 'ready' });
+ */
 export function createLogger({
   level = process.env.PATINA_LOG_LEVEL || 'info',
   quiet = false,
-  json = false,
   stream = process.stderr,
 } = {}) {
   const threshold = quiet ? LEVELS.silent : (LEVELS[String(level).toLowerCase()] ?? LEVELS.info);
@@ -18,19 +30,11 @@ export function createLogger({
   const emit = (levelName, event, fields = {}) => {
     if (LEVELS[levelName] < threshold) return;
     closeProgress();
-    if (json) {
-      console.error(JSON.stringify(record(levelName, event, fields)));
-      return;
-    }
     if (fields.message) console.error(fields.message);
   };
 
-  const progress = (event, fields = {}) => {
+  const progress = (_event, fields = {}) => {
     if (LEVELS.info < threshold) return;
-    if (json) {
-      console.error(JSON.stringify(record('info', event, fields)));
-      return;
-    }
     if (!fields.message || !stream?.write) return;
     stream.write(`\r${fields.message}`);
     progressOpen = true;
@@ -49,22 +53,17 @@ export function createLogger({
     progress,
     closeProgress,
     child(extra = {}) {
-      return createLogger({ level, quiet, json, stream, ...extra });
+      return createLogger({ level, quiet, stream, ...extra });
     },
   };
 }
 
-function record(level, event, fields = {}) {
-  const { message, model = null, latency_ms = null, ...rest } = fields;
-  return {
-    ts: new Date().toISOString(),
-    level,
-    event,
-    model,
-    latency_ms,
-    ...(message ? { message } : {}),
-    ...rest,
-  };
-}
 
+/**
+ * Default stderr logger used by simple callers.
+ *
+ * @type {Object}
+ * @example
+ * defaultLogger.info('patina.ready', { message: 'ready' });
+ */
 export const defaultLogger = createLogger();

package/src/model-defaults.js

@@ -0,0 +1,55 @@
+// @ts-check
+
+/**
+ * Default to the strongest stable model ids that patina documents for each
+ * backend family. These values are intentionally centralized so releases can
+ * refresh "latest best" defaults without touching backend process plumbing.
+ */
+export const DEFAULT_BEST_MODELS = Object.freeze({
+  openai: 'gpt-5.5',
+  codexCli: 'gpt-5.5',
+  claudeCli: 'claude-sonnet-4-6',
+  geminiCli: 'gemini-2.5-pro',
+  kimiCli: 'kimi-code/kimi-for-coding',
+});
+
+const BACKEND_MODEL_KEYS = Object.freeze({
+  'codex-cli': 'codexCli',
+  'claude-cli': 'claudeCli',
+  'gemini-cli': 'geminiCli',
+  'kimi-cli': 'kimiCli',
+});
+
+const BACKEND_SELECTOR_ALIASES = Object.freeze({
+  'codex-cli': 'codex',
+  'claude-cli': 'claude',
+  'gemini-cli': 'gemini',
+  'kimi-cli': 'kimi',
+});
+
+/**
+ * Resolve the model id a local CLI backend should receive.
+ *
+ * `resolveProviderConfig` always supplies an HTTP default model when the user
+ * did not choose one. Local CLIs need their own family-specific defaults, so
+ * `modelSource: "default"` is treated as unset. Exact selector aliases such as
+ * `--model codex` still route to the backend without becoming invalid model ids.
+ *
+ * @param {object} options
+ * @param {string} options.backendName Local backend name.
+ * @param {string|null|undefined} [options.model] Resolved model value.
+ * @param {string|null|undefined} [options.modelSource] Source label from provider resolution.
+ * @returns {string|null} Effective local CLI model id.
+ */
+export function resolveLocalCliModel({ backendName, model, modelSource }) {
+  const key = BACKEND_MODEL_KEYS[backendName];
+  if (!key) return model || null;
+
+  const defaultModel = DEFAULT_BEST_MODELS[key];
+  if (!model || modelSource === 'default') return defaultModel;
+
+  const alias = BACKEND_SELECTOR_ALIASES[backendName];
+  if (alias && String(model).toLowerCase() === alias) return defaultModel;
+
+  return model;
+}