oh-my-knowledge 0.47.0 → 0.49.0

package/dist/authoring/generator.d.ts

@@ -3,8 +3,8 @@ import type { ObservationInboxItem } from '../types/observability.js';
 interface GenerateSamplesOptions {
     skillContent: string;
     count?: number;
-    model?: string;
-    executorName?: string;
+    model: string;
+    executorName: string;
     /**
      * 自然语言描述用户希望重点覆盖的场景。会作为额外约束追加到 prompt 末尾，
      * 优先于"自由发挥"的多样性。空串 / undefined 表示不施加额外约束。
@@ -66,7 +66,7 @@ export declare function buildSamplesFromTracesPrompt(items: TraceSignalItem[], c
 export interface GenerateSamplesFromTracesOptions {
     items: TraceSignalItem[];
     count?: number;
-    model?: string;
+    model: string;
     executorName?: string;
     /** Injectable executor (tests). Defaults to createExecutor(executorName). */
     executor?: ExecutorFn;

package/dist/authoring/generator.js

@@ -1,13 +1,5 @@
 import { createExecutor } from '../executors/index.js';
 import { DEFAULT_GATE_THRESHOLD } from '../eval-core/verdict.js';
-/**
- * Generator 默认模型 'opus' (跟 eval 默认对齐)。
- * lean=true 路径会自动追加 `--effort low`,关掉 opus 默认的扩展思考,
- * 所以 opus + lean + effort-low 在 generator 场景下速度仍然可控(单 skill ~30-60s)。
- * 成本约 sonnet 的 5x,但 opus 在结构化指令遵循 / 长 prompt 一致性上更稳。
- * 用户想要省钱时显式 `--model sonnet` 即可。
- */
-const GENERATOR_DEFAULT_MODEL = 'sonnet';
 const SYSTEM_PROMPT = `你是一个评测用例生成器。你的任务是根据用户提供的 skill（系统提示词）内容，生成高质量的评测用例。
 
 样本结构决策（必须先做）：先扫一遍 skill 内容判断它属于哪一类，按对应配比和数量生成。
@@ -398,7 +390,7 @@ ${skillContent}
 
 ${countLine}直接输出 JSON 数组。${focusBlock}${noMockBlock}`;
 }
-export async function generateSamples({ skillContent, count, model = GENERATOR_DEFAULT_MODEL, executorName = 'claude', focus, noMock }) {
+export async function generateSamples({ skillContent, count, model, executorName, focus, noMock }) {
     const executor = createExecutor(executorName);
     const prompt = buildSamplesPrompt({ skillContent, count, focus, noMock });
     // 生成场景比单次 eval 调用更重(LLM 要思考结构 + 输出大段 JSON),
@@ -547,9 +539,12 @@ function traceSanitizeContext(items) {
  * stamps `provenance: 'production-trace'`. Output is meant to land in a review draft,
  * not the live dataset (the CLI enforces that).
  */
-export async function generateSamplesFromTraces({ items, count, model = GENERATOR_DEFAULT_MODEL, executorName = 'claude', executor: injectedExecutor, }) {
+export async function generateSamplesFromTraces({ items, count, model, executorName, executor: injectedExecutor, }) {
     if (items.length === 0)
         return { samples: [], costUSD: 0 };
+    if (!injectedExecutor && !executorName) {
+        throw new Error('executorName is required when no executor is injected');
+    }
     const executor = injectedExecutor ?? createExecutor(executorName);
     const prompt = buildSamplesFromTracesPrompt(items, count);
     const sanitizeContext = traceSanitizeContext(items);

package/dist/authoring/sample-fixer.d.ts

@@ -1,4 +1,5 @@
 import type { EvaluationReport } from '../types/report.js';
+import type { ToolCallInfo } from '../types/index.js';
 export interface FixContext {
     sampleId: string;
     originalSample: Record<string, unknown>;
@@ -12,11 +13,7 @@ export interface FixContext {
         value: string;
         passed: boolean;
     }>;
-    toolCalls: Array<{
-        tool: string;
-        input: unknown;
-        success: boolean;
-    }>;
+    toolCalls: Array<Pick<ToolCallInfo, 'tool' | 'input' | 'success' | 'status'>>;
 }
 export interface FixSamplesOptions {
     skillContent: string;
@@ -33,18 +30,23 @@ export interface FixSamplesOptions {
         ok: boolean;
         text: string;
         costUSD: number;
+        costReported?: boolean;
     }>;
-    model?: string;
+    model: string;
     maxAttemptsPerSample?: number;
 }
 export interface FixSamplesResult {
     samples: Record<string, unknown>[];
     fixedCount: number;
     costUSD: number;
+    /** false 表示 costUSD 只是执行器已上报部分的下界。 */
+    costReported: boolean;
     fixes: Array<{
         sampleId: string;
         changed: boolean;
         error?: string;
     }>;
 }
+export declare function sampleFixWithinScope(previous: Record<string, unknown>, next: Record<string, unknown>): boolean;
+export declare function stampFixMetadata(sample: Record<string, unknown>, reportId: string): void;
 export declare function fixSamples(options: FixSamplesOptions): Promise<FixSamplesResult>;

package/dist/authoring/sample-fixer.js

@@ -1,10 +1,11 @@
+import { toolCallStatus } from '../shared/tool-call-status.js';
 import { sanitizeGeneratedSamples } from './generator.js';
 const FIX_SYSTEM_PROMPT = `你是一个评测用例修复专家。根据诊断信息和失败断言修复评测用例（sample）。
 
 修复原则：
 1. 先分析失败原因——是 sample 设计问题（mock 缺失 / 断言写错 / 工具名不匹配）还是 LLM 行为问题（LLM 真的做错了,低分合理）
 2. **如果是 LLM 行为问题（低分合理）,不要改 sample,原样返回**
-3. 如果是 sample 设计问题,修复 mocks / assertions / environment,必要时微调 rubric
+3. 如果是 sample 设计问题,只修复 mocks / mocksStrict / assertions / environment
 4. 保持 sample_id 不变,保持测试意图不变
 5. provenance 只能使用现有合法枚举: "human" / "llm-generated" / "production-trace"。不要发明 "llm-generated-fixed"、"fixed" 等新值；不确定时保留原值或用 "llm-generated"
 6. 断言修复只保留核心行为节点：必要输出位置、必须/禁止的关键副作用、关键安全约束。不要为了贴合某次执行轨迹而绑定具体工具、命令形态、文案、完整步骤顺序或临时实现细节
@@ -23,6 +24,30 @@ function sanitizeFixedSamples(samples, skillContent) {
     sanitizeGeneratedSamples(samples, { skillContent });
     return samples;
 }
+const FIXABLE_SAMPLE_FIELDS = new Set([
+    'assertions',
+    'mocks',
+    'mocksStrict',
+    'environment',
+]);
+function canonicalStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalStringify).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalStringify(record[key])}`)
+        .join(',')}}`;
+}
+function sampleOutsideFixScope(sample) {
+    return Object.fromEntries(Object.entries(sample).filter(([key]) => !FIXABLE_SAMPLE_FIELDS.has(key)));
+}
+export function sampleFixWithinScope(previous, next) {
+    return canonicalStringify(sampleOutsideFixScope(previous))
+        === canonicalStringify(sampleOutsideFixScope(next));
+}
 function fixAttempts(sample) {
     const meta = sample.omkFix;
     if (!meta || typeof meta !== 'object')
@@ -30,7 +55,7 @@ function fixAttempts(sample) {
     const attempts = meta.attempts;
     return typeof attempts === 'number' && Number.isFinite(attempts) ? attempts : 0;
 }
-function stampFixMetadata(sample, reportId) {
+export function stampFixMetadata(sample, reportId) {
     sample.omkFix = {
         ...(typeof sample.omkFix === 'object' && sample.omkFix !== null ? sample.omkFix : {}),
         attempts: fixAttempts(sample) + 1,
@@ -72,7 +97,7 @@ function parseFixedSamples(text) {
     return null;
 }
 export async function fixSamples(options) {
-    const { skillContent, samples, report, treatmentKey, executor, model = 'opus', maxAttemptsPerSample = 2 } = options;
+    const { skillContent, samples, report, treatmentKey, executor, model, maxAttemptsPerSample = 2 } = options;
     const sampleMap = new Map(samples.map((s) => [s.sample_id, s]));
     // Collect all fixable samples into one batch
     const fixContexts = [];
@@ -114,6 +139,7 @@ export async function fixSamples(options) {
             samples,
             fixedCount: 0,
             costUSD: 0,
+            costReported: true,
             fixes: skippedByAttempts.map((sampleId) => ({ sampleId, changed: false, error: `max attempts reached (${maxAttemptsPerSample})` })),
         };
     }
@@ -127,7 +153,7 @@ export async function fixSamples(options) {
             .map((a) => `  - ${a.type}: ${a.value}`)
             .join('\n');
         const toolCallsSummary = ctx.toolCalls.length > 0
-            ? ctx.toolCalls.map((tc, i) => `  [${i}] ${tc.tool} success=${tc.success} input=${JSON.stringify(tc.input).slice(0, 150)}`).join('\n')
+            ? ctx.toolCalls.map((tc, i) => `  [${i}] ${tc.tool} status=${toolCallStatus(tc)} input=${JSON.stringify(tc.input).slice(0, 150)}`).join('\n')
             : '  (无工具调用)';
         return `### ${ctx.sampleId}
 
@@ -156,13 +182,18 @@ ${skillPreview}
 ${sampleSections}
 
 请分析每条用例的失败原因，判断是 sample 设计问题还是 LLM 行为问题。若是 sample 设计问题，优先把断言收敛到核心行为节点，放松易随机的工具/命令/文案/完整步骤绑定；不要为了过用例而要求修改 SKILL.md，也不要把 skill 的完整流程细节塞进 sample。输出一个 JSON 数组，包含所有 ${fixContexts.length} 条 sample（修改过的和原样保留的都要包含）。`;
+    let incurredCostUSD = 0;
+    let incurredCostReported = false;
     try {
         const result = await executor({ model, system: FIX_SYSTEM_PROMPT, prompt, timeoutMs: 300_000 });
+        incurredCostUSD = result.costUSD;
+        incurredCostReported = result.costReported !== false;
         if (!result.ok) {
             return {
                 samples,
                 fixedCount: 0,
                 costUSD: result.costUSD,
+                costReported: incurredCostReported,
                 fixes: fixContexts.map((ctx) => ({ sampleId: ctx.sampleId, changed: false, error: 'executor failed' })),
             };
         }
@@ -172,10 +203,48 @@ ${sampleSections}
                 samples,
                 fixedCount: 0,
                 costUSD: result.costUSD,
+                costReported: incurredCostReported,
                 fixes: fixContexts.map((ctx) => ({ sampleId: ctx.sampleId, changed: false, error: 'failed to parse LLM response as JSON array' })),
             };
         }
+        const expectedIds = fixContexts.map((context) => context.sampleId);
+        const returnedIds = fixedArr.map((sample) => sample.sample_id);
+        const returnedIdSet = new Set(returnedIds);
+        if (returnedIds.some((sampleId) => typeof sampleId !== 'string')
+            || returnedIdSet.size !== returnedIds.length
+            || returnedIdSet.size !== expectedIds.length
+            || expectedIds.some((sampleId) => !returnedIdSet.has(sampleId))) {
+            return {
+                samples,
+                fixedCount: 0,
+                costUSD: result.costUSD,
+                costReported: incurredCostReported,
+                fixes: fixContexts.map((ctx) => ({
+                    sampleId: ctx.sampleId,
+                    changed: false,
+                    error: 'fixer must return every requested sample_id exactly once and no others',
+                })),
+            };
+        }
         const sanitizedFixedArr = sanitizeFixedSamples(fixedArr, skillContent);
+        const outOfScope = sanitizedFixedArr.find((fixed) => {
+            const sid = fixed.sample_id;
+            const original = sampleMap.get(sid);
+            return !original || !sampleFixWithinScope(original, fixed);
+        });
+        if (outOfScope) {
+            return {
+                samples,
+                fixedCount: 0,
+                costUSD: result.costUSD,
+                costReported: incurredCostReported,
+                fixes: fixContexts.map((ctx) => ({
+                    sampleId: ctx.sampleId,
+                    changed: false,
+                    error: `fixer changed protected fields in sample ${String(outOfScope.sample_id)}`,
+                })),
+            };
+        }
         const fixes = [];
         for (const fixed of sanitizedFixedArr) {
             const sid = fixed.sample_id;
@@ -195,6 +264,7 @@ ${sampleSections}
             samples: samples.map((s) => sampleMap.get(s.sample_id) ?? s),
             fixedCount: fixes.filter((f) => f.changed).length,
             costUSD: result.costUSD,
+            costReported: incurredCostReported,
             fixes: [
                 ...fixes,
                 ...skippedByAttempts.map((sampleId) => ({ sampleId, changed: false, error: `max attempts reached (${maxAttemptsPerSample})` })),
@@ -205,7 +275,8 @@ ${sampleSections}
         return {
             samples,
             fixedCount: 0,
-            costUSD: 0,
+            costUSD: incurredCostUSD,
+            costReported: incurredCostReported,
             fixes: fixContexts.map((ctx) => ({ sampleId: ctx.sampleId, changed: false, error: String(err) })),
         };
     }

package/dist/cli/commands/doctor.js

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, readdirSync, unlinkSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { Args, Flags } from '@oclif/core';
 import { LANG_FLAG, bilingual } from '../oclif/i18n.js';
@@ -7,12 +7,15 @@ import { enumStringParser, integerStringParser, numberStringParser } from '../oc
 import { CliExit } from '../lib/cli-exit.js';
 import { tCli } from '../lib/i18n.js';
 import { makeDoctorProgress } from '../lib/progress.js';
+import { resolveCliExecutor, resolveRuntimeSelection } from '../lib/runtime-defaults.js';
 import { DEFAULT_DOCTORS_DIR } from '../../eval-core/default-dirs.js';
 import { indexDoctorWrite, removeDoctorCard } from '../../eval-core/artifact-index.js';
-import { doctorReportFileStem, isReportFileName, reportFilePath } from '../../eval-core/artifact-file-names.js';
+import { doctorReportFileStem, isReportFileName, reportFilePath, reportFileStem } from '../../eval-core/artifact-file-names.js';
 import { migrateLegacyReportFiles } from '../../eval-core/report-file-migration.js';
 import { projectDoctorsDir, globalDoctorsDir } from '../../eval-core/measurement-dirs.js';
 import { persistDoctorGraphSidecars, removeDoctorGraphSidecars } from '../../artifact-graph/doctor.js';
+import { parseDoctorReport } from '../../shared/doctor-report.js';
+import { writeJsonFileAtomic } from '../../shared/atomic-json.js';
 export default class Doctor extends BaseCommand {
     static description = bilingual({
         zh: '体检 omk 工作目录：先跑静态规则，再对 skill 做多维度 LLM 健康度审计（默认 --repeat 2 采样 + 共识归并）。',
@@ -75,14 +78,14 @@ export default class Doctor extends BaseCommand {
         }),
         executor: Flags.string({
             description: bilingual({
-                zh: '执行器名，默认 claude。指定为测试 fixture 路径可在测试里跑（同 omk doctor）。',
-                en: 'Executor name, default claude. Pass a test fixture path to use in tests.',
+                zh: '执行器名。Codex 任务内自动用 codex；也可用 OMK_EXECUTOR 设置环境偏好。指定为测试 fixture 路径可在测试里跑。',
+                en: 'Executor name. Defaults to codex inside Codex tasks; OMK_EXECUTOR sets an environment preference. A test fixture path is also accepted in tests.',
             }),
         }),
         model: Flags.string({
             description: bilingual({
-                zh: 'LLM model 名，默认 sonnet。',
-                en: 'LLM model name, default sonnet.',
+                zh: 'LLM model 名。Codex 自动读取本机配置；也可用 OMK_MODEL 设置环境偏好。',
+                en: 'LLM model name. Codex reads the local configured model; OMK_MODEL sets an environment preference.',
             }),
         }),
         timeout: Flags.string({
@@ -151,8 +154,15 @@ export default class Doctor extends BaseCommand {
         const lang = this.lang;
         await this.runWithCliExit(async () => {
             const target = args.target ?? null;
-            const executorName = flags.executor ?? 'claude';
-            const model = flags.model ?? 'sonnet';
+            const staticOnly = flags['static-only'];
+            const runtime = staticOnly
+                ? {
+                    executor: resolveCliExecutor(flags.executor),
+                    model: flags.model ?? 'static-only',
+                }
+                : resolveRuntimeSelection({ executor: flags.executor, model: flags.model }, { lang });
+            const executorName = runtime.executor;
+            const model = runtime.model;
             // omk doctor 默认 = 静态规则 + LLM 健康度审计(7 内置维度 + 用户注册的自定义维度);
             // --static-only = 只跑静态检测(readable / metadata / 正文依赖,不调 LLM、不读 samples)。
             // samples_contract_aligned 仍只归 eval preflight(它要 samples.json,与离线解耦)。
@@ -184,7 +194,6 @@ export default class Doctor extends BaseCommand {
             // 默认:静态规则 + 在线检查(LLM health composer + endpoint 自定义维度 external=true)。
             // --static-only:只跑静态检测(纯静态内置 rule),但排除 samples_contract_aligned
             // (那条要 samples.json,与离线解耦) → 且不加载 samples,依赖检查只扫 skill 正文。
-            const staticOnly = flags['static-only'];
             const isOnline = (r) => isComposerRule(r) || r.external === true;
             const rulesOverride = staticOnly
                 ? getRegisteredRules().filter((r) => !isOnline(r) && r.id !== 'samples_contract_aligned')
@@ -298,7 +307,10 @@ function persistDoctorReport(report, outputDir, lang = 'zh') {
         };
         const cardId = doctorReportFileStem(skill.skillName, report.id);
         const filePath = reportFilePath(dir, cardId);
-        writeFileSync(filePath, JSON.stringify(perSkill, null, 2), 'utf8');
+        const parsed = parseDoctorReport(perSkill);
+        if (!parsed)
+            throw new Error('invalid doctor report');
+        writeJsonFileAtomic(filePath, parsed);
         // 产物发现索引:per-skill 报告落项目本地后,best-effort 追加全局轻卡片,让 studio 跨项目聚合。
         indexDoctorWrite({
             id: cardId, path: filePath, skillName: skill.skillName, reportId: report.id, timestamp: report.timestamp,
@@ -328,19 +340,24 @@ function persistDoctorReport(report, outputDir, lang = 'zh') {
 // 按 timestamp 倒排,保留 maxKeep 份最近的,其余删。按 content 匹配 skillName 不
 // 看文件名,所以清理逻辑不依赖 readdir 顺序或 stem 推断 skill 名。
 export function pruneDoctorHistory(dir, skillName, maxKeep) {
+    if (!Number.isSafeInteger(maxKeep) || maxKeep < 0) {
+        throw new TypeError('maxKeep must be a non-negative safe integer');
+    }
     migrateLegacyReportFiles(dir, 'doctor');
     const candidates = [];
     for (const file of readdirSync(dir)) {
         if (!isReportFileName(file))
             continue;
         try {
-            const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
-            const kind = data?.kind === 'doctor' ? data.kind : null;
-            if (!kind || !Array.isArray(data.skills) || data.skills.length !== 1)
+            const data = parseDoctorReport(JSON.parse(readFileSync(join(dir, file), 'utf-8')));
+            if (!data || data.skills.length !== 1)
                 continue;
             if (data.skills[0].skillName !== skillName)
                 continue;
-            candidates.push({ file, graphStem: doctorReportFileStem(skillName, data.id), timestamp: data.timestamp });
+            const expectedStem = doctorReportFileStem(skillName, data.id);
+            if (reportFileStem(file) !== expectedStem)
+                continue;
+            candidates.push({ file, graphStem: expectedStem, timestamp: data.timestamp });
         }
         catch { /* skip corrupt / unrelated json */ }
     }

package/dist/cli/commands/eval/index.d.ts

@@ -1,4 +1,7 @@
 import { BaseCommand } from '../../oclif/base-command.js';
+import { type CliLang } from '../../lib/i18n.js';
+import { type RunConfig } from '../../lib/parse-run-config.js';
+export declare function formatConnectivityFailureHint(message: string, config: Pick<RunConfig, 'executorName' | 'model' | 'judgeModels' | 'noJudge'>, lang: CliLang, env?: NodeJS.ProcessEnv): string;
 export default class Eval extends BaseCommand {
     static description: string;
     static examples: {

package/dist/cli/commands/eval/index.js

@@ -1,3 +1,5 @@
+import { existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
 import { Flags } from '@oclif/core';
 import { LANG_FLAG, bilingual } from '../../oclif/i18n.js';
 import { BaseCommand } from '../../oclif/base-command.js';
@@ -7,10 +9,17 @@ import { tCli } from '../../lib/i18n.js';
 import { parseRunConfig } from '../../lib/parse-run-config.js';
 import { makeOnProgress } from '../../lib/progress.js';
 import { computeRunTally } from '../../lib/run-tally.js';
+import { codexModelFlagValue, codexModelHint } from '../../lib/codex-model-hint.js';
+import { looksLikeModelUnavailableFailure } from '../../lib/llm-failure-classifier.js';
 import { DEFAULT_BOOTSTRAP_SAMPLES } from '../../../eval-core/bootstrap.js';
 import { DEFAULT_GATE_THRESHOLD } from '../../../eval-core/verdict.js';
 import { EVALUATION_REPORT_SCHEMA_VERSION } from '../../../eval-core/evaluation-reporting.js';
 import { findSingleTreatmentDeprecatedSamplesHint, hasUsableSamplesPath, } from '../../../inputs/sample-locator.js';
+import { shellQuoteArg } from '../../../shared/shell-quote.js';
+const CLAUDE_EXECUTORS = new Set(['claude', 'claude-sdk']);
+const CODEX_EXECUTORS = new Set(['codex', 'codex-sdk']);
+const OPENAI_API_EXECUTORS = new Set(['openai-api']);
+const ANTHROPIC_API_EXECUTORS = new Set(['anthropic-api']);
 function isDryRunReport(report) {
     return Boolean(report && typeof report === 'object' && report.dryRun === true);
 }
@@ -42,6 +51,25 @@ function applyGateExitCode(code, values, lang) {
     process.stderr.write(tCli('cli.run.report_only_gate_skipped', lang));
     return 0;
 }
+function userFacingPath(path) {
+    const rel = relative(process.cwd(), path);
+    if (rel && rel !== '..' && !rel.startsWith(`..${sep}`))
+        return rel;
+    return path;
+}
+function sampleCommandForSingleTreatment(treatment, skillDir) {
+    if (existsSync(treatment))
+        return `omk sample ${shellQuoteArg(treatment)}`;
+    const dirSkillPath = join(skillDir, treatment);
+    if (existsSync(join(dirSkillPath, 'SKILL.md'))) {
+        return `omk sample ${shellQuoteArg(userFacingPath(dirSkillPath))}`;
+    }
+    const flatSkillPath = join(skillDir, `${treatment}.md`);
+    if (existsSync(flatSkillPath)) {
+        return `omk sample ${shellQuoteArg(userFacingPath(flatSkillPath))}`;
+    }
+    return null;
+}
 /**
  * 完整 report JSON 是**机器输出**:重定向 / 管道(`omk eval > r.json`、`| jq`)时吐到 stdout 供下游消费。
  * 交互式 TTY 下报告已存盘、(默认)还起了 report server,再刷上千行 JSON 只会把 verdict 淹没在屏幕外 ——
@@ -62,11 +90,118 @@ function emitVerdictText(text) {
     const stream = process.stdout.isTTY ? process.stdout : process.stderr;
     stream.write(text + '\n');
 }
+function preflightFailedTarget(message) {
+    return message.match(/(^|\n)preflight failed \[([^\]]+)\]:/)?.[2] ?? null;
+}
+function runtimeKey(executor, model) {
+    return `${executor}:${model}`;
+}
+function matchesPreflightTarget(target, executor, model) {
+    return target.includes(':') ? target === runtimeKey(executor, model) : target === model;
+}
+function matchingPreflightRuntimes(config, failedTarget) {
+    const matches = [];
+    if (config.executorName && matchesPreflightTarget(failedTarget, config.executorName, config.model ?? '')) {
+        matches.push({ executor: config.executorName, role: 'task' });
+    }
+    if (!config.noJudge) {
+        for (const judge of config.judgeModels) {
+            if (matchesPreflightTarget(failedTarget, judge.executor, judge.model))
+                matches.push({ executor: judge.executor, role: 'judge' });
+        }
+    }
+    return matches;
+}
+function hasExecutor(matches, executors) {
+    return matches.some((match) => executors.has(match.executor));
+}
+function configHasExecutor(config, executors) {
+    if (config.executorName && executors.has(config.executorName))
+        return true;
+    return !config.noJudge && config.judgeModels.some((judge) => executors.has(judge.executor));
+}
+function shouldSwitchJudgeWithTask(config, executors) {
+    return !config.noJudge && config.judgeModels.length === 1 && executors.has(config.judgeModels[0].executor);
+}
+function fallbackFlags(matches, executor, taskModel, judgeModel, includeJudgeWithTask) {
+    const hasTask = matches.some((match) => match.role === 'task');
+    const hasJudge = matches.some((match) => match.role === 'judge') || (hasTask && includeJudgeWithTask);
+    return [
+        hasTask ? `--executor ${executor} --model ${taskModel}` : '',
+        hasJudge ? `--judge-models ${executor}:${judgeModel}` : '',
+    ].filter(Boolean).join(' ');
+}
+export function formatConnectivityFailureHint(message, config, lang, env = process.env) {
+    const failedTarget = preflightFailedTarget(message);
+    if (failedTarget) {
+        const matches = matchingPreflightRuntimes(config, failedTarget);
+        if (matches.length === 0)
+            return '';
+        if (hasExecutor(matches, CLAUDE_EXECUTORS)) {
+            const codexModel = codexModelFlagValue(env);
+            return tCli('cli.run.codex_fallback_hint', lang, {
+                flags: fallbackFlags(matches, 'codex', codexModel, codexModel, shouldSwitchJudgeWithTask(config, CLAUDE_EXECUTORS)),
+                codexModelHint: codexModelHint(lang, env),
+            });
+        }
+        if (hasExecutor(matches, CODEX_EXECUTORS)) {
+            if (looksLikeModelUnavailableFailure(message)) {
+                const codexModel = codexModelFlagValue(env);
+                return tCli('cli.run.codex_model_hint', lang, {
+                    codexFlags: fallbackFlags(matches, 'codex', codexModel, codexModel, shouldSwitchJudgeWithTask(config, CODEX_EXECUTORS)),
+                    codexExec: `codex exec -m ${codexModel} "hi"`,
+                    claudeFlags: fallbackFlags(matches, 'claude', 'sonnet', 'haiku', shouldSwitchJudgeWithTask(config, CODEX_EXECUTORS)),
+                    openaiFlags: fallbackFlags(matches, 'openai-api', '<openai-model>', '<openai-model>', shouldSwitchJudgeWithTask(config, CODEX_EXECUTORS)),
+                    codexModelHint: codexModelHint(lang, env),
+                });
+            }
+            return tCli('cli.run.codex_auth_hint', lang, {
+                claudeFlags: fallbackFlags(matches, 'claude', 'sonnet', 'haiku', shouldSwitchJudgeWithTask(config, CODEX_EXECUTORS)),
+                openaiFlags: fallbackFlags(matches, 'openai-api', '<openai-model>', '<openai-model>', shouldSwitchJudgeWithTask(config, CODEX_EXECUTORS)),
+            });
+        }
+        if (hasExecutor(matches, OPENAI_API_EXECUTORS)) {
+            return tCli(looksLikeModelUnavailableFailure(message) ? 'cli.run.openai_api_model_hint' : 'cli.run.openai_api_auth_hint', lang);
+        }
+        if (hasExecutor(matches, ANTHROPIC_API_EXECUTORS)) {
+            return tCli(looksLikeModelUnavailableFailure(message) ? 'cli.run.anthropic_api_model_hint' : 'cli.run.anthropic_api_auth_hint', lang);
+        }
+        return '';
+    }
+    if (message.includes('OPENAI_API_KEY') && configHasExecutor(config, OPENAI_API_EXECUTORS))
+        return tCli('cli.run.openai_api_auth_hint', lang);
+    if (message.includes('ANTHROPIC_API_KEY') && configHasExecutor(config, ANTHROPIC_API_EXECUTORS))
+        return tCli('cli.run.anthropic_api_auth_hint', lang);
+    return '';
+}
+function treatmentVariantFromVerdict(result) {
+    if (result.representative?.treatment)
+        return result.representative.treatment;
+    if (result.level === 'SOLO')
+        return result.variants[0];
+    return result.variants[1];
+}
+function promoteTargetFromEvidence(result, records) {
+    const treatment = treatmentVariantFromVerdict(result);
+    const matched = treatment ? records.filter((r) => r.variant === treatment) : records;
+    const names = new Set(matched.filter((r) => r.bound).map((r) => r.name));
+    return names.size === 1 ? [...names][0] : undefined;
+}
+function emitRecordedEvidence(records, lang, verdict) {
+    for (const w of records) {
+        const command = `omk promote ${shellQuoteArg(w.name)}`;
+        const key = w.bound && verdict === 'PROGRESS'
+            ? 'cli.run.evidence_recorded_promotable'
+            : (w.bound ? 'cli.run.evidence_recorded' : 'cli.run.evidence_recorded_unbound');
+        process.stderr.write(tCli(key, lang, { name: w.name, command }));
+    }
+}
 async function emitEvaluationVerdict(report, values, lang) {
     const { computeVerdict, formatVerdictText } = await import('../../../eval-core/verdict.js');
     const result = computeVerdict(report, verdictOptions(values));
-    emitVerdictText(formatVerdictText(result, { verbose: true, lang }));
-    await recordEvidenceSafely(report, result.level, values, lang);
+    const written = await recordEvidenceSafely(report, result.level, values);
+    emitVerdictText(formatVerdictText(result, { verbose: true, lang, promoteTarget: promoteTargetFromEvidence(result, written) }));
+    emitRecordedEvidence(written, lang, result.level);
     return verdictPasses(result.level, result.headline) ? 0 : 1;
 }
 /**
@@ -74,18 +209,16 @@ async function emitEvaluationVerdict(report, values, lang) {
  * 永不致命:管理是 eval 的旁路,写入失败 / 无匹配记录都不影响 verdict 与 exit code。
  * `--no-evidence` 关闭。仅对实际写入的记录打一行提示(无匹配则全静默)。
  */
-async function recordEvidenceSafely(report, verdict, values, lang) {
+async function recordEvidenceSafely(report, verdict, values) {
     if (values['no-evidence'] === true)
-        return;
+        return [];
     try {
         const { recordEvalEvidence } = await import('../../../managed/index.js');
-        const written = recordEvalEvidence(report, verdict, new Date().toISOString());
-        for (const w of written) {
-            process.stderr.write(tCli(w.bound ? 'cli.run.evidence_recorded' : 'cli.run.evidence_recorded_unbound', lang, { name: w.name }));
-        }
+        return recordEvalEvidence(report, verdict, new Date().toISOString());
     }
     catch {
         // 证据写入是旁路,任何异常都不该让评测失败
+        return [];
     }
 }
 function batchItemFallbackReport(batch, item) {
@@ -137,7 +270,7 @@ async function emitBatchVerdict(report, reportsDir, values, lang) {
     // batch 每个子报告各自是一份独立 skill 的评测 → 各自写证据。
     for (const child of childReports) {
         const v = results.find((r) => r.id === child.id)?.verdict.level ?? 'SOLO';
-        await recordEvidenceSafely(child, v, values, lang);
+        emitRecordedEvidence(await recordEvidenceSafely(child, v, values), lang, v);
     }
     const passed = results.filter((r) => verdictPasses(r.verdict.level, r.verdict.headline)).length;
     const failed = results.length - passed;
@@ -188,7 +321,7 @@ async function announceSavedReport({ report, filePath, reportsDir, values, lang,
     }
 }
 async function runEval(_args, flags, lang) {
-    const { values, config, evalConfig } = parseRunConfig({ ...flags });
+    const { values, config, evalConfig } = parseRunConfig({ ...flags }, { lang });
     if (!values.batch && !hasUsableSamplesPath(config.samplesPath)) {
         const treatmentRaw = typeof values.treatment === 'string' ? values.treatment : '';
         const treatments = treatmentRaw.split(',').map((v) => v.trim()).filter(Boolean);
@@ -201,8 +334,15 @@ async function runEval(_args, flags, lang) {
                 newPath: deprecatedSamplesHint.newPath,
             }));
         }
+        const sampleCommand = !deprecatedSamplesHint && !values.samples && !evalConfig?.samples && treatments.length === 1
+            ? sampleCommandForSingleTreatment(treatments[0], config.skillDir)
+            : null;
+        const missingSamplesMessage = [
+            tCli('cli.common.samples_not_found', lang, { path: config.samplesPath }),
+            sampleCommand ? tCli('cli.common.samples_not_found_hint', lang, { command: sampleCommand }) : '',
+        ].filter(Boolean).join('\n');
         console.error(tCli('cli.common.error_prefix', lang, {
-            message: tCli('cli.common.samples_not_found', lang, { path: config.samplesPath }),
+            message: missingSamplesMessage,
         }));
         throw new CliExit(1);
     }
@@ -349,7 +489,10 @@ async function runEval(_args, flags, lang) {
     catch (err) {
         if (err instanceof CliExit)
             throw err;
-        console.error(tCli('cli.common.error_prefix', lang, { message: err.message }));
+        const message = err.message;
+        console.error(tCli('cli.common.error_prefix', lang, {
+            message: `${message}${formatConnectivityFailureHint(message, config, lang)}`,
+        }));
         throw new CliExit(1);
     }
 }
@@ -416,14 +559,14 @@ export default class Eval extends BaseCommand {
         }),
         executor: Flags.string({
             description: bilingual({
-                zh: '执行器:claude / claude-sdk / codex / codex-sdk / openai-api / gemini / 自定义命令（默认 claude）。',
-                en: 'Executor: claude / claude-sdk / codex / codex-sdk / openai-api / gemini / custom (default claude).',
+                zh: '执行器：claude / claude-sdk / codex / codex-sdk / openai-api / gemini / 自定义命令。Codex 任务内自动用 codex；也可用 OMK_EXECUTOR 设置环境偏好。',
+                en: 'Executor: claude / claude-sdk / codex / codex-sdk / openai-api / gemini / custom. Defaults to codex inside Codex tasks; OMK_EXECUTOR sets an environment preference.',
             }),
         }),
         'judge-models': Flags.string({
             description: bilingual({
-                zh: '评委配置，格式 executor:model[,...]，例 claude:haiku 或 claude:opus,openai-api:gpt-4o(≥ 2 个 = ensemble）。默认 <executor>:haiku。',
-                en: 'Judge config: executor:model[,...]. e.g. claude:haiku or claude:opus,openai-api:gpt-4o (≥ 2 = ensemble). Default <executor>:haiku.',
+                zh: '评委配置，格式 executor:model[,...]，例 claude:haiku 或 codex:<model>（≥ 2 个 = ensemble）。默认跟随所选执行器；Codex 沿用被测模型。',
+                en: 'Judge config: executor:model[,...], e.g. claude:haiku or codex:<model> (≥ 2 = ensemble). Defaults to the selected executor; Codex reuses the evaluated model.',
             }),
         }),
         'output-dir': Flags.string({
@@ -482,7 +625,10 @@ export default class Eval extends BaseCommand {
             parse: integerStringParser('--retry', { min: 0 }),
         }),
         resume: Flags.string({
-            description: bilingual({ zh: '从某次失败 run 续跑', en: 'Resume a previous failed run' }),
+            description: bilingual({
+                zh: '从契约兼容的报告恢复成功项；不兼容则从头运行',
+                en: 'Reuse successful entries from a contract-compatible report; otherwise start over',
+            }),
         }),
         'layered-stats': Flags.boolean({
             description: bilingual({ zh: '输出分层统计', en: 'Emit layered stats' }),