@genee/omp-opsx-addon 0.7.0 → 0.9.0

package/index.ts

@@ -82,30 +82,71 @@ function handleSubagentEvent(payload: unknown, primarySessionId: string): void {
         getLogger().error('Failed to handle subagent event', { err });
     }
 }
-import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext, Settings } from '@oh-my-pi/pi-coding-agent';
-import { getKnownRoleIds, MODEL_ROLE_IDS } from '@oh-my-pi/pi-coding-agent/config/model-roles';
+import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from '@oh-my-pi/pi-coding-agent';
+import { discoverAgents } from '@oh-my-pi/pi-coding-agent/task/discovery';
 import type { Model, Api } from '@oh-my-pi/pi-catalog/types';
 import type { UsageReport } from '@oh-my-pi/pi-ai';
 import { createCachedScanner } from './lib/change-scanner.js';
-import { installAgents } from './lib/agent-defs.js';
+import { installAgents, SCOPE_FENCE_TAG } from './lib/agent-defs.js';
 import {
     applyRoleModelOverrides,
     buildRoleOverridePlan,
     dispatchModelHint,
     frontmatterModel,
+    resolveOmpRoleTier,
     ROLE_TO_OMP_ALIAS,
     OMP_ROLE_TO_TIER,
     ROLE_CAPABILITY,
     type SkippedRole,
 } from './lib/model-roles.js';
+import {
+    annotationOfPicked,
+    coverageLabel,
+    formatAgentInventory,
+    formatCandidateOverview,
+    formatChangeLine,
+    formatFootnote,
+    formatRoleLines,
+    renderPickModelReport,
+    resolveSymbols,
+    roleKindLabel,
+    tierLabel,
+} from './lib/pick-model-render.js';
 import { buildStaticPrompt, buildDynamicPrompt } from './lib/system-prompt.js';
 import { type ProviderHealth, canonicalizeProvider, listDetectableProviders, healthCacheKey } from './lib/usage-resolver.js';
-import { readOpsxSettings, type ResolvedOpsxConfig, type RoleValue, OPSX_ROLES } from './lib/unified-config.js';
+import { readOpsxSettings, resolveManagedProviders, type ResolvedOpsxConfig, type RoleValue, OPSX_ROLES } from './lib/unified-config.js';
+import {
+    createConcurrencyController,
+    createNodeFsPort,
+    type ConcurrencyController,
+    type ConcurrencyLeaseFactory,
+    type ConcurrencyRedisPort,
+    type SettingsPort,
+} from './lib/concurrency-control.js';
+import { TUNER_DEFAULTS, type TunerOptions } from './lib/concurrency-tuner.js';
+import { nodeWriterFileSystem } from './lib/concurrency-writer.js';
+import { RedisClient } from './lib/usage-redis-client.js';
 import { selectAllRoles, selectModel, mergePlanProviders, type SelectorResult } from './lib/model-selector.js';
+import { resolveSpeedAware } from './lib/model-speed.js';
 import { scoreModelWithProvider, type TierName } from './lib/model-tiers.js';
+import {
+    applyBandOffset,
+    classifyTaskSafe,
+    type RoutingRuntime,
+    type TaskBand,
+} from './lib/complexity-router.js';
+import {
+    createStallRuntime,
+    evaluateStall,
+    recordToolCall,
+    rebuildFromEntries,
+    toolSignature,
+    type StallRuntime,
+} from './lib/stall-detector.js';
+import { decideGuard, pinPriorPick } from './lib/continuity-guard.js';
 import { DIRECT_FETCHERS } from './lib/direct-fetchers.js';
 import { createUsageWidget } from './lib/usage-widget.js';
-import { renderUsageReports, type ConsumptionTrack } from './lib/usage-render.js';
+import { renderUsageReports, type ConsumptionTrack, type ConcurrencyInlineView } from './lib/usage-render.js';
 import { markExhausted, markAvailable, getExhaustedProviders } from './lib/provider-status.js';
 import { registerPipeCore } from './lib/pipe-core.js';
 import { registerPipePush } from './lib/pipe-push.js';
@@ -134,7 +175,6 @@ import {
 import { updateTiers, autoRefreshTiersIfStale } from './lib/tiers-updater.js';
 import { appendSample, getConsumptionSamples, RING_SIZE } from './lib/usage-sampler.js';
 import { buildBalanceEstimates, type UsageBucket } from './lib/usage-estimator.js';
-import { matchDataEntry, TIERS_DATA_PATH, isTiersDataLoaded, tiersDataAge } from './lib/tiers-data.js';
 import {
     loadBlockedModels,
     persistBlockedModels,
@@ -144,21 +184,102 @@ import { refreshReachability } from './lib/reachability-refresh.js';
 import { loadAvailableByProvider } from './lib/reachability-refresh.js';
 import { filterSelectableModels, reachabilityFingerprint } from './lib/selection-filters.js';
 import { parseAutoModelArgs, CHINA_EXCLUDE_FAMILIES, listFamilies, listProviders } from './lib/family-filter.js';
+import {
+    REGION_VARIANT_GROUPS,
+    resolveVariantCollapse,
+    variantCollapseAnnotation,
+    collapseUsageView,
+    providerSurvivesAllowlist,
+    type VariantCollapseResult,
+} from './lib/provider-variants.js';
 import { hasRateLimitError, hasRegionError, buildErrorDiagnosis, exclusionReasonStats } from './lib/error-scan.js';
-import { applyEditVariantPin } from './lib/edit-variant-pin.js';
+import { applyEditVariantPin, resolveGlobalConfigPath } from './lib/edit-variant-pin.js';
 import { setOpsxLogger, getLogger } from './lib/logger.js';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { YAML } from 'bun';
 type Role = 'coder' | 'reviewer' | 'planner' | 'proposal-reviewer';
 
 /** Session-scoped selector constraint for `/pick-model <selector> [--china]`. */
 export interface FamilyConstraint {
     selectors: string[] | null;
     excludeSelectors: string[];
+    /** Canonical modelRole ids the constraint narrows; null/absent = global (all roles). */
+    roles?: string[] | null;
 }
 
-/** Stable fingerprint of the active selector constraint (design Decision 3/9). */
-function familyConstraintFingerprint(fc: FamilyConstraint | null): string {
+/**
+ * Stable fingerprint of the active selector constraint (design Decision 3/9;
+ * pick-model-role-scope: roles participate so global↔scoped switches and scope
+ * changes invalidate the selection health cache). Exported for tests — the
+ * fingerprint IS the documented cache-invalidation contract.
+ */
+export function familyConstraintFingerprint(fc: FamilyConstraint | null): string {
     if (!fc) return 'none';
-    return `fam:${fc.selectors ? fc.selectors.join(',') : '*'}|excl:${fc.excludeSelectors.join(',')}`;
+    return `fam:${fc.selectors ? fc.selectors.join(',') : '*'}|excl:${fc.excludeSelectors.join(',')}|roles:${fc.roles ? fc.roles.join(',') : '*'}`;
+}
+
+/**
+ * Fingerprint of the regional-variant collapse set (china-config). Exported
+ * for tests — same contract as familyConstraintFingerprint: the segment is the
+ * documented cache-invalidation channel for auth-state flips (re-login can
+ * change which side of a variant pair collapses, so the set must participate
+ * in the selection health key).
+ */
+export function variantCollapseFingerprint(collapsed: ReadonlySet<string>): string {
+    return `variants:${[...collapsed].sort().join(',')}`;
+}
+
+/**
+ * Pre-resolve the API keys of the variant-group members present in `present`
+ * (≤2 awaits) into the sync key view `resolveVariantCollapse` gates on. A
+ * missing getter, a rejected/throwing lookup, or an empty key all land as
+ * `undefined` → the gate stays conservative (both doors coexist).
+ */
+async function resolveVariantKeyLookup(
+    present: ReadonlySet<string>,
+    getApiKey: ((provider: string) => Promise<string | undefined>) | undefined,
+): Promise<(provider: string) => string | undefined> {
+    const keys = new Map<string, string | undefined>();
+    for (const group of REGION_VARIANT_GROUPS) {
+        for (const member of [group.domestic, group.intl]) {
+            if (!present.has(member) || keys.has(member)) continue;
+            try {
+                keys.set(member, (await getApiKey?.(member)) ?? undefined);
+            } catch {
+                keys.set(member, undefined);
+            }
+        }
+    }
+    return (provider) => keys.get(provider);
+}
+
+/**
+ * Scope roles → tier slots (pick-model-role-scope D3). Resolved with the same
+ * effective mapping batch-all-roles uses (`model_role_tiers` override + the
+ * built-in default table). `vision` contributes no slot (its scope semantics
+ * gate the capability candidate set instead); a role resolving to the `skip`
+ * sentinel throws ScopedRoleSkipError — a skip role sits on no tier slot, so a
+ * pool constraint on it is inexpressible.
+ */
+export class ScopedRoleSkipError extends Error {
+    constructor(readonly role: string) {
+        super(`role 定向条目 "${role}" 的有效档位为 skip（model_role_tiers），无法对其施加池约束`);
+    }
+}
+
+export function scopedTierSlots(
+    roles: readonly string[] | null | undefined,
+    ompRoleTiers: Record<string, TierName | 'skip'>,
+): Set<TierName> {
+    const slots = new Set<TierName>();
+    for (const role of roles ?? []) {
+        const tier = resolveOmpRoleTier(role, ompRoleTiers);
+        if (tier === 'skip') throw new ScopedRoleSkipError(role);
+        if (role === 'vision') continue;
+        slots.add(tier);
+    }
+    return slots;
 }
 
 /**
@@ -170,12 +291,13 @@ function selectionHealthKeyFor(
     reach: { unreachable: Set<string>; availableByProvider: Map<string, string[] | null> },
     fc: FamilyConstraint | null,
     blocked: ReadonlySet<string>,
+    collapsed: ReadonlySet<string>,
 ): string {
     return `${healthCacheKey(health)}|${reachabilityFingerprint({
         unreachable: reach.unreachable,
         availableByProvider: reach.availableByProvider,
         blocked,
-    })}|${familyConstraintFingerprint(fc)}`;
+    })}|${familyConstraintFingerprint(fc)}|${variantCollapseFingerprint(collapsed)}`;
 }
 
 /** Suggested id segment for the ambiguity hint (design Decision 8). */
@@ -261,12 +383,12 @@ export interface SelectionContext {
     roleOverrides: Record<string, string>;
     /** Known roles left out of the overlay payload (config skip / capability gate / no pick). */
     skippedRoles: SkippedRole[];
+    /** payg_last_resort the selection was computed with — drives the 分区 fold annotation in choices markdown. Default true. */
+    paygLastResort?: boolean;
+    /** W4 routing: the task band this selection was computed with (undefined = routing runtime absent). */
+    routingBand?: TaskBand;
 }
 
-const DEFAULT_PLAN_PROVIDERS = new Set(['minimax-code-cn', 'opencode-go', 'zhipu-coding-plan', 'kimi', 'openai-codex']);
-
-
-
 function roleValueToModelString(value: RoleValue): string | undefined {
     if (value.kind === 'auto') return undefined;
     if (value.kind === 'omp-alias') return `@${value.alias}`;
@@ -305,53 +427,126 @@ export function buildDispatchPrompt(role: Role, task: string, selection: Selecti
     else parts.push(`请直接通过 task 工具调用 ${agent}（无需指定 model，模型按 role 自动解析）。`);
     if (sel?.decision) parts.push(`原因: ${sel.decision}`);
     parts.push('直接用内置工具实现。');
+    if (role === 'coder') parts.push(`${SCOPE_FENCE_TAG}与本任务无关的异常状态（别人未提交的改动、无关失败测试、无关脏文件、工作树状态与预期不符）：最小相关性核查（如 git status、确认被改动文件是否落在本次改动面内）不受限；判定为无关后 MUST NOT 调查改动来源、MUST NOT 暂停当前任务，改为记录假设、写入交付摘要 SUMMARY、继续执行当前任务；真阻塞（缺依赖 / 契约动摇 / 权限不足 / 需用户决策）仍立即 STATUS: blocked。`);
     return `请使用 task 工具委派给 ${agent}：\ntask(agent:"${agent}"${modelHint ? `, model:"${modelHint}"` : ''}, task:"${parts.join(' ')}\\n\\n${task}")`;
 }
 
-/**
- * All model roles the host currently knows (10 built-in + custom roles from
- * cycleOrder/modelRoles/modelTags). Host settings can throw during early
- * startup or partial init; fall back to the built-in set rather than
- * aborting selection (later recomputes pick up custom roles once ready).
- */
-function safeGetKnownRoleIds(settings: Settings | null | undefined): string[] {
-    if (!settings) return [...MODEL_ROLE_IDS];
-    try {
-        return getKnownRoleIds(settings);
-    } catch (err) {
-        getLogger().warn(`[omp-opsx-addon] getKnownRoleIds failed; using built-in model roles only: ${err instanceof Error ? err.message : String(err)}`);
-        return [...MODEL_ROLE_IDS];
-    }
-}
-
 function computeSelectionSync(
     config: ResolvedOpsxConfig,
     models: Model<Api>[] | null,
     health: Map<string, ProviderHealth> | null,
-    knownRoleIds: string[],
     regionBlockedModels?: Set<string>,
     unreachableProviders?: Set<string>,
     availableByProvider?: Map<string, string[] | null>,
     familyConstraint?: FamilyConstraint | null,
+    collapsedProviders?: ReadonlySet<string>,
+    onWarn?: (msg: string) => void,
+    /** W4 routing runtime (design D8.5); undefined = all switches off + balanced → byte-identical legacy path. */
+    routing?: RoutingRuntime,
 ): SelectionContext {
-    const filteredModels = models
+    const fc = familyConstraint ?? null;
+    // pick-model-role-scope: pool split. basePool = reachability/provider
+    // filtering plus account-level regional-variant dedup (china-config: the
+    // collapse set is resolved at the call sites and narrows EVERY slot,
+    // scoped or not — account-level, orthogonal to constraints);
+    // filteredModels = basePool further narrowed by the selector filter and
+    // the effective china exclusion (explicit `--china` constraint first, else
+    // the `china: true` config default). Global constraints feed every slot
+    // from the single filtered pool (status-quo shape); scoped constraints
+    // only the slots in scope — everything else draws basePool, which
+    // deliberately KEEPS china families (role-scope contract: out-of-scope
+    // slots never inherit the standing exclusion).
+    const scopeRoles = fc?.roles && fc.roles.length > 0 ? fc.roles : null;
+    const scopedSlots = scopedTierSlots(scopeRoles, config.ompRoleTiers);
+    // provider-auto-targets: config-static per-provider narrowing at the pool
+    // layer — every downstream slot (tierPicks / vision / role pools) inherits it.
+    const providerModelMap = Object.keys(config.providerModels).length > 0
+        ? new Map(Object.entries(config.providerModels))
+        : undefined;
+    const providerModelWipes = new Set<string>();
+    const basePool = models
         ? filterSelectableModels(models, {
             blockedSelectors: regionBlockedModels,
             unreachableProviders,
-            excludedProviders: config.excluded_providers,
+            excludedProviders: [...config.excluded_providers, ...(collapsedProviders ?? [])],
             availableByProvider,
-            selectors: familyConstraint?.selectors ?? undefined,
-            excludeSelectors:
-                familyConstraint?.excludeSelectors && familyConstraint.excludeSelectors.length > 0
-                    ? familyConstraint.excludeSelectors
-                    : undefined,
+            providerModels: providerModelMap,
+            zeroHitProviders: providerModelWipes,
         })
         : models;
+    if (onWarn) {
+        for (const p of providerModelWipes) {
+            onWarn(`[omp-opsx-addon] provider_models.${p}: 收窄零命中（候选全部未命中模式，检查模式拼写是否与 catalog id 一致）`);
+        }
+        // Sentinel id drift (catalog renamed its auto entry): marking silently
+        // falls back to heuristic scoring — surface it instead of staying quiet.
+        for (const [p, id] of Object.entries(config.providerAuto)) {
+            const inPool = basePool?.some((m) => canonicalizeProvider(m.provider) === p);
+            if (!inPool) continue;
+            const hit = basePool?.some((m) => canonicalizeProvider(m.provider) === p && m.id.toLowerCase() === id.toLowerCase());
+            if (!hit) onWarn(`[omp-opsx-addon] provider_auto.${p}: 声明的哨兵 id "${id}" 不在 ${p} 的存活候选中（catalog id 已漂移？标记失效，回落普通评分）`);
+        }
+    }
+    // 命令显式 > 配置缺省: a constraint carrying excludeSelectors wins; the
+    // config default only fills in when the constraint carries none. Invariant:
+    // excludeSelectors has exactly one write site (parsed.china →
+    // CHINA_EXCLUDE_FAMILIES in the selector branch), so non-empty ≡ explicit.
+    const effectiveExclude =
+        fc?.excludeSelectors && fc.excludeSelectors.length > 0
+            ? fc.excludeSelectors
+            : config.china
+                ? CHINA_EXCLUDE_FAMILIES
+                : undefined;
+    const filteredModels = basePool
+        ? filterSelectableModels(basePool, {
+            selectors: fc?.selectors ?? undefined,
+            excludeSelectors: effectiveExclude,
+        })
+        : basePool;
+    // Pool a slot draws from: global constraints (roles null) constrain every
+    // slot; scoped constraints only the slots the scope roles map onto.
+    const poolForSlot = (slot: TierName): Model<Api>[] | null =>
+        scopeRoles === null || scopedSlots.has(slot) ? filteredModels : basePool;
     const selectorResults = {} as Record<Role, SelectorResult>;
     const roleModels = {} as Record<Role, string | undefined>;
     const roleConfigs = {} as Record<Role, string | undefined>;
     const roleKind = {} as Record<Role, RoleValue['kind']>;
-    const planSet = mergePlanProviders(config.planProviders);
+    const planSet = mergePlanProviders(config.planProviders, config.planProvidersRemove);
+    // Speed-aware selection: undefined when disabled — zero DB IO, and the
+    // selector keeps the frozen W1 order byte-for-byte.
+    const speedAware = resolveSpeedAware(config.speedAware);
+    // ── W4 difficulty routing (design D3/D5) ──────────────────────
+    // `routing === undefined` keeps every map/value at its legacy identity —
+    // the zero-drift structure is "not entering" the new paths, not an
+    // equivalent re-derivation. Explicit command paths KEEP the session-band
+    // offsets (design D5: 沿用当前会话级 band) and skip only guard pinning and
+    // the band annotation (显式指令 > 守门；显式路径不做新分类).
+    // Offsets are SELECTOR-TARGET pre-corrections only: the role→slot mapping
+    // (buildRoleOverridePlan's input) stays structurally untouched — smol
+    // always consumes the coder pick, slow the top supplemental, so shifted
+    // targets flow through the existing slots.
+    // Selector-side offsets key on the OMP write-set alias (smol/default/
+    // slow/vision); opsx roles translate via ROLE_TO_OMP_ALIAS.
+    const routedTierFor = (role: string, ompRole: string | undefined, base: TierName): TierName => {
+        if (!routing || !ompRole) return base;
+        // The per-role map carries only this role's base tier, so a `skip`
+        // sentinel can never appear here — but the offset table's value type
+        // admits it, and falling back to the base keeps that safe.
+        const routed = applyBandOffset({ [ompRole]: base }, routing.band, { stallActive: routing.stallActive });
+        const value = routed[ompRole];
+        return value === 'skip' || value === undefined ? base : value;
+    };
+    // Data-layer annotations (design D9): `band=<band>` when routing drives
+    // the recompute, `stall+1` on the roles aliased to default while stall is
+    // active. Explicit paths suppress the band segment (no fresh
+    // classification).
+    const noteFor = (role: string): string | undefined => {
+        if (!routing) return undefined;
+        const parts: string[] = [];
+        if (!routing.explicit && config.difficultyRouting.enabled) parts.push(`band=${routing.band}`);
+        if (routing.stallActive && ROLE_TO_OMP_ALIAS[role] === 'default') parts.push('stall+1');
+        return parts.length > 0 ? parts.join(', ') : undefined;
+    };
     for (const role of OPSX_ROLES) {
         const value = config.roles[role];
         roleKind[role] = value.kind;
@@ -362,20 +557,31 @@ function computeSelectionSync(
             : (roleValueToModelString(value) ?? '?');
         const alias = `@${ROLE_TO_OMP_ALIAS[role]}`;
         if (value.kind === 'auto') {
-            if (filteredModels && filteredModels.length > 0) {
+            // coder's pick feeds the mid slot, the other three feed high —
+            // the same consumed-slot mapping buildEffectiveConfig and the
+            // tierPicks assembly below use.
+            const pool = poolForSlot(role === 'coder' ? 'mid' : 'high');
+            if (pool && pool.length > 0) {
                 const ompRole = ROLE_TO_OMP_ALIAS[role];
-                const tier = (config.roleTiers[role]
+                const tier = routedTierFor(role, ompRole, (config.roleTiers[role]
                     ?? (OMP_ROLE_TO_TIER as Record<string, TierName>)[ompRole]
-                    ?? 'mid') as TierName;
+                    ?? 'mid') as TierName);
                 const roleTiers = { ...config.roleTiers, [role]: tier };
                 const result = selectAllRoles(
                     [role],
-                    filteredModels,
+                    pool,
                     roleTiers,
                     config.tierOverrides,
                     health ?? undefined,
                     config.modelAllowlist,
                     planSet,
+                    undefined,
+                    config.paygLastResort,
+                    config.providerAuto,
+                    config.providerAutoTiers,
+                    speedAware,
+                    routing?.qualityPreference,
+                    noteFor(role),
                 )[role];
                 selectorResults[role] = result;
                 roleModels[role] = result.picked ? alias : undefined;
@@ -397,123 +603,118 @@ function computeSelectionSync(
             roleModels[role] = modelString?.includes('/') ? modelString : undefined;
         }
     }
-    // change: pick-model-batch-all-roles — build the full-role session overlay:
-    // every host-known role (10 built-in + custom) follows one tier's picked
-    // model. mid/high reuse the opsx picks (coder/reviewer); tiny/low/top are
-    // supplemental picks over the same filtered candidate set; vision picks
-    // from image-capable candidates only. See design D2/D3.
+    // ── W4 continuity guard (design D5) ───────────────────────────
+    // Pin viable incumbents on auto recomputes — the pin outranks every
+    // tie-break; a switch needs a strict band upgrade at sufficient
+    // confidence, a stall escalation, or an incumbent hard-filtered out of
+    // the pool. Runs BEFORE the overlay plan so pinned picks flow into
+    // roleOverrides; explicit paths bypass (显式指令 > 守门).
+    if (routing?.guard && !routing.explicit) {
+        const incumbentResults = routing.guard.incumbent?.selectorResults ?? null;
+        for (const role of OPSX_ROLES) {
+            const prev = incumbentResults?.[role];
+            if (!prev?.picked) continue;
+            const cur = selectorResults[role];
+            const picked = prev.picked;
+            // Viability = the incumbent's selector still sits in the fresh
+            // candidate pool (zero registry queries — pool membership only).
+            const viable = cur.candidates.some((c) => c.model.provider === picked.provider && c.model.id === picked.id);
+            // Stall escalates the `default` alias only (reviewer/planner/
+            // proposal-reviewer); coder maps to smol and stays sticky.
+            const outcome = decideGuard({
+                enabled: true,
+                weight: routing.guard.weight,
+                explicit: false,
+                incumbent: prev,
+                incumbentViable: viable,
+                newBand: routing.band,
+                incumbentBand: routing.guard.priorBand ?? null,
+                confidence: routing.confidence,
+                stallEscalated: routing.stallActive && ROLE_TO_OMP_ALIAS[role] === 'default',
+            });
+            if (outcome.decision === 'pin' && outcome.pinned) {
+                selectorResults[role] = pinPriorPick(outcome.pinned, routing.band);
+            }
+        }
+    }
+    // change: pick-model-ux — minimal write-set session overlay {smol, default,
+    // slow, vision}: mid/high reuse the opsx picks (coder/reviewer), top is the
+    // sole supplemental pick (slow), vision picks from image-capable candidates
+    // only. Roles outside the set resolve through OMP native chains. See
+    // lib/model-roles.ts design D5.
     let roleOverrides: Record<string, string> = {};
     let skippedRoles: SkippedRole[] = [];
-    if (filteredModels && filteredModels.length > 0) {
+    if (basePool && basePool.length > 0) {
         const pickString = (r: SelectorResult): string | undefined =>
             r.picked ? `${r.picked.provider}/${r.picked.id}` : undefined;
         const tierPicks: Partial<Record<TierName, string | undefined>> = {
+            // Guard pinning ran above: a pinned pick replaces the role result
+            // and therefore feeds the overlay payload (T4: application stays
+            // at the existing apply points — this only refreshes the cache).
             mid: pickString(selectorResults.coder),
             high: pickString(selectorResults.reviewer),
         };
-        for (const supplementalTier of ['tiny', 'low', 'top'] as const) {
-            const synthRole = `__tier_${supplementalTier}`;
+        const synthRole = '__tier_top';
+        const topPool = poolForSlot('top');
+        const topSlotTier: TierName = routing
+            ? applyBandOffset({ slow: 'top' }, routing.band, { stallActive: routing.stallActive }).slow as TierName
+            : 'top';
+        if (topPool && topPool.length > 0) {
             const result = selectModel({
                 role: synthRole,
-                models: filteredModels,
-                roleTiers: { [synthRole]: supplementalTier },
+                models: topPool,
+                // This slot feeds the write-set `slow` role: its target shifts
+                // with the band (top−1 under simple etc., design D3), while the
+                // role→slot mapping itself stays fixed.
+                roleTiers: { [synthRole]: topSlotTier },
                 tierOverrides: config.tierOverrides,
                 health: health ?? undefined,
                 allowlist: config.modelAllowlist,
                 planProviders: planSet,
+                paygLastResort: config.paygLastResort,
+                providerAuto: config.providerAuto,
+                providerAutoTiers: config.providerAutoTiers,
+                speedAware,
+                qualityPreference: routing?.qualityPreference,
             });
-            tierPicks[supplementalTier] = pickString(result);
+            tierPicks.top = pickString(result);
         }
         const capabilityPicks: Record<string, string | undefined> = {};
-        const visionModels = filteredModels.filter((m) => ROLE_CAPABILITY.vision(m));
+        // vision scope gates its capability candidate set only — it never
+        // contributes a tier slot.
+        const visionSource = scopeRoles?.includes('vision') ? filteredModels : basePool;
+        const visionModels = (visionSource ?? []).filter((m) => ROLE_CAPABILITY.vision(m));
         if (visionModels.length > 0) {
             const visionResult = selectModel({
                 role: 'vision',
                 models: visionModels,
-                roleTiers: { vision: 'high' },
+                // Write-set member: band offset shifts the in-pool preference
+                // (capability filter already ran — no incapable-model risk).
+                roleTiers: routing
+                    ? applyBandOffset({ vision: 'high' } as Record<string, TierName>, routing.band, { stallActive: routing.stallActive }) as Record<string, TierName>
+                    : { vision: 'high' },
                 tierOverrides: config.tierOverrides,
                 health: health ?? undefined,
                 allowlist: config.modelAllowlist,
                 planProviders: planSet,
+                paygLastResort: config.paygLastResort,
+                providerAuto: config.providerAuto,
+                providerAutoTiers: config.providerAutoTiers,
+                speedAware,
+                qualityPreference: routing?.qualityPreference,
             });
             capabilityPicks.vision = pickString(visionResult);
         }
-        const plan = buildRoleOverridePlan(
-            { knownRoleIds, ompRoleTiers: config.ompRoleTiers, tierPicks, capabilityPicks },
-            (m) => getLogger().warn(m),
-        );
+        const plan = buildRoleOverridePlan({ ompRoleTiers: config.ompRoleTiers, tierPicks, capabilityPicks });
         roleOverrides = plan.overrides;
         skippedRoles = plan.skipped;
     }
-    return { selectorResults, roleModels, roleConfigs, roleKind, roleOverrides, skippedRoles };
-}
-function formatModelChoicesMarkdown(sel: SelectionContext, suffix: string = '', primaryModel?: Model<Api>): string {
-    const rows: string[] = [];
-    let totalModelCount = 0;
-    if (primaryModel) {
-        const score = scoreModelWithProvider(primaryModel.provider, primaryModel.id, primaryModel.name, undefined);
-        rows.push(
-            `| 🏠 **主会话** | **${primaryModel.provider}/${primaryModel.id}** | ${score.tier} | 当前活跃模型 (tier=${score.tier}) |`,
-        );
-    }
-    for (const role of OPSX_ROLES) {
-        const r = sel.selectorResults[role];
-        if (!r) continue;
-        totalModelCount += r.allCandidates.length;
-        const icon = r.picked ? '✅' : '❌';
-        const configLabel = sel.roleConfigs[role];
-        const displayRole = configLabel ? `${role} (${configLabel})` : role;
-        const model = r.picked ? `${r.picked.provider}/${r.picked.id}` : (sel.roleModels[role] ?? '(none)');
-        const detail = r.pickedReason ?? r.decision;
-        rows.push(`| ${icon} **${displayRole}** | **${model}** | ${r.expectedTier} | ${detail} |`);
-    }
-    if (rows.length === 0) return `*模型选择${suffix}: no data*`;
-    return [
-        '| 智能体 | 模型 | 期望档位 | 详情 |',
-        '|---|---|---|---|',
-        ...rows,
-        '',
-        `*${totalModelCount} 个 model 参与评分 · \`/pick-model refresh\` 强制重选*`,
-    ].join('\n');
-}
-
-/** Format per-family per-tier model choices as a markdown table. */
-function formatFamilyTierMarkdown(sel: SelectionContext): string {
-    // Group (provider, tier) → best model by reputation
-    const byFamily = new Map<string, Map<string, { modelId: string; rep: number; rank: number }>>();
-    for (const role of OPSX_ROLES) {
-        const r = sel.selectorResults[role];
-        if (!r) continue;
-        for (const c of r.allCandidates) {
-            if (c.exhausted) continue;
-            const fam = c.model.provider;
-            const tier = c.tier;
-            if (!byFamily.has(fam)) byFamily.set(fam, new Map());
-            const tierMap = byFamily.get(fam)!;
-            const existing = tierMap.get(tier);
-            if (!existing || c.reputation > existing.rep || (c.reputation === existing.rep && c.rank > existing.rank)) {
-                tierMap.set(tier, { modelId: c.model.id, rep: c.reputation, rank: c.rank });
-            }
-        }
-    }
-
-    const rows: string[] = [];
-    const families = [...byFamily.keys()].sort();
-    for (const fam of families) {
-        const tierMap = byFamily.get(fam)!;
-        const parts: string[] = [];
-        for (const tier of ['top', 'high', 'mid', 'low', 'tiny']) {
-            const m = tierMap.get(tier);
-            if (!m) continue;
-            const shortId = m.modelId.length > 35 ? m.modelId.slice(0, 32) + '...' : m.modelId;
-            parts.push(`${tier}→${shortId}`);
-        }
-        if (parts.length === 0) continue;
-        rows.push(`**${fam}**: ${parts.join('  ')}`);
-    }
-    if (rows.length === 0) return '*No models available*';
-    return rows.join('\n');
+    return { selectorResults, roleModels, roleConfigs, roleKind, roleOverrides, skippedRoles, paygLastResort: config.paygLastResort, routingBand: routing?.band };
 }
+// change: pick-model-ux — choices/switch/refresh/reset output rendering lives
+// in lib/pick-model-render.ts (shared compact block renderer); the former
+// formatModelChoicesMarkdown / formatFamilyTierMarkdown markdown tables were
+// migrated there.
 
 // ── process-wide usage recorder singleton ──────────────────────────
 // This IS a process-wide singleton: the harness rebinds the same evaluated
@@ -540,6 +741,161 @@ const sessionUsageRecorder: SessionUsageRecorder = createSessionUsageRecorder({
     onDelta: mirrorSessionDelta,
 });
 
+// ── adaptive provider concurrency (process-wide owner) ──────────────
+// Ownership model (the same P0 invariant as plugins/omp-whip/index.ts): the
+// host re-runs this factory once per in-process subagent binding, so an owner
+// kept in the closure would be claimed by EVERY binding — each starting its
+// own control loop, lease and state file against the same config root. The
+// owner therefore lives at module scope (shared by every binding in this
+// process, and re-imported fresh by isolated workers), and the session id
+// captured at claim time is the identity gate for `session_shutdown`: without
+// it, a subagent exiting would tear down the root's loop and release its lease.
+interface OwnedConcurrency {
+    /** Session id captured when this process claimed the control loop. */
+    sessionId: string;
+    controller: ConcurrencyController;
+}
+
+let ownedConcurrency: OwnedConcurrency | null = null;
+
+/** Test-only: reset the module-level control-loop owner (production never calls this). */
+export function __resetOwnedConcurrencyForTests(): void {
+    ownedConcurrency = null;
+}
+
+/** Test-only: read the module-level control-loop owner (production never calls this). */
+export function __getOwnedConcurrencyForTests(): OwnedConcurrency | null {
+    return ownedConcurrency;
+}
+
+/**
+ * Test-only seam (mirrors usage-poller's `_set*ForTest`): overrides the
+ * transport the assembly injects into the control loop. `undefined` derives it
+ * from `redis_*` config (production), `null` forces the Redis-free path so the
+ * file lease / degradation behavior is testable without a local Redis.
+ */
+let concurrencyRedisPortForTests: ConcurrencyRedisPort | null | undefined;
+export function _setConcurrencyRedisPortForTest(port: ConcurrencyRedisPort | null | undefined): void {
+    concurrencyRedisPortForTests = port;
+}
+
+/**
+ * Test-only seam: the home directory the assembly reads its **global**
+ * `opsx.yml` layer from (`<home>/.omp/agent/opsx.yml`). `undefined` = the real
+ * `homedir()` (production); a path makes the factory hermetic, so a suite that
+ * starts the loop cannot inherit whatever the developer happens to have set
+ * globally — `concurrency_enabled: false` there would otherwise silently disable
+ * every factory-level case.
+ */
+let opsxGlobalHomeForTests: string | undefined;
+export function _setOpsxGlobalHomeForTest(homeDir: string | undefined): void {
+    opsxGlobalHomeForTests = homeDir;
+}
+
+/** Process-stable lease owner id: `pid` + process start time (design D5). */
+const PROCESS_OWNER = `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1000)}`;
+
+/**
+ * Keys declared under `providers.maxInFlightRequests` in the shared
+ * `config.yml`. Only key *presence* is read here — the writer owns value
+ * validation, so a key whose value is not a positive integer still enters the
+ * managed set (its baseline reads as「无现值」→ `concurrency_start`).
+ */
+function readLimitKeys(configPath: string): string[] {
+    let text: string | null;
+    try {
+        text = nodeWriterFileSystem.readFile(configPath);
+    } catch {
+        return [];
+    }
+    if (text === null) return [];
+    try {
+        const limits = (YAML.parse(text) as { providers?: { maxInFlightRequests?: unknown } } | null)
+            ?.providers?.maxInFlightRequests;
+        if (!limits || typeof limits !== 'object' || Array.isArray(limits)) return [];
+        return Object.keys(limits as Record<string, unknown>);
+    } catch {
+        return [];
+    }
+}
+
+/** Map the resolved `concurrency_*` config onto the tuner's injected knobs. */
+function tunerOptionsFromConfig(cfg: ResolvedOpsxConfig): TunerOptions {
+    return {
+        floor: cfg.concurrency_floor,
+        ceiling: cfg.concurrency_ceiling,
+        start: cfg.concurrency_start,
+        upMs: cfg.concurrency_up_ms,
+        downMs: cfg.concurrency_down_ms,
+        k: cfg.concurrency_latency_k,
+        minSamples: cfg.concurrency_min_samples,
+        queueWaitHighMs: cfg.concurrency_queue_wait_high_ms,
+        queueWaitWindowMs: cfg.concurrency_queue_wait_window_ms,
+        evalIntervalMs: cfg.concurrency_eval_interval_ms,
+        decayAfterMs: cfg.concurrency_decay_after_ms,
+        ewmaAlpha: TUNER_DEFAULTS.ewmaAlpha,
+    };
+}
+
+/** Assembly seams for the control loop; production passes host/plugin values, tests inject. */
+export interface ConcurrencyAssemblyDeps {
+    /** Config root `config.yml` the writer reads/merges/writes. */
+    configPath: string;
+    /** Agent dir the log reader / `model_perf` path derive from. */
+    agentDir?: string;
+    /** Host settings port for the hot-apply (`settings.override`). */
+    settings?: SettingsPort | null;
+    /** Cross-process ① aggregation channel (`null` → local-only + warn). */
+    redis?: ConcurrencyRedisPort | null;
+    /** Warn sink (the host logger). */
+    warn: (message: string) => void;
+    /** Injected clock (tests). */
+    now?: () => number;
+    /** Lease owner id (defaults to this process's `pid:startTime`). */
+    owner?: string;
+    /** Managed-set override (tests). */
+    managedProviders?: readonly string[];
+    /** Lease factory seam (tests). */
+    leaseFactory?: ConcurrencyLeaseFactory;
+}
+
+/**
+ * Build the control loop for this config root, or `null` when it MUST NOT run:
+ * `concurrency_enabled: false` (spec「配置面与降级」: no setting write, no lease
+ * competition, no state-file write) or no managed provider to control. The
+ * managed set is `concurrency_providers` ∪ the shared `providers.
+ * maxInFlightRequests` keys (spec「受管集合」).
+ *
+ * Ports are wired here: the node fs port, the derived sqlite `model_perf` port
+ * and the file/Redis lease come from the controller's production defaults; the
+ * host settings `override` and the existing Redis client are injected.
+ */
+export function createConcurrencyControllerIfEnabled(
+    cfg: ResolvedOpsxConfig,
+    deps: ConcurrencyAssemblyDeps,
+): ConcurrencyController | null {
+    if (!cfg.concurrency_enabled) return null;
+    const managedProviders = deps.managedProviders
+        ?? resolveManagedProviders(cfg.concurrency_providers, readLimitKeys(deps.configPath));
+    if (managedProviders.length === 0) return null;
+    return createConcurrencyController({
+        configPath: deps.configPath,
+        managedProviders,
+        tuner: tunerOptionsFromConfig(cfg),
+        now: deps.now ?? (() => Date.now()),
+        fs: createNodeFsPort(),
+        owner: deps.owner ?? PROCESS_OWNER,
+        ...(deps.agentDir ? { agentDir: deps.agentDir } : {}),
+        redis: deps.redis ?? null,
+        settings: deps.settings ?? null,
+        ceilingByProvider: cfg.concurrency_ceiling_by_provider,
+        warn: deps.warn,
+        leaseTtlMs: cfg.concurrency_lease_ttl_ms,
+        writeMinIntervalMs: cfg.concurrency_write_min_interval_ms,
+        ...(deps.leaseFactory ? { leaseFactory: deps.leaseFactory } : {}),
+    });
+}
+
 // ── plugin entry ────────────────────────────────────────────────────
 
 export default (pi: ExtensionAPI) => {
@@ -558,11 +914,7 @@ export default (pi: ExtensionAPI) => {
     applyEditVariantPin(pi, { 'deepseek-v4-flash': 'replace' });
     const directory = process.cwd();
     const warn = (msg: string) => pi.logger.warn(msg);
-    // Roles known to the host at the moment of a (re)selection: computed per
-    // call so custom roles appearing after startup are covered on
-    // refresh/reset/selector/tick.
-    const currentKnownRoleIds = (): string[] => safeGetKnownRoleIds(pi.pi?.settings);
-    const opsxConfig = readOpsxSettings(directory, warn);
+    const opsxConfig = readOpsxSettings(directory, warn, opsxGlobalHomeForTests ?? homedir());
     // Static orchestration rules — built once, reused every turn for cache stability.
     const STATIC_PROMPT = buildStaticPrompt();
     let initialModel: { provider: string; id: string } | null = null;
@@ -585,27 +937,144 @@ export default (pi: ExtensionAPI) => {
     // and `/pick-model reset` restores it to opsxConfig.
     let familyConstraint: FamilyConstraint | null = null;
     let effectiveConfig: ResolvedOpsxConfig = opsxConfig;
+    // Session-start autoselect once-flag. Factory closure, not module-level:
+    // rebind instances (in-process task subagents) re-run the factory and each
+    // gets its own flag — the owner gate below is what actually excludes them.
+    let autoApplied = false;
+
+    // ── W4 difficulty routing state (change: difficulty-routed-selection) ──
+    // Factory closure, lazily keyed by session id (design D4: NOT hung on any
+    // session_start handler — that region belongs to the usage/autoselect
+    // owners). `band/confidence` come from classifyTaskSafe on the
+    // before_agent_start path; `stall` is the read-only sampling window fed
+    // by the tool_execution_start handler below.
+    let routingState: {
+        sessionId: string;
+        band: TaskBand;
+        confidence: number;
+        stallActive: boolean;
+        stall: StallRuntime | null;
+    } | null = null;
+
+    const routingStateFor = (sessionId: string) => {
+        if (!routingState || routingState.sessionId !== sessionId) {
+            routingState = {
+                sessionId,
+                band: 'standard',
+                confidence: 0,
+                stallActive: false,
+                stall: opsxConfig.stallEscalation.enabled ? createStallRuntime(opsxConfig.stallEscalation) : null,
+            };
+        }
+        return routingState;
+    };
+
+    /**
+     * Routing runtime handed to computeSelectionSync (design D8.5). All
+     * switches off + balanced → `undefined` (the zero-drift contract: the
+     * selection path never even sees a routing object). `explicit` marks the
+     * /pick-model command paths — guard bypassed, no fresh classification,
+     * band annotations suppressed; the session band still drives offsets.
+     */
+    const routingRuntimeFor = (ctx: ExtensionContext, explicit: boolean): RoutingRuntime | undefined => {
+        const qp = opsxConfig.qualityPreference;
+        const anyOn = opsxConfig.difficultyRouting.enabled
+            || opsxConfig.stallEscalation.enabled
+            || opsxConfig.continuityGuard.enabled
+            || qp !== 'balanced';
+        if (!anyOn) return undefined;
+        const st = routingStateFor(ctx.sessionManager?.getSessionId?.() ?? '');
+        return {
+            band: st.band,
+            confidence: st.confidence,
+            stallActive: st.stallActive,
+            explicit,
+            qualityPreference: qp,
+            // Incumbent read BEFORE the recompute reassigns `selection` — the
+            // pin decision compares against the previous context only.
+            guard: opsxConfig.continuityGuard.enabled && !explicit
+                ? { weight: opsxConfig.continuityGuard.weight, incumbent: selection, priorBand: selection?.routingBand ?? null }
+                : undefined,
+        };
+    };
+
+    // Same-account regional variant state (china-config): resolved fresh at
+    // every recompute path from the live pool composition — no cache and
+    // therefore no invalidation problem. The result feeds both
+    // computeSelectionSync and the health key so the two cannot drift.
+    // Judgment = variant-table membership + both sides in the effective pool
+    // + strictly equal API keys (same-account proof; unequal/missing keys →
+    // both doors coexist).
+    const resolveVariantState = async (
+        models: { provider: string; id: string }[] | null | undefined,
+        getApiKey: ((provider: string) => Promise<string | undefined>) | undefined,
+        reach: { unreachable?: Set<string>; availableByProvider?: Map<string, string[] | null> } = {},
+    ): Promise<VariantCollapseResult> => {
+        const idle: VariantCollapseResult = { collapsedProviders: new Set<string>(), dropped: null, kept: null };
+        if (!models || models.length === 0) return idle;
+        // Trigger condition evaluates on the EFFECTIVE pool (spec: 双变体同时
+        // 在池才触发——reachability / 静态排除 / provider_models 收窄 /
+        // allowlist 已滤掉一侧时不触发): the same provider-level filters
+        // computeSelectionSync applies to basePool (minus the collapse
+        // itself), plus the allowlist reduction. provider_models participates:
+        // a kept side narrowed to zero must not count as "in pool", or the
+        // collapse would drop the other side and leave the account unservable.
+        const providerModelMap = Object.keys(opsxConfig.providerModels).length > 0
+            ? new Map(Object.entries(opsxConfig.providerModels))
+            : undefined;
+        const providersInPool = new Set(
+            filterSelectableModels(models, {
+                blockedSelectors: regionBlockedModels,
+                unreachableProviders: reach.unreachable,
+                availableByProvider: reach.availableByProvider,
+                excludedProviders: opsxConfig.excluded_providers,
+                providerModels: providerModelMap,
+            })
+                .filter((m) => providerSurvivesAllowlist(m.provider, m.id, opsxConfig.modelAllowlist))
+                .map((m) => m.provider),
+        );
+        return resolveVariantCollapse({
+            china: opsxConfig.china,
+            providersInPool,
+            getApiKey: await resolveVariantKeyLookup(providersInPool, getApiKey),
+        });
+    };
 
     const buildSelectionHealthKey = (
         health: Map<string, ProviderHealth> | null,
         reach: { unreachable: Set<string>; availableByProvider: Map<string, string[] | null> },
         fc: FamilyConstraint | null,
+        collapsed: ReadonlySet<string> = new Set<string>(),
     ): string => {
-        return selectionHealthKeyFor(health, reach, fc, regionBlockedModels);
+        return selectionHealthKeyFor(health, reach, fc, regionBlockedModels, collapsed);
     };
 
     const formatFamilyConstraint = (fc: FamilyConstraint | null): string => {
-        if (!fc) return '';
         const parts: string[] = [];
-        if (fc.selectors && fc.selectors.length > 0) parts.push(`selectors=${fc.selectors.join(',')}`);
-        if (fc.excludeSelectors.length > 0) parts.push('china=on');
+        if (fc?.selectors && fc.selectors.length > 0) parts.push(`selectors=${fc.selectors.join(',')}`);
+        // china=on when the session constraint carries the exclusion OR the
+        // config default is on — the config-derived segment renders even
+        // without any selector constraint (spec: 配置派生 china=on 无约束也显示).
+        if ((fc?.excludeSelectors.length ?? 0) > 0 || effectiveConfig.china) parts.push('china=on');
+        if (fc?.roles && fc.roles.length > 0) parts.push(`scope=${fc.roles.join(',')}`);
         return parts.join(' · ');
     };
 
-    /** Copy of opsxConfig with every role forced to auto — covers pinned roles. */
-    const buildEffectiveConfig = (): ResolvedOpsxConfig => {
+    /**
+     * Copy of opsxConfig with the constrained roles forced to auto — covers
+     * pinned roles. `scopedSlots === null` = global constraint (every role
+     * auto, status-quo shape); scoped constraints only force the roles whose
+     * consumed tier slot is in scope (coder feeds mid, the rest high) —
+     * out-of-scope roles keep their opsx.yml value, so synthPinnedResult
+     * keeps their pin and auto roles draw the unconstrained pool. The no-arg
+     * poller/assembly call sites keep the all-auto semantics.
+     */
+    const buildEffectiveConfig = (scopedSlots: ReadonlySet<TierName> | null = null): ResolvedOpsxConfig => {
         const roles = {} as Record<Role, RoleValue>;
-        for (const role of OPSX_ROLES) roles[role] = { kind: 'auto' };
+        for (const role of OPSX_ROLES) {
+            const slot: TierName = role === 'coder' ? 'mid' : 'high';
+            roles[role] = scopedSlots === null || scopedSlots.has(slot) ? { kind: 'auto' } : opsxConfig.roles[role];
+        }
         return { ...opsxConfig, roles };
     };
     const startPollerFor = async (ctx: ExtensionContext, onTick?: () => void): Promise<void> => {
@@ -630,7 +1099,7 @@ export default (pi: ExtensionAPI) => {
         });
     };
 
-    const ensureSelection = (ctx: ExtensionContext, force = false): Promise<SelectionContext> => {
+    const ensureSelection = (ctx: ExtensionContext, force = false, explicit = false): Promise<SelectionContext> => {
         if (selectionPromise && !force) return selectionPromise;
         selectionPromise = (async () => {
             await startPollerFor(ctx);
@@ -644,7 +1113,11 @@ export default (pi: ExtensionAPI) => {
             firstUnreachableProviders = reach.unreachable;
             availableByProvider = reach.availableByProvider;
             const health = getSharedUsage()?.health ?? null;
-            const key = buildSelectionHealthKey(health, reach, familyConstraint);
+            const getApiKey = ctx.modelRegistry?.getApiKeyForProvider
+                ? (provider: string) => ctx.modelRegistry.getApiKeyForProvider(provider)
+                : undefined;
+            const collapsed = (await resolveVariantState(models, getApiKey, reach)).collapsedProviders;
+            const key = buildSelectionHealthKey(health, reach, familyConstraint, collapsed);
             if (!force && selection && selectionHealthKey === key) return selection;
             // Thread effectiveConfig + familyConstraint so family/pinned constraints
             // survive this recompute (ensureSelection is one of the shared recompute paths).
@@ -652,11 +1125,13 @@ export default (pi: ExtensionAPI) => {
                 effectiveConfig,
                 models,
                 health,
-                currentKnownRoleIds(),
                 regionBlockedModels,
                 reach.unreachable,
                 reach.availableByProvider,
                 familyConstraint,
+                collapsed,
+                warn,
+                routingRuntimeFor(ctx, explicit),
             );
             selection = sel;
             selectionHealthKey = key;
@@ -688,6 +1163,35 @@ export default (pi: ExtensionAPI) => {
     // would be overwritten by whichever instance starts last.
     let recordsOwnUsage = false;
 
+    // ── adaptive provider concurrency: host seams ─────────────────
+    /** Host settings port for the control loop's hot-apply (narrowed to `override`). */
+    const hostSettingsPort = (): SettingsPort | null => {
+        const settings = pi.pi?.settings as unknown as { override?: unknown } | undefined;
+        return settings && typeof settings.override === 'function' ? (settings as SettingsPort) : null;
+    };
+    /** Config root + agent dir for the control loop (host settings, else `~/.omp/agent`). */
+    const resolveConcurrencyPaths = (): { agentDir: string; configPath: string } => {
+        let agentDir = '';
+        try {
+            agentDir = (pi.pi?.settings as { getAgentDir?: () => string } | undefined)?.getAgentDir?.() ?? '';
+        } catch {
+            agentDir = '';
+        }
+        if (!agentDir) agentDir = join(homedir(), '.omp', 'agent');
+        return { agentDir, configPath: resolveGlobalConfigPath(agentDir) ?? join(agentDir, 'config.yml') };
+    };
+    /** The existing Redis channel as the ① aggregation transport (no new command surface). */
+    const aggregationRedisPort = (cfg: ResolvedOpsxConfig): ConcurrencyRedisPort | null => {
+        if (!cfg.redis_enabled) return null;
+        const client = new RedisClient({
+            host: cfg.redis_host,
+            port: cfg.redis_port,
+            connectTimeoutMs: cfg.redis_connect_timeout_ms,
+            commandTimeoutMs: cfg.redis_command_timeout_ms,
+        });
+        return { pipeline: (commands) => client.pipeline(commands) };
+    };
+
     // ── shared usage poller + widget ──────────────────────────────
     pi.on('session_start', async (_event, ctx) => {
         try {
@@ -821,8 +1325,23 @@ export default (pi: ExtensionAPI) => {
             // Last unix second already sampled by onTick (per session). Drives
             // the catch-up loop that backfills every skipped second with zeros.
             let lastSampledSec: number | undefined;
-            const render = () => {
-                const { reports, placeholderIds, active, show } = resolveActiveProviders();
+            const render = async () => {
+                const resolved = resolveActiveProviders();
+                // Same-account regional collapse on the usage bar (china-config):
+                // a collapsed side is a duplicate door into the quota the kept
+                // side already displays, so dropping its row loses nothing.
+                // In-pool for usage = usage data or credentials present (the
+                // `active` union) — model candidates are not required. The
+                // strict key-equality gate matches the pool path: unequal or
+                // missing keys keep BOTH rows (labels 智谱 / Z.AI distinguish).
+                const activeSet = new Set(resolved.active);
+                const collapsed = resolveVariantCollapse({
+                    china: opsxConfig.china,
+                    providersInPool: activeSet,
+                    getApiKey: await resolveVariantKeyLookup(activeSet, getApiKey),
+                }).collapsedProviders;
+                const { reports, placeholderIds, active } = collapseUsageView(resolved.reports, resolved.placeholderIds, resolved.active, collapsed);
+                const show = resolved.show;
                 const state = getSharedUsage();
                 const loadingProviders = state?.loadingProviders ?? new Set<string>();
                 if (!show) {
@@ -852,14 +1371,28 @@ export default (pi: ExtensionAPI) => {
                 for (const p of active) {
                     consumptionTracks.set(p, { samples: getConsumptionSamples(p) });
                 }
+                // Adaptive-concurrency inline tokens: the controller's per-provider
+                // view (`stateFor`) rendered as `L/ceiling` right after the provider
+                // name on BOTH render paths. Providers the controller does not manage
+                // stay absent from the map — and an empty map keeps the widget
+                // byte-identical to the pre-token output.
+                const concurrencyViews = new Map<string, ConcurrencyInlineView>();
+                if (ownedConcurrency) {
+                    const degraded = ownedConcurrency.controller.leaseMode() === 'readonly';
+                    for (const p of active) {
+                        const view = ownedConcurrency.controller.stateFor(p);
+                        if (view) concurrencyViews.set(p, { limit: view.limit, ceiling: view.ceiling, degraded });
+                    }
+                }
+                const inlineConcurrency = concurrencyViews.size > 0 ? concurrencyViews : undefined;
                 if (ctx.hasUI) {
-                    ctx.ui.setWidget(key, createUsageWidget(reports, placeholderIds, loadingProviders, consumptionTracks, usageEstimates, getExhaustedProviders()), {
+                    ctx.ui.setWidget(key, createUsageWidget(reports, placeholderIds, loadingProviders, consumptionTracks, usageEstimates, getExhaustedProviders(), inlineConcurrency), {
                         placement: 'belowEditor',
                     });
                 } else {
                     if (ctx.ui) {
                         const cols = (process.stdout.columns ?? 120) - 3;
-                        const lines = renderUsageReports(reports, cols, undefined, placeholderIds, loadingProviders, consumptionTracks, usageEstimates, getExhaustedProviders());
+                        const lines = renderUsageReports(reports, cols, undefined, placeholderIds, loadingProviders, consumptionTracks, usageEstimates, getExhaustedProviders(), inlineConcurrency);
                         ctx.ui.setWidget(key, lines.length > 0 ? lines : undefined, { placement: 'belowEditor' });
                     }
                 }
@@ -870,8 +1403,41 @@ export default (pi: ExtensionAPI) => {
             // subagent via cache backflow), and re-renders the widget. It never
             // recomputes a selection, never applies overrides, never setModel.
             const cfg = buildEffectiveConfig();
+            // ── claim the process-wide adaptive-concurrency control loop ──
+            // Only the owning session starts it (same rule as the render tick
+            // above), and the module-level `ownedConcurrency` gate keeps a
+            // subagent binding — or a re-entrant session_start — from starting a
+            // second loop and lease against the same config root. The
+            // `concurrency_enabled` check also short-circuits here so the
+            // disabled path allocates nothing (no transport, no config read).
+            if (claimsOwnership && ownedConcurrency === null && cfg.concurrency_enabled) {
+                const paths = resolveConcurrencyPaths();
+                const controller = createConcurrencyControllerIfEnabled(cfg, {
+                    configPath: paths.configPath,
+                    agentDir: paths.agentDir,
+                    settings: hostSettingsPort(),
+                    redis: concurrencyRedisPortForTests !== undefined ? concurrencyRedisPortForTests : aggregationRedisPort(cfg),
+                    warn,
+                });
+                if (controller) {
+                    ownedConcurrency = {
+                        sessionId: ctx.sessionManager?.getSessionId?.() ?? '',
+                        controller,
+                    };
+                }
+            }
             const onTick = () => {
-                // Fire-and-forget status probe: do not block the tick.
+                // Adaptive concurrency rides the SAME render tick — it owns no
+                // timer; the controller's absolute-time gate (`concurrency_eval_
+                // interval_ms`) decides whether this tick evaluates.
+                const controller = ownedConcurrency?.controller;
+                if (controller) {
+                    void controller.onTick().catch((e) => warn(`[omp-opsx-addon] concurrency tick error: ${e}`));
+                }
+                // Fire-and-forget status probe: do not block the tick. Deliberately
+                // NOT filtered by the regional collapse (china-config): probing the
+                // collapsed side keeps its reachability record fresh, so the
+                // selection-pool premise of the collapse never rides stale data.
                 const { placeholderIds, active } = resolveActiveProviders();
                 let models: { id: string; provider: string; baseUrl?: string }[] = [];
                 try {
@@ -897,7 +1463,7 @@ export default (pi: ExtensionAPI) => {
                         timeoutMs: cfg.probe_timeout_ms,
                         excluded: cfg.excluded_providers,
                     },
-                }).then((written) => { if (written > 0) render(); }).catch(() => {});
+                }).then((written) => { if (written > 0) void render().catch(() => {}); }).catch(() => {});
 
                 sessionUsageRecorder.flush();
                 // Waveform source = per-second consumption sequence (timestamped
@@ -923,7 +1489,7 @@ export default (pi: ExtensionAPI) => {
                     }
                 }
                 lastSampledSec = lastSec;
-                render();
+                void render().catch((e) => warn(`[omp-opsx-addon] usage render error: ${e}`));
             };
             await startSharedPoller(auth, DIRECT_FETCHERS, getApiKey, {
                 onTick: claimsOwnership ? onTick : undefined,
@@ -945,10 +1511,10 @@ export default (pi: ExtensionAPI) => {
             // exposes no `signal`, so per-session abort cleanup never fires —
             // ownership above, not teardown hooks, keeps the singletons sane.)
             if (activeResizeHandler) process.stdout.off('resize', activeResizeHandler);
-            const onResize = () => render();
+            const onResize = () => void render().catch(() => {});
             activeResizeHandler = onResize;
             process.stdout.on('resize', onResize);
-            render();
+            void render().catch((e) => warn(`[omp-opsx-addon] usage render error: ${e}`));
         } catch (e) {
             warn(`[omp-opsx-addon] usage poller error: ${e}`);
         }
@@ -1046,25 +1612,76 @@ export default (pi: ExtensionAPI) => {
                     }
                 }
             }
+            // The control loop belongs to ONE session: only the owner's own exit
+            // stops it. A subagent's shutdown MUST NOT tear down the root's loop
+            // and release its lease (identity gate, see `ownedConcurrency`).
+            if (ownedConcurrency && sid === ownedConcurrency.sessionId) {
+                const owned = ownedConcurrency;
+                ownedConcurrency = null;
+                try {
+                    await owned.controller.shutdown();
+                } catch (e) {
+                    warn(`[omp-opsx-addon] concurrency shutdown error: ${e}`);
+                }
+            }
         } catch {
             /* best-effort */
         }
     });
     // ── session lifecycle ─────────────────────────────────────────
-    // Pick-model is manual: `/pick-model refresh`. Session start does not pick or setModel.
+    // Pick-model stays manual (`/pick-model refresh`); with autoselect_on_start
+    // (default true) the session_start handler below additionally applies the
+    // configured selection once at startup, so it already holds for turn one.
     const changeScanner = createCachedScanner(30_000);
 
+    // ── W4 routing segment (change: difficulty-routed-selection) ──
+    // The gate wraps ONLY this segment: the handler's existing body below
+    // (systemPrompt injection + change scanning) runs unchanged under every
+    // switch combination — gating never retires the whole handler (P1-1).
+    // Both gates mirror the existing instance rules: the feature switches
+    // (both off → straight out, zero behavior) and the main-instance rule
+    // (subagent bindings never classify or sample). The band/stall comparison
+    // decides whether one force recompute happens this turn; otherwise the
+    // existing health-key caching applies untouched.
+    const runRoutingSegment = async (event: { prompt: string }, ctx: ExtensionContext): Promise<void> => {
+        if (!opsxConfig.difficultyRouting.enabled && !opsxConfig.stallEscalation.enabled) return;
+        if (!(ctx.hasUI || !hasTickOwner())) return;
+        const st = routingStateFor(ctx.sessionManager?.getSessionId?.() ?? '');
+        const classification = opsxConfig.difficultyRouting.enabled
+            ? classifyTaskSafe(event.prompt)
+            : { band: 'standard' as TaskBand, confidence: 0 };
+        // Stall episode evaluation for this turn (design D4: anchored on the
+        // newest signature, escalated latches once per episode). The window
+        // content is maintained by the tool_execution_start handler below.
+        let stallActive = false;
+        if (opsxConfig.stallEscalation.enabled && st.stall) {
+            stallActive = evaluateStall(st.stall).active;
+        }
+        const prevBand = st.band;
+        const prevStallActive = st.stallActive;
+        st.band = classification.band;
+        st.confidence = classification.confidence;
+        st.stallActive = stallActive;
+        const bandMoved = opsxConfig.difficultyRouting.enabled && prevBand !== classification.band;
+        const stallMoved = opsxConfig.stallEscalation.enabled && prevStallActive !== stallActive;
+        if (bandMoved || stallMoved) await ensureSelection(ctx, true);
+    };
+
     pi.on('before_agent_start', async (event, ctx) => {
         try {
+            // Best-effort isolation (review P2): the segment's force-recompute
+            // awaits poller/Redis and cache-fs paths absent from this handler
+            // pre-W4; a rejection must never reach the outer catch and strip
+            // STATIC_PROMPT + the change-scan segment for the turn.
+            try {
+                await runRoutingSegment(event, ctx);
+            } catch (segErr) {
+                warn(`[omp-opsx-addon] routing segment error: ${segErr}`);
+            }
             // This fallback call is intentionally NOT threaded with familyConstraint:
             // it prefers the cached `selection`, and the fallback passes models=null so
             // filterSelectableModels' family branch never runs — it is not a reselect path.
-            const sel = selection ?? computeSelectionSync(
-                opsxConfig,
-                null,
-                null,
-                safeGetKnownRoleIds(pi.pi?.settings),
-            );
+            const sel = selection ?? computeSelectionSync(opsxConfig, null, null);
             const changes = await changeScanner.scanChanges(directory, 'doing');
             // Layered injection: STATIC_PROMPT is byte-identical every turn → prefix cache
             // hit for [omp-base + skills + static]. Only the dynamic tail re-prefills.
@@ -1087,11 +1704,41 @@ export default (pi: ExtensionAPI) => {
                 frontmatter('planner'),
                 frontmatter('proposal-reviewer'),
             );
-            warn('[omp-opsx-addon] agents ready (pick-model idle until /pick-model refresh)');
+            warn('[omp-opsx-addon] agents ready (selection auto-applies at session start unless autoselect_on_start: false; /pick-model to re-run)');
         } catch (e) {
             warn('[omp-opsx-addon] installAgents error: ' + e);
         }
     });
+
+    // Session-start autoselect: apply the configured selection once so the
+    // first turn already follows it — role overrides through the same apply
+    // path as /pick-model, and the main session moved to the reviewer pick
+    // (no-op when already equal; undefined pick → skip). The once-flag is also
+    // what keeps a later in-session /model switch authoritative: this path
+    // never runs again for the instance, so nothing rewrites the user's
+    // choice. Owner gate before the once-flag: subagent bindings re-run the
+    // factory with independent closures (a closure once-flag cannot see
+    // them), so the process-level owner rule decides — same rule as the
+    // usage/render claim in the first handler. Awaited, never fire-and-forget:
+    // a detached apply would race the user's first prompt onto the native
+    // model. Pins (opsx.yml agents.*) bypass selection via synthPinnedResult
+    // and are never touched here.
+    pi.on('session_start', async (_event, ctx) => {
+        if (!opsxConfig.autoselectOnStart) return;
+        if (!(ctx.hasUI || !hasTickOwner())) return;
+        if (autoApplied) return;
+        autoApplied = true;
+        try {
+            const sel = await ensureSelection(ctx);
+            applyRoleModel(sel);
+            const picked = sel.selectorResults.reviewer?.picked;
+            if (picked && ctx.model && `${ctx.model.provider}/${ctx.model.id}` !== `${picked.provider}/${picked.id}`) {
+                await pi.setModel(picked);
+            }
+        } catch (e) {
+            warn(`[omp-opsx-addon] session-start autoselect error: ${e}`);
+        }
+    });
     // ── Diagnostic-only error path (429/403; never auto-switches) ─
     const diagnoseProviderError = async (ctx: ExtensionContext, source: string, errorType: '429' | '403'): Promise<void> => {
         const currentModel = ctx.model;
@@ -1105,6 +1752,10 @@ export default (pi: ExtensionAPI) => {
         // without a usage fetcher — record it in the process-local binary status
         // so the placeholder column reads 耗尽 (see lib/provider-status.ts).
         markExhausted(canonical);
+        // Adaptive-concurrency signal ①: hand the observed explicit failure to
+        // the control loop as a COUNTED event only. The diagnosis text and the
+        // "never auto-switch provider" policy below are unchanged (task 6.5).
+        ownedConcurrency?.controller.noteExplicitFailure(canonical, errorType);
         // Force-refresh just this provider (bypassing the 10s floor) so the
         // diagnosis reflects current quota.
         if (auth) await pokeProvider(auth, DIRECT_FETCHERS, getApiKey, { providers: [canonical], force: true });
@@ -1148,6 +1799,44 @@ export default (pi: ExtensionAPI) => {
             warn(`[omp-opsx-addon] tool_execution_end error: ${e}`);
         }
     });
+    // ── W4 stall sampling (change: difficulty-routed-selection; read-only) ──
+    // Freshly registered handlers (unlike before_agent_start, which predates
+    // W4): the first-line switch gate IS the whole disabled behavior — zero
+    // sampling, zero state writes. Main-instance gate mirrors autoselect:
+    // subagent bindings never sample (design D4). The window only shapes the
+    // NEXT selection recompute's inputs; nothing here switches a live model
+    // and the 429/403 diagnostics above are untouched (T4).
+    pi.on('tool_execution_start', async (event, ctx) => {
+        if (!opsxConfig.stallEscalation.enabled) return;
+        if (!(ctx.hasUI || !hasTickOwner())) return;
+        try {
+            const sessionId = ctx.sessionManager?.getSessionId?.() ?? '';
+            const st = routingStateFor(sessionId);
+            if (!st.stall) return;
+            recordToolCall(st.stall, sessionId, toolSignature(event.toolName, event.args));
+        } catch {
+            /* stall sampling is best-effort; stay silent */
+        }
+    });
+    pi.on('turn_end', async (_event, ctx) => {
+        if (!opsxConfig.stallEscalation.enabled) return;
+        if (!(ctx.hasUI || !hasTickOwner())) return;
+        try {
+            const st = routingStateFor(ctx.sessionManager?.getSessionId?.() ?? '');
+            if (!st.stall) return;
+            // Transcription fallback (design D4): the event stream is the
+            // primary source; when it delivered nothing for this session
+            // (process reload), rebuild the near window from the read-only
+            // transcript. Empty/corrupt entries idle the feature — never a
+            // downgrade, no warn noise into the selection path.
+            if (st.stall.signatures.length === 0) {
+                rebuildFromEntries(st.stall, ctx.sessionManager.getEntries());
+            }
+            evaluateStall(st.stall);
+        } catch {
+            /* stall evaluation is best-effort; stay silent */
+        }
+    });
     pi.on('input', async (event) => {
         const match = event.text.match(/^@(coder|reviewer|planner|proposal-reviewer|code-reviewer)\b(.*)$/i);
         if (!match) return;
@@ -1165,12 +1854,13 @@ export default (pi: ExtensionAPI) => {
 
     pi.setLabel('pick-model', '模型选择');
     pi.registerCommand('pick-model', {
-        description: '模型管理：choices 展示 / refresh 重选 / update 更新档位 / <selector> [--china] 按选择器约束（裸词·glob·provider/id 双段，如 zhipu*/glm*）/ reset 清除约束',
+        description: '模型管理：choices 展示 / refresh 重选 / update 更新档位 / [roleList:]<selector> [--china] 按 selector 约束（可 role 定向，如 smol:glm*；词表 smol/default/…+agent 别名/all；裸词·glob·provider/id 双段）/ reset 清除约束',
         handler: async (args: string, ctx: ExtensionCommandContext) => {
             try {
+                const symbols = resolveSymbols(pi.pi?.settings);
                 const parsed = parseAutoModelArgs(args);
                 if (parsed.kind === 'error') {
-                    pi.sendMessage({ customType: 'pick-model', content: `❌ ${parsed.message}`, display: true }, { triggerTurn: false });
+                    pi.sendMessage({ customType: 'pick-model', content: `${symbols.error} ${parsed.message}`, display: true }, { triggerTurn: false });
                     return;
                 }
 
@@ -1178,8 +1868,8 @@ export default (pi: ExtensionAPI) => {
                 if (parsed.kind === 'update') {
                     const result = updateTiers();
                     const msg = result.ok
-                        ? `✅ Tiers data updated: ${result.count} entries`
-                        : `❌ Update failed: ${result.error}`;
+                        ? `${symbols.success} Tiers data updated: ${result.count} entries`
+                        : `${symbols.error} Update failed: ${result.error}`;
                     pi.sendMessage({ customType: 'pick-model', content: msg, display: true }, { triggerTurn: false });
                     return;
                 }
@@ -1196,15 +1886,20 @@ export default (pi: ExtensionAPI) => {
                     firstUnreachableProviders = reach.unreachable;
                     availableByProvider = reach.availableByProvider;
                     const health = getSharedUsage()?.health ?? null;
+                    const collapsed = (await resolveVariantState(models, getApiKey, reach)).collapsedProviders;
                     const freshSel = computeSelectionSync(
                         effectiveConfig,
                         models,
                         health,
-                        currentKnownRoleIds(),
                         regionBlockedModels,
                         reach.unreachable,
                         reach.availableByProvider,
                         familyConstraint,
+                        collapsed,
+                        warn,
+                        // /pick-model refresh: explicit path (design D5) —
+                        // guard bypassed, no fresh classification.
+                        routingRuntimeFor(ctx, true),
                     );
                     const changes: string[] = [];
                     // Check primary session model
@@ -1215,7 +1910,12 @@ export default (pi: ExtensionAPI) => {
                         const primaryBest = primaryResult?.candidates[0];
                         if (primaryBest && `${currentModel.provider}/${currentModel.id}` !== `${primaryBest.model.provider}/${primaryBest.model.id}`) {
                             await pi.setModel(primaryBest.model);
-                            changes.push(`🏠 主会话 → ${primaryBest.model.provider}/${primaryBest.model.id}`);
+                            changes.push(formatChangeLine({
+                                name: '主会话',
+                                to: `${primaryBest.model.provider}/${primaryBest.model.id}`,
+                                coverage: coverageLabel(primaryBest.coverageClass),
+                                tier: tierLabel(primaryBest.tier),
+                            }));
                         }
                     }
                     // Check all agent models
@@ -1229,19 +1929,28 @@ export default (pi: ExtensionAPI) => {
                         if (roleCfg.kind === 'model' || roleCfg.kind === 'provider-model') {
                             const pinned = roleValueToModelString(roleCfg);
                             if (pinned && pinned !== pickedSel) {
-                                changes.push(`${agent} pinned ${pinned} → auto-pick ${pickedSel}`);
+                                changes.push(formatChangeLine({
+                                    name: `${agent}（已指定 ${pinned}）`,
+                                    to: pickedSel,
+                                    ...annotationOfPicked(result, picked),
+                                    kind: roleKindLabel(freshSel.roleKind[role]),
+                                }));
                             }
                         } else {
-                            changes.push(`${agent} → ${pickedSel}`);
+                            changes.push(formatChangeLine({
+                                name: agent,
+                                to: pickedSel,
+                                ...annotationOfPicked(result, picked),
+                                kind: roleKindLabel(freshSel.roleKind[role]),
+                            }));
                         }
                     }
                     selection = freshSel;
                     applyRoleModel(freshSel);
-                    if (changes.length > 0) {
-                        pi.sendMessage({ customType: 'pick-model', content: `✅ 模型已刷新:\n${changes.join('\n')}`, display: true }, { triggerTurn: false });
-                    } else {
-                        pi.sendMessage({ customType: 'pick-model', content: '✅ 所有模型状态正常，无需切换', display: true }, { triggerTurn: false });
-                    }
+                    const content = changes.length > 0
+                        ? renderPickModelReport('refresh', { action: '已刷新', constraint: formatFamilyConstraint(familyConstraint) || undefined, detail: [changes.join('\n')] }, symbols)
+                        : renderPickModelReport('refresh', { action: '已刷新 · 所有模型状态正常，无需切换' }, symbols);
+                    pi.sendMessage({ customType: 'pick-model', content, display: true }, { triggerTurn: false });
                     return;
                 }
 
@@ -1259,15 +1968,20 @@ export default (pi: ExtensionAPI) => {
                     firstUnreachableProviders = reach.unreachable;
                     availableByProvider = reach.availableByProvider;
                     const health = getSharedUsage()?.health ?? null;
+                    const collapsed = (await resolveVariantState(models, getApiKey, reach)).collapsedProviders;
                     const sel = computeSelectionSync(
                         effectiveConfig,
                         models,
                         health,
-                        currentKnownRoleIds(),
                         regionBlockedModels,
                         reach.unreachable,
                         reach.availableByProvider,
                         familyConstraint,
+                        collapsed,
+                        warn,
+                        // /pick-model reset: explicit path (design D5) —
+                        // guard bypassed, no fresh classification.
+                        routingRuntimeFor(ctx, true),
                     );
                     const changes: string[] = [];
                     const currentModel = ctx.model;
@@ -1275,7 +1989,12 @@ export default (pi: ExtensionAPI) => {
                     if (newPrimary) {
                         const newSel = `${newPrimary.provider}/${newPrimary.id}`;
                         const oldSel = currentModel ? `${currentModel.provider}/${currentModel.id}` : undefined;
-                        changes.push(oldSel && oldSel !== newSel ? `🏠 主会话 ${oldSel} → ${newSel}` : `🏠 主会话 → ${newSel}`);
+                        changes.push(formatChangeLine({
+                            name: '主会话',
+                            from: oldSel && oldSel !== newSel ? oldSel : undefined,
+                            to: newSel,
+                            ...annotationOfPicked(sel.selectorResults.reviewer, newPrimary),
+                        }));
                     }
                     for (const role of OPSX_ROLES) {
                         const picked = sel.selectorResults[role]?.picked;
@@ -1283,17 +2002,24 @@ export default (pi: ExtensionAPI) => {
                         const newSel = `${picked.provider}/${picked.id}`;
                         const prev = selection?.selectorResults[role]?.picked;
                         const oldSel = prev ? `${prev.provider}/${prev.id}` : undefined;
-                        changes.push(`${AGENT_MAP[role]} ${oldSel ?? '(none)'} → ${newSel}`);
+                        changes.push(formatChangeLine({
+                            name: AGENT_MAP[role],
+                            from: oldSel ?? '(none)',
+                            to: newSel,
+                            ...annotationOfPicked(sel.selectorResults[role], picked),
+                            kind: roleKindLabel(sel.roleKind[role]),
+                        }));
                     }
                     if (newPrimary) await pi.setModel(newPrimary);
                     selection = sel;
-                    selectionHealthKey = buildSelectionHealthKey(health, reach, familyConstraint);
+                    selectionHealthKey = buildSelectionHealthKey(health, reach, familyConstraint, collapsed);
                     applyRoleModel(sel);
                     pi.sendMessage({
                         customType: 'pick-model',
-                        content: changes.length > 0
-                            ? `✅ 已清除 selector 约束，恢复默认选择:\n${changes.join('\n')}`
-                            : `✅ 已清除 selector 约束，恢复默认选择（无变化）`,
+                        content: renderPickModelReport('reset', {
+                            action: changes.length > 0 ? '已清除 selector 约束，恢复默认选择' : '已清除 selector 约束，恢复默认选择（无变化）',
+                            detail: changes.length > 0 ? [changes.join('\n')] : undefined,
+                        }, symbols),
                         display: true,
                     }, { triggerTurn: false });
                     return;
@@ -1312,6 +2038,24 @@ export default (pi: ExtensionAPI) => {
                     availableByProvider = reach.availableByProvider;
                     const health = getSharedUsage()?.health ?? null;
                     const excludeSelectors = parsed.china ? CHINA_EXCLUDE_FAMILIES : [];
+                    const collapsed = (await resolveVariantState(models, getApiKey, reach)).collapsedProviders;
+
+                    // Fail fast on an inexpressible scope (model_role_tiers skip
+                    // sentinel) BEFORE touching any session state: a skip role
+                    // sits on no tier slot, so a pool constraint on it cannot be
+                    // expressed — never silently narrow the scope or no-op.
+                    let scopedSlots: ReadonlySet<TierName> | null = null;
+                    if (parsed.roleScope) {
+                        try {
+                            scopedSlots = scopedTierSlots(parsed.roleScope, opsxConfig.ompRoleTiers);
+                        } catch (e) {
+                            if (e instanceof ScopedRoleSkipError) {
+                                pi.sendMessage({ customType: 'pick-model', content: `${symbols.error} ${e.message}`, display: true }, { triggerTurn: false });
+                                return;
+                            }
+                            throw e;
+                        }
+                    }
 
                     // Switch the session-scoped state BEFORE any recompute so every
                     // later recompute path (ensureSelection, 429/403 auto-switch,
@@ -1320,25 +2064,35 @@ export default (pi: ExtensionAPI) => {
                     // command restores it rather than silently dropping an active one.
                     const prevConstraint = familyConstraint;
                     const prevEffective = effectiveConfig;
-                    familyConstraint = { selectors: parsed.selectors, excludeSelectors };
-                    effectiveConfig = buildEffectiveConfig();
+                    familyConstraint = { selectors: parsed.selectors, excludeSelectors, roles: parsed.roleScope ?? null };
+                    effectiveConfig = buildEffectiveConfig(scopedSlots);
 
                     // Fail fast: an empty candidate set (or a role that cannot pick)
                     // is a hard error — never silently pick nothing or change models.
+                    // Mirror computeSelectionSync's pool shape exactly (variant
+                    // collapse on the provider axis + command exclude else standing
+                    // china default) so the precheck cannot pass on a pool the real
+                    // recompute would keep, or vice versa.
+                    const standingExclude = opsxConfig.china ? CHINA_EXCLUDE_FAMILIES : undefined;
                     const preFiltered = filterSelectableModels(models, {
                         blockedSelectors: regionBlockedModels,
                         unreachableProviders: reach.unreachable,
-                        excludedProviders: effectiveConfig.excluded_providers,
+                        excludedProviders: [...effectiveConfig.excluded_providers, ...collapsed],
                         availableByProvider: reach.availableByProvider,
                         selectors: parsed.selectors ?? undefined,
-                        excludeSelectors: excludeSelectors.length > 0 ? excludeSelectors : undefined,
+                        excludeSelectors: excludeSelectors.length > 0 ? excludeSelectors : standingExclude,
+                        providerModels: Object.keys(effectiveConfig.providerModels).length > 0
+                            ? new Map(Object.entries(effectiveConfig.providerModels))
+                            : undefined,
                     });
                     if (preFiltered.length === 0) {
                         familyConstraint = prevConstraint;
                         effectiveConfig = prevEffective;
                         pi.sendMessage({
                             customType: 'pick-model',
-                            content: `❌ selector 约束下无可用模型。\n${selectorErrorDetail(models)}\n${exclusionReasonText(models, regionBlockedModels, reach.unreachable)}`,
+                            content: renderPickModelReport('error', {
+                                action: `selector 约束下无可用模型。\n${selectorErrorDetail(models)}\n${exclusionReasonText(models, regionBlockedModels, reach.unreachable)}`,
+                            }, symbols),
                             display: true,
                         }, { triggerTurn: false });
                         return;
@@ -1348,19 +2102,32 @@ export default (pi: ExtensionAPI) => {
                         effectiveConfig,
                         models,
                         health,
-                        currentKnownRoleIds(),
                         regionBlockedModels,
                         reach.unreachable,
                         reach.availableByProvider,
                         familyConstraint,
+                        collapsed,
+                        warn,
+                        // /pick-model <selector>: explicit path (design D5) —
+                        // guard bypassed, no fresh classification.
+                        routingRuntimeFor(ctx, true),
+                    );
+                    // pick-model-role-scope: only roles this command actually put
+                    // into the pool (roleKind 'auto' in the effective config) can
+                    // fail to pick. Out-of-scope pinned/omp-alias roles keep their
+                    // config value and synthPinnedResult never carries a picked —
+                    // counting them would roll back every scoped constraint.
+                    const emptyRole = OPSX_ROLES.find(
+                        (r) => sel.roleKind[r] === 'auto' && !sel.selectorResults[r]?.picked,
                     );
-                    const emptyRole = OPSX_ROLES.find((r) => !sel.selectorResults[r]?.picked);
                     if (emptyRole) {
                         familyConstraint = prevConstraint;
                         effectiveConfig = prevEffective;
                         pi.sendMessage({
                             customType: 'pick-model',
-                            content: `❌ selector 约束下无法为 role "${emptyRole}" 选择模型。\n${selectorErrorDetail(models)}\n${exclusionReasonText(models, regionBlockedModels, reach.unreachable)}`,
+                            content: renderPickModelReport('error', {
+                                action: `selector 约束下无法为 role "${emptyRole}" 选择模型。\n${selectorErrorDetail(models)}\n${exclusionReasonText(models, regionBlockedModels, reach.unreachable)}`,
+                            }, symbols),
                             display: true,
                         }, { triggerTurn: false });
                         return;
@@ -1378,14 +2145,25 @@ export default (pi: ExtensionAPI) => {
                     const changes: string[] = [];
                     if (newPrimary) {
                         const newSel = `${newPrimary.provider}/${newPrimary.id}`;
-                        changes.push(oldPrimary && oldPrimary !== newSel ? `🏠 主会话 ${oldPrimary} → ${newSel}` : `🏠 主会话 → ${newSel}`);
+                        changes.push(formatChangeLine({
+                            name: '主会话',
+                            from: oldPrimary && oldPrimary !== newSel ? oldPrimary : undefined,
+                            to: newSel,
+                            ...annotationOfPicked(sel.selectorResults.reviewer, newPrimary),
+                        }));
                     }
                     for (const role of OPSX_ROLES) {
                         const picked = sel.selectorResults[role]?.picked;
                         if (!picked) continue;
                         const newSel = `${picked.provider}/${picked.id}`;
                         const oldSel = oldRolePicks[role];
-                        changes.push(`${AGENT_MAP[role]} ${oldSel ?? '(none)'} → ${newSel}`);
+                        changes.push(formatChangeLine({
+                            name: AGENT_MAP[role],
+                            from: oldSel ?? '(none)',
+                            to: newSel,
+                            ...annotationOfPicked(sel.selectorResults[role], picked),
+                            kind: roleKindLabel(sel.roleKind[role]),
+                        }));
                     }
 
                     // Cross-provider ambiguity hint (design Decision 8): only when a
@@ -1407,9 +2185,14 @@ export default (pi: ExtensionAPI) => {
 
                     if (newPrimary) await pi.setModel(newPrimary);
                     selection = sel;
-                    selectionHealthKey = buildSelectionHealthKey(health, reach, familyConstraint);
+                    selectionHealthKey = buildSelectionHealthKey(health, reach, familyConstraint, collapsed);
                     applyRoleModel(sel);
-                    const content = `✅ 已切换 selector 约束 (${formatFamilyConstraint(familyConstraint)}):\n${changes.join('\n')}${hint ? `\n${hint}` : ''}`;
+                    const content = renderPickModelReport('switch', {
+                        action: '已切换 selector 约束',
+                        constraint: formatFamilyConstraint(familyConstraint) || undefined,
+                        detail: changes.length > 0 ? [changes.join('\n')] : undefined,
+                        footnote: hint || undefined,
+                    }, symbols);
                     pi.sendMessage({
                         customType: 'pick-model',
                         content,
@@ -1420,22 +2203,59 @@ export default (pi: ExtensionAPI) => {
 
                 // ── /pick-model choices (default) ────────────────
                 const sel = await getSelectionForCommand(ctx);
-                const tierStatus = (() => {
-                    const loaded = isTiersDataLoaded();
-                    return loaded === null ? 'not loaded' : loaded ? '' : '(tier data corrupt, using heuristics)';
-                })();
-                const lines: string[] = [];
-                const constraintLabel = formatFamilyConstraint(familyConstraint);
-                if (constraintLabel) lines.push(`constraint: ${constraintLabel}`);
-                lines.push(formatModelChoicesMarkdown(sel, '', ctx.model));
-                lines.push('');
-                lines.push(formatFamilyTierMarkdown(sel));
-                lines.push('');
-                lines.push('`/pick-model refresh` 切换耗尽模型 · `/pick-model update` 更新 tier 数据');
-                pi.sendMessage({ customType: 'pick-model', content: lines.join('\n'), display: true }, { triggerTurn: false });
+                const roleLines = formatRoleLines(
+                    OPSX_ROLES.map((role) => ({
+                        name: AGENT_MAP[role],
+                        kind: sel.roleKind[role],
+                        fallbackModel: sel.roleModels[role],
+                        result: sel.selectorResults[role],
+                    })),
+                    ctx.model
+                        ? {
+                            model: { provider: ctx.model.provider, id: ctx.model.id },
+                            tier: scoreModelWithProvider(ctx.model.provider, ctx.model.id, ctx.model.name, undefined).tier,
+                        }
+                        : undefined,
+                );
+                // Full agent inventory (project + user + bundled, host-merged).
+                // Failure downgrades to omitting the section + warn; never blocks.
+                let agentInventory: string | undefined;
+                try {
+                    agentInventory = formatAgentInventory((await discoverAgents(directory)).agents, symbols);
+                } catch (err) {
+                    warn(`[omp-opsx-addon] agent inventory unavailable: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                const detail: string[] = [];
+                if (roleLines.length > 0) detail.push(roleLines.join('\n'));
+                if (agentInventory) detail.push(agentInventory);
+                const concurrencySummary = ownedConcurrency?.controller.summaryLines() ?? [];
+                // Regional-variant appendix line (china-config): resolved fresh from
+                // the live registry with the same resolution the recompute paths use.
+                const poolModels = ctx.modelRegistry?.getAvailable() ?? [];
+                const choicesGetApiKey = ctx.modelRegistry?.getApiKeyForProvider
+                    ? (provider: string) => ctx.modelRegistry.getApiKeyForProvider(provider)
+                    : undefined;
+                const variantLine = variantCollapseAnnotation(
+                    await resolveVariantState(poolModels, choicesGetApiKey, {
+                        unreachable: firstUnreachableProviders,
+                        availableByProvider,
+                    }),
+                );
+                const appendixParts: string[] = [];
+                if (concurrencySummary.length > 0) appendixParts.push('**并发控制**', ...concurrencySummary);
+                if (variantLine) appendixParts.push(variantLine);
+                const content = renderPickModelReport('choices', {
+                    action: '当前选择',
+                    constraint: formatFamilyConstraint(familyConstraint) || undefined,
+                    detail,
+                    overview: formatCandidateOverview(OPSX_ROLES.map((role) => sel.selectorResults[role])),
+                    appendix: appendixParts.length > 0 ? appendixParts.join('\n') : undefined,
+                    footnote: formatFootnote(OPSX_ROLES.map((role) => sel.selectorResults[role]), sel.paygLastResort),
+                }, symbols);
+                pi.sendMessage({ customType: 'pick-model', content, display: true }, { triggerTurn: false });
             } catch (e) {
                 warn(`[omp-opsx-addon] /pick-model error: ${e}`);
-                pi.sendMessage({ customType: 'pick-model', content: `❌ Error: ${e}`, display: true }, { triggerTurn: false });
+                pi.sendMessage({ customType: 'pick-model', content: `${resolveSymbols(pi.pi?.settings).error} Error: ${e}`, display: true }, { triggerTurn: false });
             }
         },
     });
@@ -1461,7 +2281,9 @@ export default (pi: ExtensionAPI) => {
 
     async function getSelectionForCommand(ctx: ExtensionCommandContext): Promise<SelectionContext> {
         if (selection) return selection;
-        return ensureSelection(ctx);
+        // Explicit command path: guard bypassed, no fresh classification
+        // (design D5 — the lazy compute exists only for a cache miss).
+        return ensureSelection(ctx, false, true);
     }
 
     // Cross-broker project-scoped pipe core: registers opsx_pipe_list /