@genee/omp-opsx-addon 0.1.0

package/index.ts

@@ -0,0 +1,1327 @@
+// ── subagent usage tracking ───────────────────────────────────────────
+// The TASK_SUBAGENT_EVENT_CHANNEL is used to forward subagent events to
+// the primary session's eventBus. Subagent message_update/message_end events
+// are wrapped in SubagentEventPayload { id, event } and sent through this channel.
+// The primary session subscribes to this channel to record subagent usage into
+// the primary's recorder. This avoids the module-level singleton issue where
+// each plugin instance has its own recorder.
+//
+// IMPORTANT: Plugins cannot directly subscribe to eventBus channels via the
+// official ExtensionAPI. We access the eventBus through internal properties as a
+// pragmatic workaround. The channel string is hardcoded from harness source:
+// src/task/types.ts:59 -> "task:subagent:event"
+//
+// NOTE: This is a hack that depends on internal harness implementation details.
+// Future harness versions may break this if internal properties change.
+//
+// Reference:
+// - emitSubagentFrame: src/task/executor.ts:1431-1432
+// - SubagentEventPayload: src/task/types.ts:82-84
+// - EventBus.on(): src/utils/event-bus.ts:15-28
+const TASK_SUBAGENT_EVENT_CHANNEL = "task:subagent:event";
+
+// Track unsubscribers for cleanup on session_shutdown
+const subagentEventUnsubscribers = new Map<string, () => void>();
+
+// Helper to safely access eventBus from ctx
+function getEventBusFromCtx(ctx: ExtensionContext | ExtensionCommandContext): unknown {
+    // Try to access eventBus through various internal properties
+    // This is a hack that depends on harness implementation details
+    const sessionManager = ctx.sessionManager as Record<string, unknown>;
+    // Try common property names
+    for (const key of ['session', '_session', '__session', 'eventBus', '_eventBus']) {
+        const val = (sessionManager as Record<string, unknown>)[key];
+        if (val && typeof val === 'object') {
+            const obj = val as Record<string, unknown>;
+            if (typeof obj.eventBus !== 'undefined') {
+                return obj.eventBus;
+            }
+            if (key === 'eventBus' || key === '_eventBus') {
+                return val;
+            }
+        }
+    }
+    return undefined;
+}
+
+// Helper to subscribe to eventBus channel
+function subscribeToEventBusChannel(
+    eventBus: unknown,
+    channel: string,
+    handler: (data: unknown) => void,
+): () => void {
+    const bus = eventBus as Record<string, unknown>;
+    const onMethod = bus.on as ((channel: string, handler: (data: unknown) => void) => () => void) | undefined;
+    if (typeof onMethod === 'function') {
+        return onMethod.call(bus, channel, handler);
+    }
+    // Return no-op if eventBus doesn't support subscription
+    return () => {};
+}
+
+// Process subagent event payload
+function handleSubagentEvent(payload: unknown, primarySessionId: string): void {
+    try {
+        if (!payload || typeof payload !== 'object') {
+            return;
+        }
+        // The channel frame carries the subagent's AgentSessionEvent
+        // ({ type, message, assistantMessageEvent }), not a flat assistant
+        // message, so the top level has no role/provider/usage. Dispatch by
+        // event type, mirroring the primary message_update/message_end handlers.
+        const p = payload as { id?: string; event?: { type?: string; message?: unknown; assistantMessageEvent?: unknown } };
+        const ev = p.event;
+        if (!ev || typeof ev !== 'object') {
+            return;
+        }
+
+        let usageResult: { provider: string; usage: UsageBucket } | undefined;
+        if (ev.type === 'message_update') {
+            // assistantMessageEvent may be shapes other than partial
+            // (toolcall_start etc.); only 'partial' carries usage.
+            const ame = ev.assistantMessageEvent;
+            if (ame && typeof ame === 'object' && 'partial' in ame) {
+                usageResult = assistantUsageOf(ame.partial);
+            } else {
+                return;
+            }
+        } else if (ev.type === 'message_end') {
+            usageResult = assistantUsageOf(ev.message);
+        } else {
+            // Other agent-session event types carry no billable usage.
+            return;
+        }
+        if (!usageResult) {
+            return;
+        }
+
+        const { provider, usage } = usageResult;
+
+        // Use subagent-specific key for stream tracking (streamKey only, NOT setSessionId)
+        // This prevents cross-stream contamination while keeping global totals intact
+        const subagentStreamKey = `${primarySessionId}:subagent:${p.id}`;
+
+        // Record usage with subagent-specific stream key (NO setSessionId call)
+        sessionUsageRecorder.record(provider, usage, subagentStreamKey);
+    } catch (err) {
+        // Silently fail to avoid breaking the plugin
+        console.error('Failed to handle subagent event:', err);
+    }
+}
+import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from '@oh-my-pi/pi-coding-agent';
+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 { 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 { selectAllRoles, mergePlanProviders, type SelectorResult } from './lib/model-selector.js';
+import { scoreModelWithProvider } from './lib/model-tiers.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 {
+    startSharedPoller,
+    getUnconfirmedProviders,
+    isResetImminent,
+    getSharedUsage,
+    pokeProvider,
+    hasTickOwner,
+    getSessionUsageTotals,
+    getSessionUsagePerSecond,
+    writeSessionUsage,
+    removeSessionUsage,
+    mirrorSessionDelta,
+    hasManagedSessionUsage,
+} from './lib/usage-poller.js';
+import {
+    createSessionUsageRecorder,
+    assistantUsageOf,
+    SESSION_USAGE_WRITE_MS,
+    type SessionUsageSink,
+    type SessionUsageRecorder,
+} from './lib/session-usage.js';
+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,
+    getUnreachableProviders,
+} from './lib/reachability-cache.js';
+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 { hasRateLimitError, hasRegionError, buildErrorDiagnosis, exclusionReasonStats } from './lib/error-scan.js';
+import { applyEditVariantPin } from './lib/edit-variant-pin.js';
+type Role = 'coder' | 'reviewer' | 'planner' | 'proposal-reviewer';
+
+/** Session-scoped selector constraint for `/pick-model <selector> [--china]`. */
+export interface FamilyConstraint {
+    selectors: string[] | null;
+    excludeSelectors: string[];
+}
+
+/** Stable fingerprint of the active selector constraint (design Decision 3/9). */
+function familyConstraintFingerprint(fc: FamilyConstraint | null): string {
+    if (!fc) return 'none';
+    return `fam:${fc.selectors ? fc.selectors.join(',') : '*'}|excl:${fc.excludeSelectors.join(',')}`;
+}
+
+/**
+ * Selection health key for a given blocked set — shared by the session closure's
+ * buildSelectionHealthKey (used by every manual recompute path).
+ */
+function selectionHealthKeyFor(
+    health: Map<string, ProviderHealth> | null,
+    reach: { unreachable: Set<string>; availableByProvider: Map<string, string[] | null> },
+    fc: FamilyConstraint | null,
+    blocked: ReadonlySet<string>,
+): string {
+    return `${healthCacheKey(health)}|${reachabilityFingerprint({
+        unreachable: reach.unreachable,
+        availableByProvider: reach.availableByProvider,
+        blocked,
+    })}|${familyConstraintFingerprint(fc)}`;
+}
+
+/** Suggested id segment for the ambiguity hint (design Decision 8). */
+function buildSuggestedIdSeg(selectors: readonly string[]): string {
+    if (selectors.length === 1) {
+        const s = selectors[0];
+        if (s.includes('/')) {
+            const idSeg = s.slice(s.indexOf('/') + 1);
+            return idSeg === '' ? '*' : idSeg;
+        }
+        return s.includes('*') ? '*' : `${s}*`;
+    }
+    for (const s of selectors) {
+        if (s.includes('/')) {
+            const idSeg = s.slice(s.indexOf('/') + 1);
+            return idSeg === '' ? '*' : idSeg;
+        }
+    }
+    return '*';
+}
+
+/** Two-dimension error detail: provider counts (desc) + id family words + example. */
+function selectorErrorDetail(models: readonly { provider: string; id: string }[]): string {
+    const prov = [...listProviders(models).entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([p, c]) => `${p}(${c})`)
+        .join(', ');
+    const fams = listFamilies(models).join(', ');
+    return `providers: ${prov}\nid families: ${fams}\n示例: /pick-model zhipu*/glm*   （provider glob / id glob）`;
+}
+
+/** Human-readable reasons a selector candidate set came up empty. */
+function exclusionReasonText(
+    models: readonly { provider: string; id: string }[],
+    regionBlockedModels: ReadonlySet<string>,
+    unreachableProviders: ReadonlySet<string>,
+): string {
+    const { blockedCount, blockedExamples, unreachableProviderCount } = exclusionReasonStats(
+        models,
+        regionBlockedModels,
+        unreachableProviders,
+    );
+    const lines: string[] = [];
+    if (blockedCount > 0) {
+        const ex = blockedExamples.join(', ');
+        lines.push(`被 403 屏蔽: ${blockedCount} 个模型 (${ex})`);
+    }
+    if (unreachableProviderCount > 0) {
+        lines.push(`不可达 provider: ${unreachableProviderCount} 个`);
+    }
+    if (lines.length === 0) {
+        lines.push('（无 403 屏蔽、无不可达 provider）');
+    }
+    lines.push('提示: 不可达 provider 由探测决定；403 不再自动屏蔽模型。');
+    return lines.join('\n');
+}
+
+const AGENT_MAP: Record<Role, string> = {
+    coder: 'coder',
+    reviewer: 'code-reviewer',
+    planner: 'planner',
+    'proposal-reviewer': 'proposal-reviewer',
+};
+function findRoleForModel(provider: string, modelId: string, sel: SelectionContext): Role | null {
+    for (const role of OPSX_ROLES) {
+        const r = sel.selectorResults[role];
+        if (!r) continue;
+        if (r.allCandidates.some((c) => c.selector === `${provider}/${modelId}`)) {
+            return role;
+        }
+    }
+    return null;
+}
+
+export interface SelectionContext {
+    selectorResults: Record<Role, SelectorResult>;
+    roleModels: Record<Role, string | undefined>;
+    /** Display label for each role from config, e.g. "auto", "smol", "deepseek-v4-pro". */
+    roleConfigs: Record<Role, string | undefined>;
+}
+
+const DEFAULT_PLAN_PROVIDERS = new Set(['minimax-code-cn', 'opencode-go', 'zhipu-coding-plan', 'kimi', 'openai-codex']);
+
+/** OPSX role → OMP role alias used in agent frontmatter `model: @<alias>`. */
+const ROLE_TO_OMP_ALIAS: Record<Role, string> = {
+    coder: 'smol',
+    reviewer: 'default',
+    planner: 'default',
+    'proposal-reviewer': 'default',
+};
+
+/** OMP role alias → expected tier (without the `@`). */
+const OMP_ROLE_TO_TIER: Record<string, string> = {
+    smol: 'mid',
+    default: 'high',
+    slow: 'top',
+};
+
+function roleValueToModelString(value: RoleValue): string | undefined {
+    if (value.kind === 'auto') return undefined;
+    if (value.kind === 'omp-alias') return `@${value.alias}`;
+    if (value.kind === 'provider-model') return `${value.provider}/${value.modelId}`;
+    if (value.kind === 'model') return value.modelId;
+    return undefined;
+}
+
+function normalizeRole(input: string): Role {
+    const lower = input.toLowerCase();
+    if (lower === 'code-reviewer') return 'reviewer';
+    return lower as Role;
+}
+
+function synthPinnedResult(role: string, modelString: string | undefined): SelectorResult {
+    return {
+        role,
+        expectedTier: 'mid',
+        picked: null,
+        candidates: [],
+        allCandidates: [],
+        decision: modelString ? `pinned: ${modelString}` : 'pinned: <no model specified>',
+        pickedReason: modelString ? `pinned to ${modelString}` : null,
+    };
+}
+
+export function buildDispatchPrompt(role: Role, task: string, selection: SelectionContext): string {
+    const agent = AGENT_MAP[role];
+    const sel = selection.selectorResults[role];
+    const modelHint = sel?.picked ? `${sel.picked.provider}/${sel.picked.id}` : selection.roleModels[role];
+    const parts = [`你的 opsx.${role} 已自动选择 model。`];
+    if (modelHint) parts.push(`请通过 task 工具调用 ${agent} 并指定 model="${modelHint}"。`);
+    else parts.push(`请通过 task 工具调用 ${agent}。`);
+    if (sel?.decision) parts.push(`原因: ${sel.decision}`);
+    parts.push('直接用内置工具实现。');
+    return `请使用 task 工具委派给 ${agent}：\ntask(agent:"${agent}"${modelHint ? `, model:"${modelHint}"` : ''}, task:"${parts.join(' ')}\\n\\n${task}")`;
+}
+
+function computeSelectionSync(
+    config: ResolvedOpsxConfig,
+    models: Model<Api>[] | null,
+    health: Map<string, ProviderHealth> | null,
+    regionBlockedModels?: Set<string>,
+    unreachableProviders?: Set<string>,
+    availableByProvider?: Map<string, string[] | null>,
+    familyConstraint?: FamilyConstraint | null,
+): SelectionContext {
+    const filteredModels = models
+        ? filterSelectableModels(models, {
+            blockedSelectors: regionBlockedModels,
+            unreachableProviders,
+            excludedProviders: config.excluded_providers,
+            availableByProvider,
+            selectors: familyConstraint?.selectors ?? undefined,
+            excludeSelectors:
+                familyConstraint?.excludeSelectors && familyConstraint.excludeSelectors.length > 0
+                    ? familyConstraint.excludeSelectors
+                    : undefined,
+        })
+        : models;
+    const selectorResults = {} as Record<Role, SelectorResult>;
+    const roleModels = {} as Record<Role, string | undefined>;
+    const roleConfigs = {} as Record<Role, string | undefined>;
+    const planSet = mergePlanProviders(config.planProviders);
+    for (const role of OPSX_ROLES) {
+        const value = config.roles[role];
+        roleConfigs[role] = value.kind === 'auto' ? ROLE_TO_OMP_ALIAS[role] : (roleValueToModelString(value) ?? '?');
+        const alias = `@${ROLE_TO_OMP_ALIAS[role]}`;
+        if (value.kind === 'auto') {
+            if (filteredModels && filteredModels.length > 0) {
+                const ompRole = ROLE_TO_OMP_ALIAS[role];
+                const tier = (config.roleTiers[role] ?? OMP_ROLE_TO_TIER[ompRole] ?? 'mid') as
+                    'top' | 'high' | 'mid' | 'low' | 'tiny';
+                const roleTiers = { ...config.roleTiers, [role]: tier };
+                const result = selectAllRoles(
+                    [role],
+                    filteredModels,
+                    roleTiers,
+                    config.tierOverrides,
+                    health ?? undefined,
+                    config.modelAllowlist,
+                    planSet,
+                )[role];
+                selectorResults[role] = result;
+                roleModels[role] = result.picked ? alias : undefined;
+            } else {
+                selectorResults[role] = {
+                    role,
+                    expectedTier: 'mid',
+                    picked: null,
+                    candidates: [],
+                    allCandidates: [],
+                    decision: 'auto: modelRegistry unavailable',
+                    pickedReason: null,
+                };
+                roleModels[role] = undefined;
+            }
+        } else {
+            const modelString = roleValueToModelString(value);
+            selectorResults[role] = synthPinnedResult(role, modelString);
+            roleModels[role] = modelString?.includes('/') ? modelString : undefined;
+        }
+    }
+    return { selectorResults, roleModels, roleConfigs };
+}
+
+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');
+}
+
+// ── per-plugin-instance usage recorder ─────────────────────────────
+// NOT a process-wide singleton: the harness loads a fresh plugin instance
+// for every session, including in-process task subagents (task/executor.ts),
+// so each instance builds its own recorder here. Subagent sessions therefore
+// cannot write to the primary's recorder directly. Instead their usage is
+// captured through the eventBus mechanism:
+// - task/executor.ts:1431-1432 forwards subagent events to the primary session's
+//   eventBus via TASK_SUBAGENT_EVENT_CHANNEL ("task:subagent:event")
+// - The primary plugin subscribes to this channel and records subagent usage
+//   with subagent-specific stream keys (never re-keys the recorder, so the
+//   owner's cumulative baseline survives and streams don't double-count)
+// Each session's recorder persists its own session totals into the shared
+// usage cache, which every process aggregates on read.
+const sessionUsageRecorder: SessionUsageRecorder = createSessionUsageRecorder({
+    write: writeSessionUsage,
+    remove: removeSessionUsage,
+    onDelta: mirrorSessionDelta,
+});
+
+// ── plugin entry ────────────────────────────────────────────────────
+
+export default (pi: ExtensionAPI) => {
+    // Runtime edit-variant pin for deepseek-v4-flash. The host hard-maps the
+    // model to the sloppy §/» marker grammar (it misreads hashline ranges),
+    // but the model repeatedly breaks sloppy control lines too — retry loops
+    // burn tokens and abort agents. Point it at the simplest old_string/
+    // new_string "replace" variant instead.
+    // Preferred path: `settings.override` (in-memory, per-session). omp
+    // 18.0.11 removed `edit.modelVariants` from the settings schema, so on
+    // that host the pin is persisted into the global config.yml once — the
+    // host reads the merged view directly, making the file equivalent.
+    applyEditVariantPin(pi, { 'deepseek-v4-flash': 'replace' });
+    const directory = process.cwd();
+    const warn = (msg: string) => console.warn(msg);
+    const opsxConfig = readOpsxSettings(directory, warn);
+    // Static orchestration rules — built once, reused every turn for cache stability.
+    const STATIC_PROMPT = buildStaticPrompt();
+    let initialModel: { provider: string; id: string } | null = null;
+    // Active resize handler — tracked so each session_start can off the previous one.
+    let activeResizeHandler: (() => void) | null = null;
+    let selection: SelectionContext | null = null;
+    // 403 no longer auto-blocks; the set is always empty in the running session.
+    // A one-time startup migration clears stale blockedModels written by the old
+    // auto-switch path (loadBlockedModels/persistBlockedModels are kept for it).
+    const regionBlockedModels: Set<string> = new Set();
+    let selectionPromise: Promise<SelectionContext> | null = null;
+    let firstUnreachableProviders: Set<string> = getUnreachableProviders(opsxConfig.probe_ttl_ms);
+    let availableByProvider: Map<string, string[] | null> = loadAvailableByProvider(opsxConfig.probe_ttl_ms);
+    let selectionHealthKey = '';
+
+    // Session-scoped family constraint (never persisted). `effectiveConfig` is the
+    // config consulted by every recompute path during a family constraint: family
+    // commands deep-copy opsxConfig with all roles forced to auto (covering pinned
+    // roles that would otherwise synthPinnedResult and bypass filterSelectableModels),
+    // and `/pick-model reset` restores it to opsxConfig.
+    let familyConstraint: FamilyConstraint | null = null;
+    let effectiveConfig: ResolvedOpsxConfig = opsxConfig;
+
+    const buildSelectionHealthKey = (
+        health: Map<string, ProviderHealth> | null,
+        reach: { unreachable: Set<string>; availableByProvider: Map<string, string[] | null> },
+        fc: FamilyConstraint | null,
+    ): string => {
+        return selectionHealthKeyFor(health, reach, fc, regionBlockedModels);
+    };
+
+    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');
+        return parts.join(' · ');
+    };
+
+    /** Copy of opsxConfig with every role forced to auto — covers pinned roles. */
+    const buildEffectiveConfig = (): ResolvedOpsxConfig => {
+        const roles = {} as Record<Role, RoleValue>;
+        for (const role of OPSX_ROLES) roles[role] = { kind: 'auto' };
+        return { ...opsxConfig, roles };
+    };
+    const startPollerFor = async (ctx: ExtensionContext, onTick?: () => void): Promise<void> => {
+        const auth = ctx.modelRegistry?.authStorage;
+        const getApiKey = ctx.modelRegistry?.getApiKeyForProvider
+            ? (provider: string) => ctx.modelRegistry.getApiKeyForProvider(provider)
+            : undefined;
+        const cfg = buildEffectiveConfig();
+        await startSharedPoller(auth, DIRECT_FETCHERS, getApiKey, {
+            ...(onTick ? { onTick } : undefined),
+            redis: {
+                enabled: cfg.redis_enabled,
+                host: cfg.redis_host,
+                port: cfg.redis_port,
+                connectTimeoutMs: cfg.redis_connect_timeout_ms,
+                commandTimeoutMs: cfg.redis_command_timeout_ms,
+                reconcileIntervalMs: cfg.redis_reconcile_interval_ms,
+                probeIntervalMs: cfg.redis_probe_interval_ms,
+                unhealthyRetryMs: cfg.redis_unhealthy_retry_ms,
+                ttlMs: cfg.redis_ttl_ms,
+            },
+        });
+    };
+
+    const ensureSelection = (ctx: ExtensionContext, force = false): Promise<SelectionContext> => {
+        if (selectionPromise && !force) return selectionPromise;
+        selectionPromise = (async () => {
+            await startPollerFor(ctx);
+            let models: Model<Api>[] | null = null;
+            try {
+                models = ctx.modelRegistry.getAvailable();
+            } catch (e) {
+                warn(`[omp-opsx-addon] modelRegistry error: ${e}`);
+            }
+            const reach = await refreshReachability(models, opsxConfig);
+            firstUnreachableProviders = reach.unreachable;
+            availableByProvider = reach.availableByProvider;
+            const health = getSharedUsage()?.health ?? null;
+            const key = buildSelectionHealthKey(health, reach, familyConstraint);
+            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).
+            const sel = computeSelectionSync(
+                effectiveConfig,
+                models,
+                health,
+                regionBlockedModels,
+                reach.unreachable,
+                reach.availableByProvider,
+                familyConstraint,
+            );
+            selection = sel;
+            selectionHealthKey = key;
+            return sel;
+        })().finally(() => {
+            selectionPromise = null;
+        });
+        return selectionPromise;
+    };
+    // Push selector-picked models to native task subagents via task.agentModelOverrides.
+    // pi.pi.settings is the host-process Settings singleton (the require()'d copy in
+    // node_modules is a separate, uninitialized instance — writing to it was a no-op).
+    const applyAgentModelOverrides = (sel: SelectionContext, force = false): void => {
+        const settings = pi.pi?.settings;
+        if (!settings) {
+            warn('[omp-opsx-addon] pi.pi.settings unavailable; subagent model overrides skipped');
+            return;
+        }
+        const overrides: Record<string, string> = {};
+        for (const role of OPSX_ROLES) {
+            const picked = sel.selectorResults[role]?.picked;
+            if (picked) {
+                overrides[AGENT_MAP[role]] = `${picked.provider}/${picked.id}`;
+            }
+        }
+        if (Object.keys(overrides).length > 0 || force) {
+            settings.override('task.agentModelOverrides', overrides);
+            warn(
+                `[omp-opsx-addon] task.agentModelOverrides: ${Object.entries(overrides)
+                    .map(([k, v]) => `${k}=${v}`)
+                    .join(', ')}`,
+            );
+        }
+    };
+
+    // ── shared usage poller + widget ──────────────────────────────
+    pi.on('session_start', async (_event, ctx) => {
+        try {
+            initialModel = ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : null;
+            // One-time migration: wipe stalled blockedModels persisted by the old
+            // auto-switch path (a single unrelated 403 could permanently shadow other
+            // providers). The runtime set is empty; only this startup cleanup writes.
+            const stale = loadBlockedModels();
+            if (stale.length > 0) persistBlockedModels(new Set());
+            // Process-wide singletons (tick render + usage recorder) belong to ONE
+            // owning session. Task subagents run in THIS process and also emit
+            // session_start (task/executor.ts); their ctx.ui is a no-op, so letting
+            // them claim the render callback freezes the host widget, and letting
+            // them re-key the recorder would clear the owner's cumulative baseline
+            // (setSessionId resets totals) AND detach their records from the
+            // owner's entry. Claim only when this session has a UI, or when no
+            // owner exists yet (headless first session). Subagent consumption is
+            // captured via the eventBus channel mechanism (see file header for
+            // details) and recorded into the primary's recorder with subagent-
+            // specific keys.
+            const ownsUi = ctx.hasUI;
+            const claimsOwnership = ownsUi || !hasTickOwner();
+            if (claimsOwnership) {
+                sessionUsageRecorder.setSessionId(ctx.sessionManager?.getSessionId?.() ?? '');
+            }
+            // Subscribe to subagent events via eventBus to capture usage
+            // Only primary sessions (with UI or no owner) should subscribe
+            if (claimsOwnership) {
+                const sessionId = ctx.sessionManager?.getSessionId?.() ?? '';
+                const eventBus = getEventBusFromCtx(ctx);
+                if (eventBus) {
+                    // Clean up any existing subscription for this session to prevent leaks
+                    const existingUnsubscribe = subagentEventUnsubscribers.get(sessionId);
+                    if (existingUnsubscribe) {
+                        try {
+                            existingUnsubscribe();
+                        } catch {
+                            // Silently ignore errors in unsubscribe
+                        }
+                    }
+                    const unsubscribe = subscribeToEventBusChannel(
+                        eventBus,
+                        TASK_SUBAGENT_EVENT_CHANNEL,
+                        (payload) => handleSubagentEvent(payload, sessionId),
+                    );
+                    if (unsubscribe) {
+                        subagentEventUnsubscribers.set(sessionId, unsubscribe);
+                    }
+                }
+            }
+            const auth = ctx.modelRegistry?.authStorage;
+            const getApiKey = ctx.modelRegistry?.getApiKeyForProvider
+                ? (provider: string) => ctx.modelRegistry.getApiKeyForProvider(provider)
+                : undefined;
+
+            const key = 'omp-opsx-addon-usage';
+            // Second-level estimate baseline — lives OUTSIDE render so drift
+            // accumulates across renders and only resets on a fresh snapshot.
+            // Active provider set shared by the tick sampler and the renderer:
+            // every reported/logged-in provider gets a chart track (blank strip
+            // when unsampled) so the mini-chart area never appears/disappears.
+            const resolveActiveProviders = (): {
+                reports: UsageReport[];
+                placeholderIds: string[];
+                active: string[];
+                show: boolean;
+            } => {
+                const state = getSharedUsage();
+                const reports = state?.reports ?? [];
+                let loggedIn: string[] = [];
+                let authAvailable = false;
+                try {
+                    if (auth?.list) {
+                        authAvailable = true;
+                        const list = auth.list();
+                        loggedIn = Array.isArray(list) ? list : [];
+                    }
+                } catch {
+                    /* treat authStorage as unavailable */
+                }
+                try {
+                    const detectable = listDetectableProviders(DIRECT_FETCHERS);
+                    if (detectable.length > 0) {
+                        authAvailable = true;
+                        loggedIn = [...new Set([...loggedIn, ...detectable])];
+                    }
+                } catch {
+                    /* ignore */
+                }
+                // reports[].provider is already canonical (the resolver
+                // normalizes built-in ids); canonicalize loggedIn too so a login
+                // alias doesn't surface as BOTH a real report and a placeholder.
+                const reported = new Set(reports.map((r) => r.provider));
+                const placeholderIds = [...new Set(loggedIn.map(canonicalizeProvider))].filter((p) => !reported.has(p));
+                // With authStorage: show iff any provider is logged in (hide even if
+                // stale reports linger). Without it (tests / offline), fall back to
+                // "has report".
+                const show = authAvailable ? loggedIn.length > 0 : reports.length > 0;
+                return { reports, placeholderIds, active: [...reported, ...placeholderIds], show };
+            };
+            // Second-level estimate baseline — lives OUTSIDE render so drift
+            // accumulates across renders and only resets on a fresh snapshot.
+            const estimateState: { baseline: { fetchedAt: number; totals: Record<string, { total: number; input: number; output: number }> } | null } = { baseline: null };
+            // 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 state = getSharedUsage();
+                const loadingProviders = state?.loadingProviders ?? new Set<string>();
+                if (!show) {
+                    if (ctx.ui) {
+                        ctx.ui.setWidget(key, undefined);
+                    }
+                    return;
+                }
+                // Second-level balance estimates: snapshot − sessionUsage flow ×
+                // price. Baseline resets whenever a fresh snapshot lands (fetch
+                // alignment), so drift only ever spans one fetch TTL.
+                const totals = getSessionUsageTotals();
+                const snapshotFetchedAt = state?.fetchedAt ?? 0;
+                const hit = estimateState.baseline && estimateState.baseline.fetchedAt === snapshotFetchedAt;
+                const baselineTotals = hit && estimateState.baseline ? estimateState.baseline.totals : totals;
+                if (!hit) {
+                    estimateState.baseline = { fetchedAt: snapshotFetchedAt, totals: { ...totals } };
+                }
+                const models = (ctx.modelRegistry && typeof ctx.modelRegistry.getAll === 'function'
+                    ? ctx.modelRegistry.getAll()
+                    : []) as { provider: string; cost?: { input: number; output: number } }[];
+                const usageEstimates = buildBalanceEstimates(reports, totals, models, baselineTotals);
+                // Per-provider Braille consumption mini-charts — read-only, never
+                // touches selection. Every active provider gets a track; an
+                // unsampled provider renders as a blank placeholder strip.
+                const consumptionTracks = new Map<string, ConsumptionTrack>();
+                for (const p of active) {
+                    consumptionTracks.set(p, { samples: getConsumptionSamples(p) });
+                }
+                if (ctx.hasUI) {
+                    ctx.ui.setWidget(key, createUsageWidget(reports, placeholderIds, loadingProviders, consumptionTracks, usageEstimates), {
+                        placement: 'belowEditor',
+                    });
+                } else {
+                    if (ctx.ui) {
+                        const cols = (process.stdout.columns ?? 120) - 3;
+                        const lines = renderUsageReports(reports, cols, undefined, placeholderIds, loadingProviders, consumptionTracks, usageEstimates);
+                        ctx.ui.setWidget(key, lines.length > 0 ? lines : undefined, { placement: 'belowEditor' });
+                    }
+                }
+            };
+            // Tick path is strictly read-only wrt selection: it flushes this
+            // session's usage totals to the shared cache, samples every
+            // provider's aggregated consumption RATE (all sessions, main +
+            // subagent via cache backflow), and re-renders the widget. It never
+            // recomputes a selection, never applies overrides, never setModel.
+            const onTick = () => {
+                sessionUsageRecorder.flush();
+                const { active } = resolveActiveProviders();
+                // Waveform source = per-second consumption sequence (timestamped
+                // deltas aggregated across sessions). Sample EVERY elapsed second
+                // for EVERY active provider — zeros when a second had no
+                // consumption or the tick was delayed — so all buffers stay
+                // aligned on the same 1px-per-second axis and the strip slides
+                // uniformly. A gap wider than the ring (sleep/resume) backfills
+                // only the window's most recent seconds.
+                const perSec = getSessionUsagePerSecond(60);
+                // Sample with a 2s lag: a consuming session's flush can land up
+                // to ~1s after the consumed second (1s write throttle + 1s
+                // tick, plus a queued lock wait), so a second is only sampled
+                // once every writer's data for it is on disk. Without the lag,
+                // a late flush would freeze the waveform at a partial bar.
+                const lastSec = Math.floor(Date.now() / 1_000) - 2;
+                let from = lastSampledSec === undefined ? lastSec : lastSampledSec + 1;
+                if (lastSec - from >= RING_SIZE) from = lastSec - RING_SIZE + 1;
+                for (let s = from; s <= lastSec; s++) {
+                    for (const p of active) {
+                        const secMap = perSec[p];
+                        appendSample(p, secMap ? secMap[s] ?? 0 : 0);
+                    }
+                }
+                lastSampledSec = lastSec;
+                render();
+            };
+            const cfg = buildEffectiveConfig();
+            await startSharedPoller(auth, DIRECT_FETCHERS, getApiKey, {
+                onTick: claimsOwnership ? onTick : undefined,
+                ownsUi,
+                redis: {
+                    enabled: cfg.redis_enabled,
+                    host: cfg.redis_host,
+                    port: cfg.redis_port,
+                    connectTimeoutMs: cfg.redis_connect_timeout_ms,
+                    commandTimeoutMs: cfg.redis_command_timeout_ms,
+                    reconcileIntervalMs: cfg.redis_reconcile_interval_ms,
+                    probeIntervalMs: cfg.redis_probe_interval_ms,
+                    unhealthyRetryMs: cfg.redis_unhealthy_retry_ms,
+                    ttlMs: cfg.redis_ttl_ms,
+                },
+            });
+            // One resize listener per process: each new owning session replaces
+            // the previous handler instead of accumulating. (ExtensionContext
+            // 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();
+            activeResizeHandler = onResize;
+            process.stdout.on('resize', onResize);
+            render();
+        } catch (e) {
+            warn(`[omp-opsx-addon] usage poller error: ${e}`);
+        }
+    });
+
+    // A completed turn just consumed quota on the CURRENT model — mark that
+    // provider dirty and run the fetch-due kernel immediately, so the widget
+    // reflects new consumption within one floor window (10s) instead of the
+    // 60s idle fallback. The per-provider floor prevents rapid back-to-back
+    // turns from hammering the API. A direct-fetcher provider
+    // (zhipu/minimax/deepseek/cursor) issues a single HTTP and never touches
+    // the bulk API; a non-direct provider falls back to bulk (5-min internal
+    // cache mitigates). Shares the poller's render callback. Silent on failure
+    // or when no authStorage.
+    pi.on('turn_end', async (_event, ctx) => {
+        try {
+            const currentModel = ctx.model;
+            const auth = ctx.modelRegistry?.authStorage;
+            const getApiKey = ctx.modelRegistry?.getApiKeyForProvider
+                ? (provider: string) => ctx.modelRegistry.getApiKeyForProvider(provider)
+                : undefined;
+            if (auth && currentModel?.provider) {
+                await pokeProvider(auth, DIRECT_FETCHERS, getApiKey, { providers: [currentModel.provider] });
+            }
+        } catch {
+            /* turn_end refresh is best-effort; stay silent */
+        }
+    });
+    // PRIMARY usage source, so the waveform reflects in-progress consumption
+    // and stays dense (message_end alone is sparse). `record` is monotonic MAX,
+    // so repeated chunk calls never double-count; the final message_end value
+    // (equal or higher) is a harmless re-record. In-process subagent sessions
+    // forward their usage through the eventBus channel (TASK_SUBAGENT_EVENT_CHANNEL)
+    // which this plugin subscribes to in session_start. Subagent consumption is
+    // recorded with subagent-specific keys and merged into the primary waveform.
+    pi.on('message_update', async (event) => {
+        try {
+            const ev = event.assistantMessageEvent;
+            if ('partial' in ev) {
+                const usage = assistantUsageOf(ev.partial);
+                if (usage) sessionUsageRecorder.record(usage.provider, usage.usage);
+            }
+        } catch {
+            /* usage recording is best-effort; stay silent */
+        }
+    });
+    // Final per-turn total — fallback for any message that ended without a
+    // nonzero streamed total (same monotonic MAX, no double count).
+    pi.on('message_end', async (event) => {
+        try {
+            const usage = assistantUsageOf(event.message);
+            if (usage) sessionUsageRecorder.record(usage.provider, usage.usage);
+        } catch {
+            /* usage recording is best-effort; stay silent */
+        }
+    });
+
+    // Session teardown: drop the cache entry THIS process wrote for the ending
+    // session. An in-process subagent never wrote one, so its shutdown is a
+    // no-op and the owner's aggregated consumption stays. A UI session ending
+    // in a multi-session process drops its own entry even when the recorder
+    // has since been re-keyed to another session.
+    pi.on('session_shutdown', async (_event, ctx) => {
+        try {
+            const sid = ctx?.sessionManager?.getSessionId?.();
+            if (sid && hasManagedSessionUsage(sid)) {
+                if (sid === sessionUsageRecorder.sessionId()) {
+                    sessionUsageRecorder.remove();
+                } else {
+                    removeSessionUsage(sid);
+                }
+                // Clean up eventBus subscription for subagent events
+                const unsubscribe = subagentEventUnsubscribers.get(sid);
+                if (unsubscribe) {
+                    try {
+                        unsubscribe();
+                        subagentEventUnsubscribers.delete(sid);
+                    } catch {
+                        /* best-effort */
+                    }
+                }
+            }
+            // Always clean up eventBus subscription, even if no usage was recorded
+            const cleanupUnsubscribe = subagentEventUnsubscribers.get(sid!);
+            if (cleanupUnsubscribe) {
+                try {
+                    cleanupUnsubscribe();
+                    subagentEventUnsubscribers.delete(sid!);
+                } catch {
+                    /* best-effort */
+                }
+            }
+        } catch {
+            /* best-effort */
+        }
+    });
+    // ── session lifecycle ─────────────────────────────────────────
+    // Pick-model is manual: `/pick-model refresh`. Session start does not pick or setModel.
+    const changeScanner = createCachedScanner(30_000);
+
+    pi.on('before_agent_start', async (event, ctx) => {
+        try {
+            // 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);
+            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.
+            const dynamic = buildDynamicPrompt(changes, opsxConfig, sel.selectorResults);
+            return { systemPrompt: [...event.systemPrompt, STATIC_PROMPT, dynamic] };
+        } catch (e) {
+            warn(`[omp-opsx-addon] before_agent_start error: ${e}`);
+            return { systemPrompt: event.systemPrompt };
+        }
+    });
+
+    pi.on('session_start', async (_event, ctx) => {
+        try {
+            const pinned = (role: Role): string | undefined => {
+                const v = opsxConfig.roles[role];
+                if (v.kind === 'auto') return undefined;
+                return roleValueToModelString(v);
+            };
+            await installAgents(
+                directory,
+                pinned('coder'),
+                pinned('reviewer'),
+                pinned('planner'),
+                pinned('proposal-reviewer'),
+            );
+            warn('[omp-opsx-addon] agents ready (pick-model idle until /pick-model refresh)');
+        } catch (e) {
+            warn('[omp-opsx-addon] installAgents 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;
+        if (!currentModel) return;
+        const canonical = canonicalizeProvider(currentModel.provider);
+        const auth = ctx.modelRegistry?.authStorage;
+        const getApiKey = ctx.modelRegistry?.getApiKeyForProvider
+            ? (provider: string) => ctx.modelRegistry.getApiKeyForProvider(provider)
+            : undefined;
+        // 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 });
+        const health = getSharedUsage()?.health ?? null;
+        pi.sendMessage(
+            { customType: 'pick-model', content: buildErrorDiagnosis(errorType, source, canonical, health), display: true },
+            { triggerTurn: false },
+        );
+    };
+    // 主要路径：provider API 响应直接返回 429/403（覆盖 primary session + 子 agent）
+    pi.on('after_provider_response', async (event, ctx) => {
+        try {
+            if (event.status === 429) {
+                await diagnoseProviderError(ctx, `HTTP ${event.status}`, '429');
+            } else if (event.status === 403) {
+                await diagnoseProviderError(ctx, `HTTP ${event.status}`, '403');
+            }
+        } catch (e) {
+            warn(`[omp-opsx-addon] after_provider_response error: ${e}`);
+        }
+    });
+    // 兜底路径：工具执行结果中包含 429/403 文本（子 agent 输出等场景）
+    pi.on('tool_execution_end', async (event, ctx) => {
+        try {
+            if (!event.isError) return;
+            const resultStr = typeof event.result === 'string' ? event.result : JSON.stringify(event.result ?? '');
+            const has429 =
+                hasRateLimitError(resultStr);
+            const has403 =
+                hasRegionError(resultStr);
+            if (has429) {
+                await diagnoseProviderError(ctx, event.toolName, '429');
+            } else if (has403) {
+                await diagnoseProviderError(ctx, event.toolName, '403');
+            }
+        } catch (e) {
+            warn(`[omp-opsx-addon] tool_execution_end error: ${e}`);
+        }
+    });
+    pi.on('input', async (event) => {
+        const match = event.text.match(/^@(coder|reviewer|planner|proposal-reviewer|code-reviewer)\b(.*)$/i);
+        if (!match) return;
+        const role = normalizeRole(match[1]);
+        const task = match[2].trim() || '开始工作';
+        if (!selection) {
+            return {
+                action: 'transform' as const,
+                text: `(model selector not ready)\n请使用 task 工具调用 ${AGENT_MAP[role]}。`,
+            };
+        }
+        return { action: 'transform' as const, text: buildDispatchPrompt(role, task, selection) };
+    });
+
+
+    pi.setLabel('pick-model', '模型选择');
+    pi.registerCommand('pick-model', {
+        description: '模型管理：choices 展示 / refresh 重选 / update 更新档位 / <selector> [--china] 按选择器约束（裸词·glob·provider/id 双段，如 zhipu*/glm*）/ reset 清除约束',
+        handler: async (args: string, ctx: ExtensionCommandContext) => {
+            try {
+                const parsed = parseAutoModelArgs(args);
+                if (parsed.kind === 'error') {
+                    pi.sendMessage({ customType: 'pick-model', content: `❌ ${parsed.message}`, display: true }, { triggerTurn: false });
+                    return;
+                }
+
+                // ── /pick-model update ──────────────────────────
+                if (parsed.kind === 'update') {
+                    const result = updateTiers();
+                    const msg = result.ok
+                        ? `✅ Tiers data updated: ${result.count} entries`
+                        : `❌ Update failed: ${result.error}`;
+                    pi.sendMessage({ customType: 'pick-model', content: msg, display: true }, { triggerTurn: false });
+                    return;
+                }
+
+                // ── /pick-model refresh (was model-switch) ──────
+                if (parsed.kind === 'refresh') {
+                    const auth = ctx.modelRegistry?.authStorage;
+                    const getApiKey = ctx.modelRegistry?.getApiKeyForProvider
+                        ? (provider: string) => ctx.modelRegistry.getApiKeyForProvider(provider)
+                        : undefined;
+                    if (auth) await pokeProvider(auth, DIRECT_FETCHERS, getApiKey, { force: true });
+                    const models = ctx.modelRegistry?.getAvailable() ?? [];
+                    const reach = await refreshReachability(models, opsxConfig);
+                    firstUnreachableProviders = reach.unreachable;
+                    availableByProvider = reach.availableByProvider;
+                    const health = getSharedUsage()?.health ?? null;
+                    const freshSel = computeSelectionSync(
+                        effectiveConfig,
+                        models,
+                        health,
+                        regionBlockedModels,
+                        reach.unreachable,
+                        reach.availableByProvider,
+                        familyConstraint,
+                    );
+                    const changes: string[] = [];
+                    // Check primary session model
+                    const currentModel = ctx.model;
+                    if (currentModel) {
+                        const primaryRole = findRoleForModel(currentModel.provider, currentModel.id, freshSel);
+                        const primaryResult = primaryRole ? freshSel.selectorResults[primaryRole] : undefined;
+                        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}`);
+                        }
+                    }
+                    // Check all agent models
+                    for (const role of OPSX_ROLES) {
+                        const result = freshSel.selectorResults[role];
+                        const picked = result?.picked;
+                        if (!picked) continue;
+                        const agent = AGENT_MAP[role];
+                        const pickedSel = `${picked.provider}/${picked.id}`;
+                        const roleCfg = opsxConfig.roles[role];
+                        if (roleCfg.kind === 'model' || roleCfg.kind === 'provider-model') {
+                            const pinned = roleValueToModelString(roleCfg);
+                            if (pinned && pinned !== pickedSel) {
+                                changes.push(`${agent} pinned ${pinned} → auto-pick ${pickedSel}`);
+                            }
+                        } else {
+                            changes.push(`${agent} → ${pickedSel}`);
+                        }
+                    }
+                    selection = freshSel;
+                    applyAgentModelOverrides(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 });
+                    }
+                    return;
+                }
+
+                // ── /pick-model reset ────────────────────────────────
+                if (parsed.kind === 'reset') {
+                    familyConstraint = null;
+                    effectiveConfig = opsxConfig;
+                    const auth = ctx.modelRegistry?.authStorage;
+                    const getApiKey = ctx.modelRegistry?.getApiKeyForProvider
+                        ? (provider: string) => ctx.modelRegistry.getApiKeyForProvider(provider)
+                        : undefined;
+                    if (auth) await pokeProvider(auth, DIRECT_FETCHERS, getApiKey, { force: true });
+                    const models = ctx.modelRegistry?.getAvailable() ?? [];
+                    const reach = await refreshReachability(models, opsxConfig);
+                    firstUnreachableProviders = reach.unreachable;
+                    availableByProvider = reach.availableByProvider;
+                    const health = getSharedUsage()?.health ?? null;
+                    const sel = computeSelectionSync(
+                        effectiveConfig,
+                        models,
+                        health,
+                        regionBlockedModels,
+                        reach.unreachable,
+                        reach.availableByProvider,
+                        familyConstraint,
+                    );
+                    const changes: string[] = [];
+                    const currentModel = ctx.model;
+                    const newPrimary = sel.selectorResults.reviewer?.picked;
+                    if (newPrimary) {
+                        const newSel = `${newPrimary.provider}/${newPrimary.id}`;
+                        const oldSel = currentModel ? `${currentModel.provider}/${currentModel.id}` : undefined;
+                        changes.push(oldSel && oldSel !== newSel ? `🏠 主会话 ${oldSel} → ${newSel}` : `🏠 主会话 → ${newSel}`);
+                    }
+                    for (const role of OPSX_ROLES) {
+                        const picked = sel.selectorResults[role]?.picked;
+                        if (!picked) continue;
+                        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}`);
+                    }
+                    if (newPrimary) await pi.setModel(newPrimary);
+                    selection = sel;
+                    selectionHealthKey = buildSelectionHealthKey(health, reach, familyConstraint);
+                    applyAgentModelOverrides(sel, true);
+                    pi.sendMessage({
+                        customType: 'pick-model',
+                        content: changes.length > 0
+                            ? `✅ 已清除 selector 约束，恢复默认选择:\n${changes.join('\n')}`
+                            : `✅ 已清除 selector 约束，恢复默认选择（无变化）`,
+                        display: true,
+                    }, { triggerTurn: false });
+                    return;
+                }
+
+                // ── /pick-model <selector> [--china] ──────────────
+                if (parsed.kind === 'selector') {
+                    const auth = ctx.modelRegistry?.authStorage;
+                    const getApiKey = ctx.modelRegistry?.getApiKeyForProvider
+                        ? (provider: string) => ctx.modelRegistry.getApiKeyForProvider(provider)
+                        : undefined;
+                    if (auth) await pokeProvider(auth, DIRECT_FETCHERS, getApiKey, { force: true });
+                    const models = ctx.modelRegistry?.getAvailable() ?? [];
+                    const reach = await refreshReachability(models, opsxConfig);
+                    firstUnreachableProviders = reach.unreachable;
+                    availableByProvider = reach.availableByProvider;
+                    const health = getSharedUsage()?.health ?? null;
+                    const excludeSelectors = parsed.china ? CHINA_EXCLUDE_FAMILIES : [];
+
+                    // Switch the session-scoped state BEFORE any recompute so every
+                    // later recompute path (ensureSelection, 429/403 auto-switch,
+                    // refresh) obeys the constraint.
+                    // Snapshot the previously-active constraint so a failed selector
+                    // command restores it rather than silently dropping an active one.
+                    const prevConstraint = familyConstraint;
+                    const prevEffective = effectiveConfig;
+                    familyConstraint = { selectors: parsed.selectors, excludeSelectors };
+                    effectiveConfig = buildEffectiveConfig();
+
+                    // Fail fast: an empty candidate set (or a role that cannot pick)
+                    // is a hard error — never silently pick nothing or change models.
+                    const preFiltered = filterSelectableModels(models, {
+                        blockedSelectors: regionBlockedModels,
+                        unreachableProviders: reach.unreachable,
+                        excludedProviders: effectiveConfig.excluded_providers,
+                        availableByProvider: reach.availableByProvider,
+                        selectors: parsed.selectors ?? undefined,
+                        excludeSelectors: excludeSelectors.length > 0 ? excludeSelectors : 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)}`,
+                            display: true,
+                        }, { triggerTurn: false });
+                        return;
+                    }
+
+                    const sel = computeSelectionSync(
+                        effectiveConfig,
+                        models,
+                        health,
+                        regionBlockedModels,
+                        reach.unreachable,
+                        reach.availableByProvider,
+                        familyConstraint,
+                    );
+                    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)}`,
+                            display: true,
+                        }, { triggerTurn: false });
+                        return;
+                    }
+
+                    const currentModel = ctx.model;
+                    const oldPrimary = currentModel ? `${currentModel.provider}/${currentModel.id}` : undefined;
+                    const oldRolePicks: Record<string, string | undefined> = {};
+                    for (const role of OPSX_ROLES) {
+                        const prev = selection?.selectorResults[role]?.picked;
+                        oldRolePicks[role] = prev ? `${prev.provider}/${prev.id}` : undefined;
+                    }
+
+                    const newPrimary = sel.selectorResults.reviewer?.picked;
+                    const changes: string[] = [];
+                    if (newPrimary) {
+                        const newSel = `${newPrimary.provider}/${newPrimary.id}`;
+                        changes.push(oldPrimary && oldPrimary !== newSel ? `🏠 主会话 ${oldPrimary} → ${newSel}` : `🏠 主会话 → ${newSel}`);
+                    }
+                    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}`);
+                    }
+
+                    // Cross-provider ambiguity hint (design Decision 8): only when a
+                    // selector is present and the candidate set spans >1 provider.
+                    let hint = '';
+                    const selectors = parsed.selectors;
+                    if (selectors) {
+                        const byProvider = new Map<string, number>();
+                        for (const m of preFiltered) {
+                            const p = m.provider.toLowerCase();
+                            byProvider.set(p, (byProvider.get(p) ?? 0) + 1);
+                        }
+                        if (byProvider.size > 1) {
+                            const sorted = [...byProvider.entries()].sort((a, b) => b[1] - a[1]);
+                            const counts = sorted.map(([p, c]) => `${p}(${c})`).join(' ');
+                            hint = `提示: ${selectors.join(' ')} 命中 ${counts}；用 ${sorted[0][0]}*/${buildSuggestedIdSeg(selectors)} 可锁定单一 provider`;
+                        }
+                    }
+
+                    if (newPrimary) await pi.setModel(newPrimary);
+                    selection = sel;
+                    selectionHealthKey = buildSelectionHealthKey(health, reach, familyConstraint);
+                    applyAgentModelOverrides(sel);
+                    const content = `✅ 已切换 selector 约束 (${formatFamilyConstraint(familyConstraint)}):\n${changes.join('\n')}${hint ? `\n${hint}` : ''}`;
+                    pi.sendMessage({
+                        customType: 'pick-model',
+                        content,
+                        display: true,
+                    }, { triggerTurn: false });
+                    return;
+                }
+
+                // ── /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 });
+            } catch (e) {
+                warn(`[omp-opsx-addon] /pick-model error: ${e}`);
+                pi.sendMessage({ customType: 'pick-model', content: `❌ Error: ${e}`, display: true }, { triggerTurn: false });
+            }
+        },
+    });
+
+    // Auto-refresh tier data on first load if missing or stale
+    if (autoRefreshTiersIfStale()) {
+        warn('[omp-opsx-addon] Auto-refreshed tiers data (missing or stale)');
+    }
+    for (const role of Object.keys(AGENT_MAP) as Role[]) {
+        const agent = AGENT_MAP[role];
+        pi.registerCommand(role, {
+            description: `Dispatch to ${agent} via task`,
+            handler: async (args: string, _ctx: ExtensionCommandContext) => {
+                try {
+                    const sel = await getSelectionForCommand(_ctx);
+                    pi.sendUserMessage(buildDispatchPrompt(role, args.trim() || '开始工作', sel));
+                } catch (e) {
+                    warn(`[omp-opsx-addon] /${role} error: ${e}`);
+                }
+            },
+        });
+    }
+
+    async function getSelectionForCommand(ctx: ExtensionCommandContext): Promise<SelectionContext> {
+        if (selection) return selection;
+        return ensureSelection(ctx);
+    }
+};