@genee/omp-opsx-addon 0.7.0 → 0.9.0

package/lib/unified-config.ts

@@ -2,11 +2,12 @@
  * Unified opsx config schema.
  *
  * `opsx.yml` (per project at `<cwd>/.omp/opsx.yml`, layered on top of
- * `~/.omp/agent/opsx.yml`) declares how each role is dispatched. Since
- * `acpx` was removed, every role is local — values describe the *model*
- * the role should run on, not an external agent to spawn.
+ * `~/.omp/agent/opsx.yml`) declares how each dispatch agent (coder /
+ * reviewer / planner / proposal-reviewer) is dispatched. Since `acpx` was
+ * removed, every agent is local — values describe the *model* the agent
+ * should run on, not an external agent to spawn.
  *
- * Accepted values for each role:
+ * Accepted values for each dispatch agent:
  *   - `'auto'` — let the model-selector pick based on tier + usage.
  *   - An OMP role alias: `default`, `smol`, `slow`, `vision`, `plan`,
  *     `designer`, `commit`, `tiny`, `task`, `advisor` — expanded by the
@@ -16,15 +17,28 @@
  *     `openai-codex/gpt-5-codex`.
  *
  * Top-level fields:
- *   - `model_allowlist`: list of `provider/model` glob patterns — restricts
- *     which models the auto-selector may pick from.
- *   - `tiers`: list of `{ pattern, tier }` overrides for tier scoring.
- *   - `role_tiers`: `role → tier_name` map overriding the default expected
- *     tier (DEFAULT_ROLE_TIER in model-tiers) for the four opsx agents.
+ *   - `agents`: `{ coder?, reviewer?, planner?, 'proposal-reviewer'? }` map
+ *     of dispatch agent → value from the grammar above. Canonical form.
+ *   - `agent_tiers`: dispatch agent → tier_name map overriding the default
+ *     expected tier (DEFAULT_ROLE_TIER in model-tiers) for the four opsx
+ *     agents. Canonical form.
+ *   - Legacy keys `coder` / `reviewer` / `planner` / `proposal-reviewer`
+ *     (top-level values) and `role_tiers`: same semantics as their
+ *     replacements, still honored; each layer file using them gets one
+ *     aggregated warning per config read. Scheduled for removal after one
+ *     release cycle; within one file the new keys win.
  *   - `model_role_tiers`: `omp_role → tier_name | 'skip'` map controlling
  *     which selector tier each OMP model role (default/smol/slow/vision/plan/
  *     designer/commit/tiny/task/advisor + custom roles) follows after
  *     /pick-model; `skip` excludes the role from the session overlay.
+ *     Disambiguation: those are the OMP host *model roles*, not the four
+ *     opsx dispatch agents configured via `agents` / `agent_tiers`.
+ *   - `model_allowlist`: list of `provider/model` glob patterns — restricts
+ *     which models the auto-selector may pick from.
+ *   - `tiers`: list of `{ pattern, tier }` overrides for tier scoring.
+ *   - `concurrency_*`: adaptive per-provider concurrency tuner (see
+ *     `CONCURRENCY_DEFAULTS` and the `provider-concurrency-control` spec).
+ *     Flat snake_case keys with per-key fallback + warn — never throws.
  */
 
 import { existsSync, readFileSync } from 'fs';
@@ -32,6 +46,11 @@ import { homedir } from 'os';
 import { join } from 'path';
 import { YAML } from 'bun';
 import { TIER_NAMES, type TierName, type TierOverride } from './model-tiers.js';
+import { canonicalizeProvider } from './usage-resolver.js';
+import { DEFAULT_MIN_SAMPLES, SPEED_MODES, type SpeedAwareConfig, type SpeedMode } from './model-speed.js';
+import { QUALITY_PREFERENCES, type QualityPreference, type RoutingConfig } from './complexity-router.js';
+import { DEFAULT_THRESHOLD, DEFAULT_WINDOW, type StallEscalationConfig } from './stall-detector.js';
+import { DEFAULT_WEIGHT, type ContinuityGuardConfig } from './continuity-guard.js';
 
 /** OMP-documented role aliases. Plugins MAY pass these to `task(..., model: '@alias')`. */
 export const OMP_ROLE_ALIASES = new Set<string>([
@@ -54,24 +73,58 @@ export const AUTO_TOKEN = 'auto';
 export const OPSX_ROLES = ['coder', 'reviewer', 'planner', 'proposal-reviewer'] as const;
 export type OpsxRole = (typeof OPSX_ROLES)[number];
 
+/** Keys superseded by `agents` / `agent_tiers`; still honored, warned on read. */
+const LEGACY_AGENT_KEYS: readonly (OpsxRole | 'role_tiers')[] = [...OPSX_ROLES, 'role_tiers'];
+
 /** Raw YAML shape — every key is optional. */
 export interface OpsxYamlShape {
+    /** @deprecated Legacy of `agents.coder` — still honored; warned per layer file; removal after one release cycle. */
     coder?: string;
+    /** @deprecated Legacy of `agents.reviewer` — still honored; warned per layer file; removal after one release cycle. */
     reviewer?: string;
+    /** @deprecated Legacy of `agents.planner` — still honored; warned per layer file; removal after one release cycle. */
     planner?: string;
+    /** @deprecated Legacy of `agents['proposal-reviewer']` — still honored; warned per layer file; removal after one release cycle. */
     'proposal-reviewer'?: string;
+    /** Dispatch agent → value; canonical replacement for the legacy top-level role keys. */
+    agents?: Partial<Record<OpsxRole, string>>;
     primary?: string;
     model_allowlist?: string[];
     tiers?: TierOverride[];
+    /** @deprecated Legacy name of `agent_tiers` (same schema) — still honored; warned per layer file; removal after one release cycle. */
     role_tiers?: Partial<Record<OpsxRole, TierName>>;
+    /** Dispatch agent → tier override for the four opsx agents. */
+    agent_tiers?: Partial<Record<OpsxRole, TierName>>;
     /** OMP model role → tier override; `skip` excludes the role from the overlay. Keys are arbitrary strings (custom roles allowed). */
     model_role_tiers?: Record<string, string>;
     plan_providers?: string[];
+    /** Providers removed from the effective plan set: (defaults ∪ plan_providers) − plan_providers_remove. */
+    plan_providers_remove?: string[];
+    /** false collapses the PAYG-last coverage partition (pay-as-you-go candidates compete normally). Default true. */
+    payg_last_resort?: boolean;
+    /** china 家族缺省排除 + 同账号区域变体偏好方向（true = 国内语境：排除 gpt/claude/openai/anthropic 家族、区域变体保留国内入口）。缺省 false。 */
+    china?: boolean;
     probe_enabled?: boolean;
     probe_timeout_ms?: number;
     probe_http_enabled?: boolean;
     probe_ttl_ms?: number;
     excluded_providers?: string[];
+    /** provider → 服务端路由哨兵模型 id（如 `ark-coding-plan: ark-code-latest`）。键经 canonicalizeProvider 规范化。 */
+    provider_auto?: Record<string, string>;
+    /** provider → 哨兵声明档位（tiny|low|mid|high|top）；非法值 warn 丢弃，未声明按 mid。 */
+    provider_auto_tiers?: Record<string, string>;
+    /** provider → 模式数组：列出的 provider 收窄到命中模型，未列出不受限。 */
+    provider_models?: Record<string, string[]>;
+    /** 速度感知选择：enabled（缺省 true）、mode（tie-break|aggressive，缺省 tie-break）、min_samples（缺省 20）。 */
+    speed_aware?: { enabled?: boolean; mode?: string; min_samples?: number };
+    /** 难度路由（W4）：prompt 分类 → 写入集 tier 目标偏移。缺省 false。 */
+    difficulty_routing?: { enabled?: boolean };
+    /** stall 升档（W4）：同签名滑窗重复 → default 目标 +1。缺省 false / 6 / 3。 */
+    stall_escalation?: { enabled?: boolean; window?: number; threshold?: number };
+    /** 连续性守门（W4）：在选模型粘性。缺省 false / weight 0.6。 */
+    continuity_guard?: { enabled?: boolean; weight?: number };
+    /** 质量带旋钮（W4）：balanced | cost | quality。缺省 balanced（独立于路由开关）。 */
+    quality_preference?: string;
     status_probe_enabled?: boolean;
     redis_enabled?: boolean;
     redis_host?: string;
@@ -82,6 +135,24 @@ export interface OpsxYamlShape {
     redis_probe_interval_ms?: number;
     redis_unhealthy_retry_ms?: number;
     redis_ttl_ms?: number;
+    /** 会话启动自动应用一次选择（缺省 true）；false 时 session_start 不应用、不写覆盖，行为与本键引入前一致。 */
+    autoselect_on_start?: boolean;
+    concurrency_enabled?: boolean;
+    concurrency_floor?: number;
+    concurrency_ceiling?: number;
+    concurrency_start?: number;
+    concurrency_up_ms?: number;
+    concurrency_down_ms?: number;
+    concurrency_latency_k?: number;
+    concurrency_min_samples?: number;
+    concurrency_queue_wait_high_ms?: number;
+    concurrency_write_min_interval_ms?: number;
+    concurrency_lease_ttl_ms?: number;
+    concurrency_decay_after_ms?: number;
+    concurrency_eval_interval_ms?: number;
+    concurrency_queue_wait_window_ms?: number;
+    concurrency_providers?: string[];
+    concurrency_ceiling_by_provider?: Record<string, number>;
 }
 
 /** A role value as parsed. */
@@ -100,6 +171,28 @@ export interface ResolvedOpsxConfig {
     ompRoleTiers: Record<string, TierName | 'skip'>;
     /** Provider ids that have monthly plan subscriptions. */
     planProviders: string[];
+    /** Canonical provider ids removed from the effective plan set. */
+    planProvidersRemove: string[];
+    /** PAYG candidates sort last (coverage partition). false collapses the partition. Default true. */
+    paygLastResort: boolean;
+    /** Standing china family exclusion + regional-variant preference direction. Default false (= status quo). */
+    china: boolean;
+    /** provider → 服务端路由哨兵模型 id（键已 canonicalizeProvider 规范化）。空对象 = 无哨兵。 */
+    providerAuto: Record<string, string>;
+    /** provider → 哨兵声明档位（值已过 TIER_NAMES 校验）。空对象 = 全部缺省 mid。 */
+    providerAutoTiers: Record<string, TierName>;
+    /** provider → 模式数组（键已规范化）：仅列出的 provider 被收窄，未列出不受限。 */
+    providerModels: Record<string, string[]>;
+    /** 速度感知选择三键（解析层已校验并补齐缺省；enabled=false 时装配层零读取）。 */
+    speedAware: SpeedAwareConfig;
+    /** W4 难度路由（缺省 false：结构改造 opt-in，W1-W3 收益不依赖它）。 */
+    difficultyRouting: RoutingConfig;
+    /** W4 stall 升档（缺省 false / window 6 / threshold 3）。 */
+    stallEscalation: StallEscalationConfig;
+    /** W4 连续性守门（缺省 false / weight 0.6）。 */
+    continuityGuard: ContinuityGuardConfig;
+    /** W4 质量带旋钮（缺省 balanced = 既有比较器分支逐字节）。 */
+    qualityPreference: QualityPreference;
     warnings: string[];
     /** 是否开启可达性探测，默认 true */
     probe_enabled: boolean;
@@ -131,6 +224,49 @@ export interface ResolvedOpsxConfig {
     redis_unhealthy_retry_ms: number;
     /** Redis key TTL ms（默认 180000）。 */
     redis_ttl_ms: number;
+    /** 会话启动自动应用一次选择，默认 true；false 时 session_start handler 直接返回（不 setModel、不写覆盖）。 */
+    autoselectOnStart: boolean;
+    /** 是否开启自适应并发控制，默认 true；false 时装配层不创建控制器（零写入）。 */
+    concurrency_enabled: boolean;
+    /**
+     * 全局并发上限下界，默认 4（须为 ≥ 1 的整数）。每个 provider 的**有效下限**
+     * 为 `min(concurrency_floor, initial)`（见 concurrency-tuner 的
+     * `effectiveFloor` / `createProviderState`）：该值设定区间，MUST NOT 抬高
+     * provider 自身的静态现值（静态 3 的 provider 下限与起点都保持 3）。
+     */
+    concurrency_floor: number;
+    /**
+     * 全局并发上限上界，默认 16。低于**有效 floor** 时：floor 未有效显式配置
+     * （缺省或非法回落）则把 floor 压到该 ceiling（区间退化为单点），否则回落
+     * 默认（ceiling → 16，必要时 floor 也回落默认）；见 `parseOpsxConfig`。
+     */
+    concurrency_ceiling: number;
+    /** 无现有静态值时的保守启动值，默认 4（区间 clamp 由控制器负责）。 */
+    concurrency_start: number;
+    /** 加性上调所需干净窗口时长 ms，默认 30000。 */
+    concurrency_up_ms: number;
+    /** 乘性下调后的冷却时长 ms，默认 60000。 */
+    concurrency_down_ms: number;
+    /** 延迟膨胀判定比值，默认 2（> 1 的任意正数，允许小数）。 */
+    concurrency_latency_k: number;
+    /** 延迟判定所需最小样本数，默认 5。 */
+    concurrency_min_samples: number;
+    /** 排队等待 p50 高企阈值 ms，默认 2000（超阈值禁止上调）。 */
+    concurrency_queue_wait_high_ms: number;
+    /** 同一 provider 两次成功写入的最小间隔 ms，默认 20000。 */
+    concurrency_write_min_interval_ms: number;
+    /** 租约 TTL ms，默认 60000。 */
+    concurrency_lease_ttl_ms: number;
+    /** 无观测衰减周期 ms，默认 86400000（24h）。 */
+    concurrency_decay_after_ms: number;
+    /** 评估节拍 ms，默认 30000。 */
+    concurrency_eval_interval_ms: number;
+    /** 排队等待护栏统计窗口 ms，默认 60000（独立于评估节拍）。 */
+    concurrency_queue_wait_window_ms: number;
+    /** 显式希望由控制器试探上限的 provider（规范化 id，去重、声明顺序）。 */
+    concurrency_providers: string[];
+    /** per-provider ceiling 覆盖（键已规范化，值为 ≥ floor 的正整数）。 */
+    concurrency_ceiling_by_provider: Record<string, number>;
 }
 
 /** Default values applied when no config is provided. */
@@ -202,9 +338,14 @@ export function parseTierOverrides(
     return out;
 }
 
-/** Validate role_tiers entries. */
+/**
+ * Validate tier entries for the four opsx agents. `keyLabel` names the config
+ * key being parsed (`agent_tiers`, or legacy `role_tiers`) so warnings point
+ * at the key the user actually wrote.
+ */
 export function parseRoleTiers(
     raw: unknown,
+    keyLabel: 'agent_tiers' | 'role_tiers',
     warn: (msg: string) => void,
 ): Partial<Record<OpsxRole, TierName>> {
     if (!raw || typeof raw !== 'object') return {};
@@ -213,11 +354,11 @@ export function parseRoleTiers(
         const v = (raw as Record<string, unknown>)[role];
         if (v === undefined || v === null) continue;
         if (typeof v !== 'string') {
-            warn(`[omp-opsx-addon] role_tiers.${role}: expected tier name, got ${typeof v}`);
+            warn(`[omp-opsx-addon] ${keyLabel}.${role}: expected tier name, got ${typeof v}`);
             continue;
         }
         if (!TIER_NAMES.includes(v as TierName)) {
-            warn(`[omp-opsx-addon] role_tiers.${role}: unknown tier "${v}" (use one of ${TIER_NAMES.join('/')})`);
+            warn(`[omp-opsx-addon] ${keyLabel}.${role}: unknown tier "${v}" (use one of ${TIER_NAMES.join('/')})`);
             continue;
         }
         out[role] = v as TierName;
@@ -306,6 +447,375 @@ export function parseStringArray(raw: unknown, key: string, warn: (msg: string)
     return out;
 }
 
+/**
+ * `concurrency_*` 默认值 —— 逐键对应 spec `provider-concurrency-control`
+ * 的「配置面与降级」Requirement（不要按 tasks 里的数字出现顺序推断）。
+ */
+export const CONCURRENCY_DEFAULTS = {
+    enabled: true,
+    floor: 4,
+    ceiling: 16,
+    start: 4,
+    up_ms: 30_000,
+    down_ms: 60_000,
+    latency_k: 2,
+    min_samples: 5,
+    queue_wait_high_ms: 2_000,
+    write_min_interval_ms: 20_000,
+    lease_ttl_ms: 60_000,
+    decay_after_ms: 86_400_000,
+    eval_interval_ms: 30_000,
+    queue_wait_window_ms: 60_000,
+} as const;
+
+/** 解析正数（允许小数，用于 `concurrency_latency_k` 这类比值）：非法则返回 defaultValue 并 warn。 */
+export function parsePositiveNumber(raw: unknown, key: string, defaultValue: number, warn: (msg: string) => void): number {
+    if (raw === undefined || raw === null) return defaultValue;
+    if (typeof raw === 'number' && Number.isFinite(raw) && raw > 0) return raw;
+    warn(`[omp-opsx-addon] ${key}: expected positive number, got ${JSON.stringify(raw)}`);
+    return defaultValue;
+}
+
+/** 规范化 provider id 列表：canonicalize + 去重，保持声明顺序；非字符串/空串跳过并 warn。 */
+function canonicalizeProviderList(raw: readonly unknown[], key: string, warn: (msg: string) => void): string[] {
+    const out: string[] = [];
+    const seen = new Set<string>();
+    for (const entry of raw) {
+        if (typeof entry !== 'string') {
+            warn(`[omp-opsx-addon] ${key}: skipping non-string entry ${JSON.stringify(entry)}`);
+            continue;
+        }
+        const canonical = canonicalizeProvider(entry.trim());
+        if (!canonical) {
+            warn(`[omp-opsx-addon] ${key}: skipping empty provider id`);
+            continue;
+        }
+        if (!seen.has(canonical)) {
+            seen.add(canonical);
+            out.push(canonical);
+        }
+    }
+    return out;
+}
+
+/** 解析 `concurrency_providers`：非数组回落 [] 并 warn；条目规范化、去重。 */
+export function parseConcurrencyProviders(raw: unknown, warn: (msg: string) => void): string[] {
+    if (raw === undefined || raw === null) return [];
+    if (!Array.isArray(raw)) {
+        warn(`[omp-opsx-addon] concurrency_providers: expected array of provider ids, got ${JSON.stringify(raw)}`);
+        return [];
+    }
+    return canonicalizeProviderList(raw, 'concurrency_providers', warn);
+}
+
+/** 解析 `plan_providers` / `plan_providers_remove`：非数组回落 [] 并 warn；条目规范化、去重。 */
+function parsePlanProviderList(raw: unknown, key: string, warn: (msg: string) => void): string[] {
+    if (raw === undefined || raw === null) return [];
+    if (!Array.isArray(raw)) {
+        warn(`[omp-opsx-addon] ${key}: expected array of provider ids, got ${JSON.stringify(raw)}`);
+        return [];
+    }
+    return canonicalizeProviderList(raw, key, warn);
+}
+
+/**
+ * 解析 `concurrency_ceiling_by_provider`：键规范化（大小写 / `arkcodingplan` 别名同源），
+ * 值须为 ≥ 1 的正整数；非法条目跳过并 warn（回落到全局 `concurrency_ceiling`），
+ * 非对象回落 {} 并 warn。
+ *
+ * 低于全局 `floor` 的覆盖**保留**并 warn：它是用户对单个 provider 的显式收窄，
+ * 丢弃它会让该 provider 的 ceiling 回落到全局值（等于抬高用户设定）。控制器的
+ * `createProviderState` 会把该 provider 的有效下限压到 `min(floor, 静态现值,
+ * 该 ceiling)`，因此 `floor > ceiling` 的覆盖仍自洽（该 provider 固定在它的
+ * ceiling 上）。
+ */
+export function parseCeilingByProvider(
+    raw: unknown,
+    floor: number,
+    warn: (msg: string) => void,
+): Record<string, number> {
+    if (raw === undefined || raw === null) return {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        warn(`[omp-opsx-addon] concurrency_ceiling_by_provider: expected object mapping provider → ceiling, got ${JSON.stringify(raw)}`);
+        return {};
+    }
+    const out: Record<string, number> = {};
+    for (const [id, value] of Object.entries(raw as Record<string, unknown>)) {
+        const canonical = canonicalizeProvider(id.trim());
+        if (!canonical) {
+            warn('[omp-opsx-addon] concurrency_ceiling_by_provider: skipping empty provider id');
+            continue;
+        }
+        if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value) || value < 1) {
+            warn(`[omp-opsx-addon] concurrency_ceiling_by_provider.${id}: expected positive integer, got ${JSON.stringify(value)}`);
+            continue;
+        }
+        if (value < floor) {
+            warn(
+                `[omp-opsx-addon] concurrency_ceiling_by_provider.${id}: ${value} < concurrency_floor ${floor}; keeping the override（有效下限 = min(${value}, provider 静态现值)）`,
+            );
+        }
+        if (out[canonical] !== undefined && out[canonical] !== value) {
+            warn(`[omp-opsx-addon] concurrency_ceiling_by_provider.${id}: duplicate canonical id "${canonical}" (${out[canonical]} → ${value}); later key wins`);
+        }
+        out[canonical] = value;
+    }
+    return out;
+}
+
+/** 解析 `provider_auto`：键规范化（大小写 / 别名同源），键值均须字符串；非法条目跳过并 warn。 */
+export function parseProviderAuto(raw: unknown, warn: (msg: string) => void): Record<string, string> {
+    if (raw === undefined || raw === null) return {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        warn(`[omp-opsx-addon] provider_auto: expected object mapping provider → auto model id, got ${JSON.stringify(raw)}`);
+        return {};
+    }
+    const out: Record<string, string> = {};
+    for (const [id, value] of Object.entries(raw as Record<string, unknown>)) {
+        const canonical = canonicalizeProvider(id.trim());
+        if (!canonical) {
+            warn('[omp-opsx-addon] provider_auto: skipping empty provider id');
+            continue;
+        }
+        if (typeof value !== 'string' || !value.trim()) {
+            warn(`[omp-opsx-addon] provider_auto.${id}: expected model id string, got ${JSON.stringify(value)}`);
+            continue;
+        }
+        out[canonical] = value.trim();
+    }
+    return out;
+}
+
+/** 解析 `provider_auto_tiers`：键规范化，值经 TIER_NAMES 校验；非法值 warn 并丢弃（消费侧缺省 mid）。 */
+export function parseProviderAutoTiers(raw: unknown, warn: (msg: string) => void): Record<string, TierName> {
+    if (raw === undefined || raw === null) return {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        warn(`[omp-opsx-addon] provider_auto_tiers: expected object mapping provider → tier name, got ${JSON.stringify(raw)}`);
+        return {};
+    }
+    const out: Record<string, TierName> = {};
+    for (const [id, value] of Object.entries(raw as Record<string, unknown>)) {
+        const canonical = canonicalizeProvider(id.trim());
+        if (!canonical) {
+            warn('[omp-opsx-addon] provider_auto_tiers: skipping empty provider id');
+            continue;
+        }
+        if (typeof value !== 'string' || !(TIER_NAMES as readonly string[]).includes(value)) {
+            warn(`[omp-opsx-addon] provider_auto_tiers.${id}: expected one of ${TIER_NAMES.join('|')}, got ${JSON.stringify(value)}`);
+            continue;
+        }
+        out[canonical] = value as TierName;
+    }
+    return out;
+}
+
+/** 解析 `provider_models`：键规范化，值须为字符串数组（模式）；非数组整键 warn 丢弃，非字符串条目跳过并 warn。 */
+export function parseProviderModels(raw: unknown, warn: (msg: string) => void): Record<string, string[]> {
+    if (raw === undefined || raw === null) return {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        warn(`[omp-opsx-addon] provider_models: expected object mapping provider → pattern array, got ${JSON.stringify(raw)}`);
+        return {};
+    }
+    const out: Record<string, string[]> = {};
+    for (const [id, value] of Object.entries(raw as Record<string, unknown>)) {
+        const canonical = canonicalizeProvider(id.trim());
+        if (!canonical) {
+            warn('[omp-opsx-addon] provider_models: skipping empty provider id');
+            continue;
+        }
+        if (!Array.isArray(value)) {
+            warn(`[omp-opsx-addon] provider_models.${id}: expected array of patterns, got ${JSON.stringify(value)}`);
+            continue;
+        }
+        const patterns: string[] = [];
+        for (const entry of value) {
+            if (typeof entry !== 'string' || !entry.trim()) {
+                warn(`[omp-opsx-addon] provider_models.${id}: skipping non-string/empty pattern ${JSON.stringify(entry)}`);
+                continue;
+            }
+            patterns.push(entry.trim());
+        }
+        if (patterns.length > 0) out[canonical] = patterns;
+    }
+    return out;
+}
+
+/** speed_aware 三键缺省（enabled 缺省开启：T2 类别硬分区 + 缺数据零漂移已消解开启风险）。 */
+export function defaultSpeedAware(): SpeedAwareConfig {
+    return { enabled: true, mode: 'tie-break', minSamples: DEFAULT_MIN_SAMPLES };
+}
+
+/** 解析 `speed_aware`：非对象整键 warn 回落缺省；mode 非法枚举 / min_samples 非正数 / enabled 非布尔各键 warn 回落各自缺省（parseProviderAutoTiers warn 矩阵同款）。 */
+export function parseSpeedAware(raw: unknown, warn: (msg: string) => void): SpeedAwareConfig {
+    if (raw === undefined || raw === null) return defaultSpeedAware();
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        warn(`[omp-opsx-addon] speed_aware: expected object mapping { enabled, mode, min_samples }, got ${JSON.stringify(raw)}`);
+        return defaultSpeedAware();
+    }
+    const obj = raw as { enabled?: unknown; mode?: unknown; min_samples?: unknown };
+    let enabled = true;
+    if (obj.enabled !== undefined && obj.enabled !== null) {
+        if (typeof obj.enabled === 'boolean') {
+            enabled = obj.enabled;
+        } else {
+            warn(`[omp-opsx-addon] speed_aware.enabled: expected boolean, got ${JSON.stringify(obj.enabled)}`);
+        }
+    }
+    let mode: SpeedMode = 'tie-break';
+    if (obj.mode !== undefined && obj.mode !== null) {
+        if (typeof obj.mode === 'string' && (SPEED_MODES as readonly string[]).includes(obj.mode)) {
+            mode = obj.mode as SpeedMode;
+        } else {
+            warn(`[omp-opsx-addon] speed_aware.mode: expected one of ${SPEED_MODES.join('|')}, got ${JSON.stringify(obj.mode)}`);
+        }
+    }
+    let minSamples = DEFAULT_MIN_SAMPLES;
+    if (obj.min_samples !== undefined && obj.min_samples !== null) {
+        if (typeof obj.min_samples === 'number' && Number.isFinite(obj.min_samples) && obj.min_samples > 0) {
+            minSamples = obj.min_samples;
+        } else {
+            warn(`[omp-opsx-addon] speed_aware.min_samples: expected positive number, got ${JSON.stringify(obj.min_samples)}`);
+        }
+    }
+    return { enabled, mode, minSamples };
+}
+
+/** W4 难度路由缺省（enabled 缺省 false：结构改造 opt-in，与 speed_aware 缺省 true 的差异见 design D7）。 */
+export function defaultDifficultyRouting(): RoutingConfig {
+    return { enabled: false };
+}
+
+/** 解析 `difficulty_routing`：非对象整键 warn 回落缺省；enabled 非布尔逐键 warn 回落（parseSpeedAware 矩阵同款）。 */
+export function parseDifficultyRouting(raw: unknown, warn: (msg: string) => void): RoutingConfig {
+    if (raw === undefined || raw === null) return defaultDifficultyRouting();
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        warn(`[omp-opsx-addon] difficulty_routing: expected object mapping { enabled }, got ${JSON.stringify(raw)}`);
+        return defaultDifficultyRouting();
+    }
+    const obj = raw as { enabled?: unknown };
+    let enabled = false;
+    if (obj.enabled !== undefined && obj.enabled !== null) {
+        if (typeof obj.enabled === 'boolean') {
+            enabled = obj.enabled;
+        } else {
+            warn(`[omp-opsx-addon] difficulty_routing.enabled: expected boolean, got ${JSON.stringify(obj.enabled)}`);
+        }
+    }
+    return { enabled };
+}
+
+/** W4 stall 升档缺省（window=6 / threshold=3，LiteLLM 同参）。 */
+export function defaultStallEscalation(): StallEscalationConfig {
+    return { enabled: false, window: DEFAULT_WINDOW, threshold: DEFAULT_THRESHOLD };
+}
+
+/** 解析 `stall_escalation`：非对象整键回落；enabled 非布尔、window/threshold 非正整数各键 warn 回落各自缺省。 */
+export function parseStallEscalation(raw: unknown, warn: (msg: string) => void): StallEscalationConfig {
+    if (raw === undefined || raw === null) return defaultStallEscalation();
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        warn(`[omp-opsx-addon] stall_escalation: expected object mapping { enabled, window, threshold }, got ${JSON.stringify(raw)}`);
+        return defaultStallEscalation();
+    }
+    const obj = raw as { enabled?: unknown; window?: unknown; threshold?: unknown };
+    let enabled = false;
+    if (obj.enabled !== undefined && obj.enabled !== null) {
+        if (typeof obj.enabled === 'boolean') {
+            enabled = obj.enabled;
+        } else {
+            warn(`[omp-opsx-addon] stall_escalation.enabled: expected boolean, got ${JSON.stringify(obj.enabled)}`);
+        }
+    }
+    let window = DEFAULT_WINDOW;
+    if (obj.window !== undefined && obj.window !== null) {
+        if (typeof obj.window === 'number' && Number.isInteger(obj.window) && obj.window > 0) {
+            window = obj.window;
+        } else {
+            warn(`[omp-opsx-addon] stall_escalation.window: expected positive integer, got ${JSON.stringify(obj.window)}`);
+        }
+    }
+    let threshold = DEFAULT_THRESHOLD;
+    if (obj.threshold !== undefined && obj.threshold !== null) {
+        if (typeof obj.threshold === 'number' && Number.isInteger(obj.threshold) && obj.threshold > 0) {
+            threshold = obj.threshold;
+        } else {
+            warn(`[omp-opsx-addon] stall_escalation.threshold: expected positive integer, got ${JSON.stringify(obj.threshold)}`);
+        }
+    }
+    return { enabled, window, threshold };
+}
+
+/** W4 连续性守门缺省（weight 缺省 0.6：越高越保守/粘性越强）。 */
+export function defaultContinuityGuard(): ContinuityGuardConfig {
+    return { enabled: false, weight: DEFAULT_WEIGHT };
+}
+
+/** 解析 `continuity_guard`：非对象整键回落；enabled 非布尔、weight 越出 (0,1] 开闭区间各键 warn 回落各自缺省。 */
+export function parseContinuityGuard(raw: unknown, warn: (msg: string) => void): ContinuityGuardConfig {
+    if (raw === undefined || raw === null) return defaultContinuityGuard();
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        warn(`[omp-opsx-addon] continuity_guard: expected object mapping { enabled, weight }, got ${JSON.stringify(raw)}`);
+        return defaultContinuityGuard();
+    }
+    const obj = raw as { enabled?: unknown; weight?: unknown };
+    let enabled = false;
+    if (obj.enabled !== undefined && obj.enabled !== null) {
+        if (typeof obj.enabled === 'boolean') {
+            enabled = obj.enabled;
+        } else {
+            warn(`[omp-opsx-addon] continuity_guard.enabled: expected boolean, got ${JSON.stringify(obj.enabled)}`);
+        }
+    }
+    let weight = DEFAULT_WEIGHT;
+    if (obj.weight !== undefined && obj.weight !== null) {
+        if (typeof obj.weight === 'number' && Number.isFinite(obj.weight) && obj.weight > 0 && obj.weight <= 1) {
+            weight = obj.weight;
+        } else {
+            warn(`[omp-opsx-addon] continuity_guard.weight: expected number in (0, 1], got ${JSON.stringify(obj.weight)}`);
+        }
+    }
+    return { enabled, weight };
+}
+
+/** 解析 `quality_preference`：非法枚举 warn 回落 balanced（独立于三开关的顶层旋钮）。 */
+export function parseQualityPreference(raw: unknown, warn: (msg: string) => void): QualityPreference {
+    if (raw === undefined || raw === null) return 'balanced';
+    if (typeof raw === 'string' && (QUALITY_PREFERENCES as readonly string[]).includes(raw)) {
+        return raw as QualityPreference;
+    }
+    warn(`[omp-opsx-addon] quality_preference: expected one of ${QUALITY_PREFERENCES.join('|')}, got ${JSON.stringify(raw)}`);
+    return 'balanced';
+}
+
+/**
+ * 受管 provider 集合（spec: 受管集合 = `concurrency_providers` ∪
+ * `providers.maxInFlightRequests` 的键）。纯函数：`providers.maxInFlightRequests`
+ * 的读取由装配层负责（config root 的 `config.yml`）。
+ *
+ * 两侧 id 均经 `canonicalizeProvider` 规范化（大小写与 `ArkCodingPlan` →
+ * `ark-coding-plan` 别名收敛为同一列），去重并返回稳定顺序 —— 先
+ * `concurrency_providers` 的声明序，再 limits 侧新增键序。
+ */
+export function resolveManagedProviders(
+    concurrencyProviders: readonly string[] | undefined,
+    providerLimitIds: readonly string[] | Record<string, unknown> | undefined,
+): string[] {
+    const limitIds = Array.isArray(providerLimitIds)
+        ? providerLimitIds
+        : providerLimitIds
+            ? Object.keys(providerLimitIds)
+            : [];
+    const out: string[] = [];
+    const seen = new Set<string>();
+    for (const id of [...(concurrencyProviders ?? []), ...limitIds]) {
+        if (typeof id !== 'string') continue;
+        const canonical = canonicalizeProvider(id.trim());
+        if (!canonical || seen.has(canonical)) continue;
+        seen.add(canonical);
+        out.push(canonical);
+    }
+    return out;
+}
+
 /** Parse the full raw opsx config. */
 export function parseOpsxConfig(
     raw: unknown,
@@ -318,15 +828,21 @@ export function parseOpsxConfig(
         warn(m);
     };
 
-    function sanitizePlanProviders(raw: unknown): string[] {
-        if (raw === undefined || raw === null) return [];
-        if (!Array.isArray(raw)) return [];
-        return raw.filter((v): v is string => typeof v === 'string');
+    // `agents` mapping (canonical form): the key set is exactly the four
+    // managed agent names, so unknown subkeys are reported and dropped
+    // instead of vanishing silently.
+    const agentsMap = obj.agents as Record<string, unknown> | undefined;
+    if (agentsMap && typeof agentsMap === 'object') {
+        for (const key of Object.keys(agentsMap)) {
+            if (!(OPSX_ROLES as readonly string[]).includes(key)) {
+                localWarn(`[omp-opsx-addon] agents: unknown agent "${key}" (valid: ${OPSX_ROLES.join(', ')}); entry ignored`);
+            }
+        }
     }
-
     const roles: Record<OpsxRole, RoleValue> = {} as Record<OpsxRole, RoleValue>;
     for (const role of OPSX_ROLES) {
-        const raw = (obj as Record<string, unknown>)[role];
+        // Within one file the `agents` mapping beats the legacy top-level key.
+        const raw = agentsMap?.[role] ?? (obj as Record<string, unknown>)[role];
         roles[role] = parseRoleValue(raw as string | undefined, localWarn);
     }
     let redisHost = '127.0.0.1';
@@ -338,13 +854,72 @@ export function parseOpsxConfig(
         }
     }
 
+    // 并发控制：floor / ceiling 先各自回落，再校验区间（ceiling < floor）。
+    // floor 未显式配置时它只是默认值，MUST NOT 反过来抬高用户显式设定的 ceiling
+    // ——那等于放开了用户明确设下的上界。这种情况下把 floor 压到 ceiling（区间
+    // 退化为单点），保持上界意图；两端都显式给出矛盾值时仍按 spec 回落默认。
+    const floorConfigured = typeof obj.concurrency_floor === 'number'
+        && Number.isFinite(obj.concurrency_floor)
+        && Number.isInteger(obj.concurrency_floor)
+        && obj.concurrency_floor > 0;
+    let concurrencyFloor = parsePositiveInt(obj.concurrency_floor, 'concurrency_floor', CONCURRENCY_DEFAULTS.floor, localWarn);
+    let concurrencyCeiling = parsePositiveInt(obj.concurrency_ceiling, 'concurrency_ceiling', CONCURRENCY_DEFAULTS.ceiling, localWarn);
+    if (concurrencyCeiling < concurrencyFloor) {
+        if (!floorConfigured) {
+            localWarn(
+                `[omp-opsx-addon] concurrency_ceiling: ${concurrencyCeiling} < default concurrency_floor ${concurrencyFloor}; using the ceiling as the floor`,
+            );
+            concurrencyFloor = concurrencyCeiling;
+        } else {
+            localWarn(
+                `[omp-opsx-addon] concurrency_ceiling: ${concurrencyCeiling} < concurrency_floor ${concurrencyFloor}; falling back to ${CONCURRENCY_DEFAULTS.ceiling}`,
+            );
+            concurrencyCeiling = CONCURRENCY_DEFAULTS.ceiling;
+            if (concurrencyCeiling < concurrencyFloor) {
+                localWarn(
+                    `[omp-opsx-addon] concurrency_floor: ${concurrencyFloor} > default ceiling ${CONCURRENCY_DEFAULTS.ceiling}; falling back to ${CONCURRENCY_DEFAULTS.floor}`,
+                );
+                concurrencyFloor = CONCURRENCY_DEFAULTS.floor;
+            }
+        }
+    }
+
+    // 并发控制：`concurrency_up_ms` 是「干净窗口」的长度，`concurrency_eval_interval_ms`
+    // 是评估节奏。`evaluateWindow` 每次评估最多记 1 个干净窗口并丢弃余数
+    // （`cleanWindowMs = 0`），所以 up_ms ≤ eval_interval 时二者的 limit 轨迹
+    // 完全一致；把 up_ms 归一为 eval_interval 只是让配置反映真实生效值，
+    // 不改变任何行为（见 concurrency-tuner.ts 的 `max(up_ms, eval_interval_ms)`）。
+    let concurrencyUpMs = parsePositiveInt(obj.concurrency_up_ms, 'concurrency_up_ms', CONCURRENCY_DEFAULTS.up_ms, localWarn);
+    const concurrencyEvalIntervalMs = parsePositiveInt(obj.concurrency_eval_interval_ms, 'concurrency_eval_interval_ms', CONCURRENCY_DEFAULTS.eval_interval_ms, localWarn);
+    if (concurrencyUpMs < concurrencyEvalIntervalMs) {
+        localWarn(
+            `[omp-opsx-addon] concurrency_up_ms: ${concurrencyUpMs} < concurrency_eval_interval_ms ${concurrencyEvalIntervalMs}; using ${concurrencyEvalIntervalMs} (the effective clean window is max(up_ms, eval_interval_ms))`,
+        );
+        concurrencyUpMs = concurrencyEvalIntervalMs;
+    }
+
     return {
         roles,
         modelAllowlist: parseModelAllowlist(obj.model_allowlist, localWarn),
         tierOverrides: parseTierOverrides(obj.tiers, localWarn),
-        roleTiers: parseRoleTiers(obj.role_tiers, localWarn),
+        roleTiers: parseRoleTiers(
+            obj.agent_tiers ?? obj.role_tiers,
+            obj.agent_tiers !== undefined && obj.agent_tiers !== null ? 'agent_tiers' : 'role_tiers',
+            localWarn,
+        ),
         ompRoleTiers: parseOmpRoleTiers(obj.model_role_tiers, localWarn),
-        planProviders: sanitizePlanProviders(obj.plan_providers),
+        planProviders: parsePlanProviderList(obj.plan_providers, 'plan_providers', localWarn),
+        planProvidersRemove: parsePlanProviderList(obj.plan_providers_remove, 'plan_providers_remove', localWarn),
+        paygLastResort: parseProbeBool(obj.payg_last_resort, 'payg_last_resort', true, localWarn),
+        china: parseProbeBool(obj.china, 'china', false, localWarn),
+        providerAuto: parseProviderAuto(obj.provider_auto, localWarn),
+        providerAutoTiers: parseProviderAutoTiers(obj.provider_auto_tiers, localWarn),
+        providerModels: parseProviderModels(obj.provider_models, localWarn),
+        speedAware: parseSpeedAware(obj.speed_aware, localWarn),
+        difficultyRouting: parseDifficultyRouting(obj.difficulty_routing, localWarn),
+        stallEscalation: parseStallEscalation(obj.stall_escalation, localWarn),
+        continuityGuard: parseContinuityGuard(obj.continuity_guard, localWarn),
+        qualityPreference: parseQualityPreference(obj.quality_preference, localWarn),
         warnings,
         probe_enabled: parseProbeBool(obj.probe_enabled, 'probe_enabled', true, localWarn),
         probe_timeout_ms: parsePositiveInt(obj.probe_timeout_ms, 'probe_timeout_ms', 3000, localWarn),
@@ -361,6 +936,23 @@ export function parseOpsxConfig(
         redis_probe_interval_ms: parsePositiveInt(obj.redis_probe_interval_ms, 'redis_probe_interval_ms', 30_000, localWarn),
         redis_unhealthy_retry_ms: parsePositiveInt(obj.redis_unhealthy_retry_ms, 'redis_unhealthy_retry_ms', 5_000, localWarn),
         redis_ttl_ms: parsePositiveInt(obj.redis_ttl_ms, 'redis_ttl_ms', 180_000, localWarn),
+        autoselectOnStart: parseProbeBool(obj.autoselect_on_start, 'autoselect_on_start', true, localWarn),
+        concurrency_enabled: parseProbeBool(obj.concurrency_enabled, 'concurrency_enabled', CONCURRENCY_DEFAULTS.enabled, localWarn),
+        concurrency_floor: concurrencyFloor,
+        concurrency_ceiling: concurrencyCeiling,
+        concurrency_start: parsePositiveInt(obj.concurrency_start, 'concurrency_start', CONCURRENCY_DEFAULTS.start, localWarn),
+        concurrency_up_ms: concurrencyUpMs,
+        concurrency_down_ms: parsePositiveInt(obj.concurrency_down_ms, 'concurrency_down_ms', CONCURRENCY_DEFAULTS.down_ms, localWarn),
+        concurrency_latency_k: parsePositiveNumber(obj.concurrency_latency_k, 'concurrency_latency_k', CONCURRENCY_DEFAULTS.latency_k, localWarn),
+        concurrency_min_samples: parsePositiveInt(obj.concurrency_min_samples, 'concurrency_min_samples', CONCURRENCY_DEFAULTS.min_samples, localWarn),
+        concurrency_queue_wait_high_ms: parsePositiveInt(obj.concurrency_queue_wait_high_ms, 'concurrency_queue_wait_high_ms', CONCURRENCY_DEFAULTS.queue_wait_high_ms, localWarn),
+        concurrency_write_min_interval_ms: parsePositiveInt(obj.concurrency_write_min_interval_ms, 'concurrency_write_min_interval_ms', CONCURRENCY_DEFAULTS.write_min_interval_ms, localWarn),
+        concurrency_lease_ttl_ms: parsePositiveInt(obj.concurrency_lease_ttl_ms, 'concurrency_lease_ttl_ms', CONCURRENCY_DEFAULTS.lease_ttl_ms, localWarn),
+        concurrency_decay_after_ms: parsePositiveInt(obj.concurrency_decay_after_ms, 'concurrency_decay_after_ms', CONCURRENCY_DEFAULTS.decay_after_ms, localWarn),
+        concurrency_eval_interval_ms: concurrencyEvalIntervalMs,
+        concurrency_queue_wait_window_ms: parsePositiveInt(obj.concurrency_queue_wait_window_ms, 'concurrency_queue_wait_window_ms', CONCURRENCY_DEFAULTS.queue_wait_window_ms, localWarn),
+        concurrency_providers: parseConcurrencyProviders(obj.concurrency_providers, localWarn),
+        concurrency_ceiling_by_provider: parseCeilingByProvider(obj.concurrency_ceiling_by_provider, concurrencyFloor, localWarn),
     };
 }
 
@@ -393,16 +985,29 @@ function pickRoleKeys(raw: OpsxYamlShape): Partial<Record<OpsxRole, string>> {
 
 function pickTopLevelKeys(raw: OpsxYamlShape): OpsxYamlShape {
     return {
+        agents: raw.agents,
+        agent_tiers: raw.agent_tiers,
         model_allowlist: raw.model_allowlist,
         tiers: raw.tiers,
         role_tiers: raw.role_tiers,
         model_role_tiers: raw.model_role_tiers,
         plan_providers: raw.plan_providers,
+        plan_providers_remove: raw.plan_providers_remove,
+        payg_last_resort: raw.payg_last_resort,
+        china: raw.china,
         probe_enabled: raw.probe_enabled,
         probe_timeout_ms: raw.probe_timeout_ms,
         probe_http_enabled: raw.probe_http_enabled,
         probe_ttl_ms: raw.probe_ttl_ms,
         excluded_providers: raw.excluded_providers,
+        provider_auto: raw.provider_auto,
+        provider_auto_tiers: raw.provider_auto_tiers,
+        provider_models: raw.provider_models,
+        speed_aware: raw.speed_aware,
+        difficulty_routing: raw.difficulty_routing,
+        stall_escalation: raw.stall_escalation,
+        continuity_guard: raw.continuity_guard,
+        quality_preference: raw.quality_preference,
         status_probe_enabled: raw.status_probe_enabled,
         redis_enabled: raw.redis_enabled,
         redis_host: raw.redis_host,
@@ -413,6 +1018,23 @@ function pickTopLevelKeys(raw: OpsxYamlShape): OpsxYamlShape {
         redis_probe_interval_ms: raw.redis_probe_interval_ms,
         redis_unhealthy_retry_ms: raw.redis_unhealthy_retry_ms,
         redis_ttl_ms: raw.redis_ttl_ms,
+        autoselect_on_start: raw.autoselect_on_start,
+        concurrency_enabled: raw.concurrency_enabled,
+        concurrency_floor: raw.concurrency_floor,
+        concurrency_ceiling: raw.concurrency_ceiling,
+        concurrency_start: raw.concurrency_start,
+        concurrency_up_ms: raw.concurrency_up_ms,
+        concurrency_down_ms: raw.concurrency_down_ms,
+        concurrency_latency_k: raw.concurrency_latency_k,
+        concurrency_min_samples: raw.concurrency_min_samples,
+        concurrency_queue_wait_high_ms: raw.concurrency_queue_wait_high_ms,
+        concurrency_write_min_interval_ms: raw.concurrency_write_min_interval_ms,
+        concurrency_lease_ttl_ms: raw.concurrency_lease_ttl_ms,
+        concurrency_decay_after_ms: raw.concurrency_decay_after_ms,
+        concurrency_eval_interval_ms: raw.concurrency_eval_interval_ms,
+        concurrency_queue_wait_window_ms: raw.concurrency_queue_wait_window_ms,
+        concurrency_providers: raw.concurrency_providers,
+        concurrency_ceiling_by_provider: raw.concurrency_ceiling_by_provider,
     };
 }
 
@@ -441,11 +1063,44 @@ function warnLegacySettingsJson(
     }
 }
 
+/**
+ * Per-layer rename diagnostics: one aggregated warning when a layer file
+ * still uses a legacy key (all offending names in a single line), plus one
+ * warning per unknown `agents` subkey (the mapping's key set is exactly the
+ * four managed agents, so a typo would otherwise vanish silently).
+ */
+function warnAgentRenameDiagnostics(
+    path: string,
+    raw: OpsxYamlShape,
+    warn: (msg: string) => void,
+): void {
+    const legacy = LEGACY_AGENT_KEYS.filter((key) => {
+        const v = (raw as Record<string, unknown>)[key];
+        return v !== undefined && v !== null;
+    });
+    if (legacy.length > 0) {
+        warn(
+            `[omp-opsx-addon] ${path}: legacy key(s) ${legacy.map((k) => `'${k}'`).join(', ')} still honored — ` +
+                `move them into the 'agents:' mapping / rename 'role_tiers' to 'agent_tiers' ` +
+                '(within one file the new keys win); legacy keys are scheduled for removal after one release cycle',
+        );
+    }
+    const agents = raw.agents;
+    if (agents && typeof agents === 'object') {
+        for (const key of Object.keys(agents)) {
+            if (!(OPSX_ROLES as readonly string[]).includes(key)) {
+                warn(`[omp-opsx-addon] ${path}: agents.${key}: unknown agent (valid: ${OPSX_ROLES.join(', ')}); entry ignored`);
+            }
+        }
+    }
+}
+
 /**
  * Read opsx config from two-layer opsx.yml:
  *   - global: `<homeDir>/.omp/agent/opsx.yml`
- *   - project: `<cwd>/.omp/opsx.yml` (per-key override on roles; full overlay on
- *     `model_allowlist` / `tiers` / `role_tiers`)
+ *   - project: `<cwd>/.omp/opsx.yml` (per-key override on `agents` — legacy:
+ *     top-level role keys; full overlay on `model_allowlist` / `tiers` /
+ *     `agent_tiers` — legacy: `role_tiers`)
  *
  * `homeDir` is overridable for tests; defaults to `os.homedir()`.
  */
@@ -471,30 +1126,63 @@ export function readOpsxSettingsFromPaths(
     const homeFromGlobal = globalPath.replace(/\.omp\/agent\/opsx\.yml$/, '');
     const projectFromPath = projectPath.replace(/\.omp\/opsx\.yml$/, '');
     warnLegacySettingsJson(projectFromPath, homeFromGlobal, warn);
+    warnAgentRenameDiagnostics(globalPath, globalYaml, warn);
+    warnAgentRenameDiagnostics(projectPath, projectYaml, warn);
 
     const globalRoles = pickRoleKeys(globalYaml);
     const projectRoles = pickRoleKeys(projectYaml);
 
-    // Per-role: project overrides global, fall back to DEFAULT_OPSX.
+    // Top-level: project fully replaces global when present.
+    const projectTop = pickTopLevelKeys(projectYaml);
+    const globalTop = pickTopLevelKeys(globalYaml);
+
+    // Per-role: project overrides global, fall back to DEFAULT_OPSX. Within
+    // each layer the `agents` mapping beats the legacy top-level key; across
+    // layers it stays a per-key overlay (a project legacy key can override a
+    // global `agents` entry and vice versa).
     const merged: OpsxYamlShape = { ...globalYaml };
     for (const role of OPSX_ROLES) {
-        const v = projectRoles[role] ?? globalRoles[role] ?? DEFAULT_OPSX[role];
+        const v = projectTop.agents?.[role] ?? projectRoles[role] ?? globalTop.agents?.[role] ?? globalRoles[role] ?? DEFAULT_OPSX[role];
         (merged as Record<string, unknown>)[role] = v;
     }
+    // The loop already folded `agents` entries into the resolved legacy keys;
+    // a raw mapping left on `merged` would shadow them inside parseOpsxConfig.
+    merged.agents = undefined;
 
-    // Top-level: project fully replaces global when present.
-    const projectTop = pickTopLevelKeys(projectYaml);
-    const globalTop = pickTopLevelKeys(globalYaml);
     merged.model_allowlist = projectTop.model_allowlist ?? globalTop.model_allowlist;
     merged.tiers = projectTop.tiers ?? globalTop.tiers;
     merged.role_tiers = projectTop.role_tiers ?? globalTop.role_tiers;
+    // Tier map: `agent_tiers` beats `role_tiers` within each layer, then the
+    // legacy whole-key overlay applies (project map replaces global's).
+    const projectTiers = projectTop.agent_tiers ?? projectTop.role_tiers;
+    const globalTiers = globalTop.agent_tiers ?? globalTop.role_tiers;
+    merged.agent_tiers = projectTiers ?? globalTiers;
     merged.model_role_tiers = projectTop.model_role_tiers ?? globalTop.model_role_tiers;
     merged.plan_providers = projectTop.plan_providers ?? globalTop.plan_providers;
+    merged.plan_providers_remove = projectTop.plan_providers_remove ?? globalTop.plan_providers_remove;
+    merged.payg_last_resort = projectTop.payg_last_resort ?? globalTop.payg_last_resort;
+    // `??` keeps an explicit project `false` (parseProbeBool only falls back on
+    // null/undefined AFTER the merge, so undefined reveals the other layer).
+    merged.china = projectTop.china ?? globalTop.china;
     merged.probe_enabled = projectTop.probe_enabled ?? globalTop.probe_enabled;
     merged.probe_timeout_ms = projectTop.probe_timeout_ms ?? globalTop.probe_timeout_ms;
     merged.probe_http_enabled = projectTop.probe_http_enabled ?? globalTop.probe_http_enabled;
     merged.probe_ttl_ms = projectTop.probe_ttl_ms ?? globalTop.probe_ttl_ms;
     merged.excluded_providers = projectTop.excluded_providers ?? globalTop.excluded_providers;
+    // Provider 键控 map 同为整键覆盖（先例 concurrency_ceiling_by_provider）：项目层
+    // 声明任一键即完整替换全局同名键，不做 per-key 叠加——只想加键就把全局条目抄过来。
+    merged.provider_auto = projectTop.provider_auto ?? globalTop.provider_auto;
+    merged.provider_auto_tiers = projectTop.provider_auto_tiers ?? globalTop.provider_auto_tiers;
+    merged.provider_models = projectTop.provider_models ?? globalTop.provider_models;
+    // 对象键一律整键覆盖（同上 provider_* 先例）：项目层声明 speed_aware 即
+    // 整份替换全局，不做字段级叠加。
+    merged.speed_aware = projectTop.speed_aware ?? globalTop.speed_aware;
+    // W4 路由四键同款整键覆盖：项目层声明任一键即完整替换全局同名键。
+    merged.difficulty_routing = projectTop.difficulty_routing ?? globalTop.difficulty_routing;
+    merged.stall_escalation = projectTop.stall_escalation ?? globalTop.stall_escalation;
+    merged.continuity_guard = projectTop.continuity_guard ?? globalTop.continuity_guard;
+    // 顶层标量键同 `??` 惯例（项目层显式值优先，undefined 露出另一层）。
+    merged.quality_preference = projectTop.quality_preference ?? globalTop.quality_preference;
     merged.status_probe_enabled = projectTop.status_probe_enabled ?? globalTop.status_probe_enabled;
     merged.redis_enabled = projectTop.redis_enabled ?? globalTop.redis_enabled;
     merged.redis_host = projectTop.redis_host ?? globalTop.redis_host;
@@ -505,6 +1193,23 @@ export function readOpsxSettingsFromPaths(
     merged.redis_probe_interval_ms = projectTop.redis_probe_interval_ms ?? globalTop.redis_probe_interval_ms;
     merged.redis_unhealthy_retry_ms = projectTop.redis_unhealthy_retry_ms ?? globalTop.redis_unhealthy_retry_ms;
     merged.redis_ttl_ms = projectTop.redis_ttl_ms ?? globalTop.redis_ttl_ms;
+    merged.autoselect_on_start = projectTop.autoselect_on_start ?? globalTop.autoselect_on_start;
+    merged.concurrency_enabled = projectTop.concurrency_enabled ?? globalTop.concurrency_enabled;
+    merged.concurrency_floor = projectTop.concurrency_floor ?? globalTop.concurrency_floor;
+    merged.concurrency_ceiling = projectTop.concurrency_ceiling ?? globalTop.concurrency_ceiling;
+    merged.concurrency_start = projectTop.concurrency_start ?? globalTop.concurrency_start;
+    merged.concurrency_up_ms = projectTop.concurrency_up_ms ?? globalTop.concurrency_up_ms;
+    merged.concurrency_down_ms = projectTop.concurrency_down_ms ?? globalTop.concurrency_down_ms;
+    merged.concurrency_latency_k = projectTop.concurrency_latency_k ?? globalTop.concurrency_latency_k;
+    merged.concurrency_min_samples = projectTop.concurrency_min_samples ?? globalTop.concurrency_min_samples;
+    merged.concurrency_queue_wait_high_ms = projectTop.concurrency_queue_wait_high_ms ?? globalTop.concurrency_queue_wait_high_ms;
+    merged.concurrency_write_min_interval_ms = projectTop.concurrency_write_min_interval_ms ?? globalTop.concurrency_write_min_interval_ms;
+    merged.concurrency_lease_ttl_ms = projectTop.concurrency_lease_ttl_ms ?? globalTop.concurrency_lease_ttl_ms;
+    merged.concurrency_decay_after_ms = projectTop.concurrency_decay_after_ms ?? globalTop.concurrency_decay_after_ms;
+    merged.concurrency_eval_interval_ms = projectTop.concurrency_eval_interval_ms ?? globalTop.concurrency_eval_interval_ms;
+    merged.concurrency_queue_wait_window_ms = projectTop.concurrency_queue_wait_window_ms ?? globalTop.concurrency_queue_wait_window_ms;
+    merged.concurrency_providers = projectTop.concurrency_providers ?? globalTop.concurrency_providers;
+    merged.concurrency_ceiling_by_provider = projectTop.concurrency_ceiling_by_provider ?? globalTop.concurrency_ceiling_by_provider;
 
     return parseOpsxConfig(merged, warn);
 }