@genee/omp-opsx-addon 0.3.0 → 0.5.0

package/index.ts

@@ -1,19 +1,18 @@
 // ── 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.
+// The harness forwards every task-subagent message as a SubagentEventPayload
+// { id, event } frame on the "task:subagent:event" channel, emitted to the
+// parent session's eventBus (plus the root observability bus, which is not
+// reachable from extensions). Each plugin instance subscribes its OWN session
+// bus via the official ExtensionAPI handle `pi.events` — the EventBus the
+// harness injects as ConcreteExtensionAPI's `events` field (loader.ts). The
+// root instance's bus carries depth-1 frames, a depth-1 instance's bus carries
+// depth-2 frames, and so on, so every nesting depth is covered while each
+// frame is consumed exactly once. Frames funnel into the module-level recorder
+// singleton below, attributed to the root session id.
 //
-// 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:
+// 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
@@ -23,42 +22,18 @@ 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;
-            }
-        }
+// Official session-bus handle accessor. `ExtensionAPI` declares
+// `events: EventBus` and the harness injects the session bus as
+// ConcreteExtensionAPI's `events` field, so this is a typed read; the runtime
+// shape check only defends against older hosts whose dist predates the field.
+function getPluginEventBus(pi: ExtensionAPI): ExtensionAPI['events'] | undefined {
+    const events = pi.events;
+    if (events && typeof events === 'object' && typeof events.on === 'function') {
+        return events;
     }
     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 {
@@ -104,23 +79,36 @@ function handleSubagentEvent(payload: unknown, primarySessionId: string): void {
         sessionUsageRecorder.record(canonicalizeProvider(provider), usage, subagentStreamKey);
     } catch (err) {
         // Silently fail to avoid breaking the plugin
-        console.error('Failed to handle subagent event:', err);
+        getLogger().error('Failed to handle subagent event', { err });
     }
 }
-import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from '@oh-my-pi/pi-coding-agent';
+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 { 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 {
+    applyRoleModelOverrides,
+    buildRoleOverridePlan,
+    dispatchModelHint,
+    frontmatterModel,
+    ROLE_TO_OMP_ALIAS,
+    OMP_ROLE_TO_TIER,
+    ROLE_CAPABILITY,
+    type SkippedRole,
+} from './lib/model-roles.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 { selectAllRoles, selectModel, mergePlanProviders, type SelectorResult } from './lib/model-selector.js';
+import { scoreModelWithProvider, type TierName } 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 { markExhausted, markAvailable, getExhaustedProviders } from './lib/provider-status.js';
+import { registerPipeCore } from './lib/pipe-core.js';
+import { registerPipePush } from './lib/pipe-push.js';
 import { scheduleStatusProbes } from './lib/status-probe.js';
 import {
     startSharedPoller,
@@ -158,6 +146,7 @@ import { filterSelectableModels, reachabilityFingerprint } from './lib/selection
 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';
+import { setOpsxLogger, getLogger } from './lib/logger.js';
 type Role = 'coder' | 'reviewer' | 'planner' | 'proposal-reviewer';
 
 /** Session-scoped selector constraint for `/pick-model <selector> [--china]`. */
@@ -266,24 +255,17 @@ export interface SelectionContext {
     roleModels: Record<Role, string | undefined>;
     /** Display label for each role from config, e.g. "auto", "smol", "deepseek-v4-pro". */
     roleConfigs: Record<Role, string | undefined>;
+    /** Parsed role value kind for each role (auto | omp-alias | model | provider-model). */
+    roleKind: Record<Role, RoleValue['kind']>;
+    /** Full-role session overlay payload written to `overrideModelRoles` (all known OMP roles). */
+    roleOverrides: Record<string, string>;
+    /** Known roles left out of the overlay payload (config skip / capability gate / no pick). */
+    skippedRoles: SkippedRole[];
 }
 
 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;
@@ -314,19 +296,39 @@ function synthPinnedResult(role: string, modelString: string | undefined): Selec
 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。`];
+    // auto roles (and omp-alias roles such as @slow) pass NO model: requestModel
+    // is the top-priority resolution layer and would shadow the frontmatter
+    // tier-role alias. Only concrete provider/model pins stay explicit.
+    const modelHint = dispatchModelHint(role, selection);
+    const parts = [`你的 opsx.${role} 模型由 role 自动解析。`];
     if (modelHint) parts.push(`请通过 task 工具调用 ${agent} 并指定 model="${modelHint}"。`);
-    else parts.push(`请通过 task 工具调用 ${agent}。`);
+    else parts.push(`请直接通过 task 工具调用 ${agent}（无需指定 model，模型按 role 自动解析）。`);
     if (sel?.decision) parts.push(`原因: ${sel.decision}`);
     parts.push('直接用内置工具实现。');
     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>,
@@ -348,16 +350,23 @@ function computeSelectionSync(
     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);
     for (const role of OPSX_ROLES) {
         const value = config.roles[role];
-        roleConfigs[role] = value.kind === 'auto' ? ROLE_TO_OMP_ALIAS[role] : (roleValueToModelString(value) ?? '?');
+        roleKind[role] = value.kind;
+        // Config label shown in /pick-model choices markdown (`角色 (label)`):
+        // auto roles display the OMP tier-role alias; pinned roles the pin.
+        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 tier = (config.roleTiers[role]
+                    ?? (OMP_ROLE_TO_TIER as Record<string, TierName>)[ompRole]
+                    ?? 'mid') as TierName;
                 const roleTiers = { ...config.roleTiers, [role]: tier };
                 const result = selectAllRoles(
                     [role],
@@ -388,9 +397,56 @@ function computeSelectionSync(
             roleModels[role] = modelString?.includes('/') ? modelString : undefined;
         }
     }
-    return { selectorResults, roleModels, roleConfigs };
+    // 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.
+    let roleOverrides: Record<string, string> = {};
+    let skippedRoles: SkippedRole[] = [];
+    if (filteredModels && filteredModels.length > 0) {
+        const pickString = (r: SelectorResult): string | undefined =>
+            r.picked ? `${r.picked.provider}/${r.picked.id}` : undefined;
+        const tierPicks: Partial<Record<TierName, string | undefined>> = {
+            mid: pickString(selectorResults.coder),
+            high: pickString(selectorResults.reviewer),
+        };
+        for (const supplementalTier of ['tiny', 'low', 'top'] as const) {
+            const synthRole = `__tier_${supplementalTier}`;
+            const result = selectModel({
+                role: synthRole,
+                models: filteredModels,
+                roleTiers: { [synthRole]: supplementalTier },
+                tierOverrides: config.tierOverrides,
+                health: health ?? undefined,
+                allowlist: config.modelAllowlist,
+                planProviders: planSet,
+            });
+            tierPicks[supplementalTier] = pickString(result);
+        }
+        const capabilityPicks: Record<string, string | undefined> = {};
+        const visionModels = filteredModels.filter((m) => ROLE_CAPABILITY.vision(m));
+        if (visionModels.length > 0) {
+            const visionResult = selectModel({
+                role: 'vision',
+                models: visionModels,
+                roleTiers: { vision: 'high' },
+                tierOverrides: config.tierOverrides,
+                health: health ?? undefined,
+                allowlist: config.modelAllowlist,
+                planProviders: planSet,
+            });
+            capabilityPicks.vision = pickString(visionResult);
+        }
+        const plan = buildRoleOverridePlan(
+            { knownRoleIds, ompRoleTiers: config.ompRoleTiers, tierPicks, capabilityPicks },
+            (m) => getLogger().warn(m),
+        );
+        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;
@@ -459,19 +515,25 @@ function formatFamilyTierMarkdown(sel: SelectionContext): string {
     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.
+// ── process-wide usage recorder singleton ──────────────────────────
+// This IS a process-wide singleton: the harness rebinds the same evaluated
+// plugin module to a fresh ExtensionAPI instance for every session, including
+// in-process task subagents (task/executor.ts), WITHOUT re-evaluating the
+// module graph — so every instance shares the recorder created here. Only the
+// owning session (has a UI, or is the first headless session) re-keys it via
+// setSessionId; rebind instances never re-key and never write usage through
+// their own message_* handlers (gated by recordsOwnUsage below). Subagent
+// consumption reaches this recorder exclusively through the bus-subscription
+// mechanism (see file header):
+// - Each instance subscribes its own session bus (pi.events) to
+//   TASK_SUBAGENT_EVENT_CHANNEL ("task:subagent:event"); depth-N frames land
+//   on the depth-(N-1) session's bus, so all depths are covered.
+// - Subscription callbacks attribute frames to the recorder's root session id
+//   with per-subagent stream keys (stream keys only — the recorder is never
+//   re-keyed, so the owner's cumulative baseline survives and streams don't
+//   double-count).
+// Session totals persist into the shared usage cache, which every process
+// aggregates on read.
 const sessionUsageRecorder: SessionUsageRecorder = createSessionUsageRecorder({
     write: writeSessionUsage,
     remove: removeSessionUsage,
@@ -481,6 +543,9 @@ const sessionUsageRecorder: SessionUsageRecorder = createSessionUsageRecorder({
 // ── plugin entry ────────────────────────────────────────────────────
 
 export default (pi: ExtensionAPI) => {
+    // Route plugin logging through the host logger (rolling file) instead of
+    // console.*, which would corrupt the TUI. Injected before any log path runs.
+    setOpsxLogger(pi.logger);
     // 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
@@ -492,7 +557,11 @@ export default (pi: ExtensionAPI) => {
     // 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 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);
     // Static orchestration rules — built once, reused every turn for cache stability.
     const STATIC_PROMPT = buildStaticPrompt();
@@ -583,6 +652,7 @@ export default (pi: ExtensionAPI) => {
                 effectiveConfig,
                 models,
                 health,
+                currentKnownRoleIds(),
                 regionBlockedModels,
                 reach.unreachable,
                 reach.availableByProvider,
@@ -596,32 +666,28 @@ export default (pi: ExtensionAPI) => {
         });
         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(', ')}`,
-            );
-        }
+    // Apply selector picks by TIER to session-scoped OMP modelRoles (smol =
+    // coder/mid, default = reviewer/high), so every role-resolving agent —
+    // including built-in scout (smol) — follows selector/refresh/reset.
+    // Persisted per-agent pins are neutralized at runtime with empty strings.
+    // 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). This thin wrapper is the single call site the
+    // constrained-period tick-reselect path (auto-model-family) also uses.
+    const applyRoleModel = (sel: SelectionContext): void => {
+        applyRoleModelOverrides(pi.pi?.settings, sel, warn);
     };
 
+    // Instance-level usage-record claim: true only while this instance's
+    // session owns the process-wide recorder (claimsOwnership in session_start
+    // below). Rebind instances (in-process task subagents) keep it false —
+    // their message_* handlers must not write the default stream, because that
+    // consumption is captured exactly once by the parent instance's bus
+    // subscription with a subagent stream key. Closure variable, not
+    // module-level: rebind reuses the evaluated module, so a module-level flag
+    // would be overwritten by whichever instance starts last.
+    let recordsOwnUsage = false;
+
     // ── shared usage poller + widget ──────────────────────────────
     pi.on('session_start', async (_event, ctx) => {
         try {
@@ -647,30 +713,38 @@ export default (pi: ExtensionAPI) => {
             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);
+            recordsOwnUsage = claimsOwnership;
+            // Every instance subscribes its OWN session bus (pi.events) to the
+            // subagent channel — record ownership and subscription rights are
+            // decoupled: the root instance's bus carries depth-1 frames, a
+            // depth-1 instance's bus carries depth-2 frames, and each frame is
+            // consumed exactly once (see file header). Callbacks attribute
+            // frames to the recorder singleton's root session id (the module
+            // graph is shared across rebinds), falling back to this session's
+            // own id only before the owner has claimed.
+            const sessionId = ctx.sessionManager?.getSessionId?.() ?? '';
+            const pluginEventBus = getPluginEventBus(pi);
+            if (pluginEventBus) {
+                // 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 = pluginEventBus.on(TASK_SUBAGENT_EVENT_CHANNEL, (payload) => {
+                    handleSubagentEvent(payload, sessionUsageRecorder.sessionId() || sessionId);
+                });
+                subagentEventUnsubscribers.set(sessionId, unsubscribe);
+                getLogger().info(
+                    `[omp-opsx-addon] subagent usage capture subscribed (sid=${sessionId}, channel=${TASK_SUBAGENT_EVENT_CHANNEL})`,
+                );
+            } else {
+                getLogger().warn(
+                    '[omp-opsx-addon] pi.events handle unavailable — subagent usage capture disabled (subagent consumption will not be recorded)',
+                );
             }
             const auth = ctx.modelRegistry?.authStorage;
             const getApiKey = ctx.modelRegistry?.getApiKeyForProvider
@@ -906,12 +980,14 @@ export default (pi: ExtensionAPI) => {
     // 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.
+    // (equal or higher) is a harmless re-record. Only the recorder-owning
+    // instance writes here: task-subagent rebind instances skip these handlers,
+    // because their consumption reaches the recorder through the parent
+    // instance's bus subscription instead (subagent-specific stream keys,
+    // merged into the primary waveform).
     pi.on('message_update', async (event) => {
         try {
+            if (!recordsOwnUsage) return;
             const ev = event.assistantMessageEvent;
             if ('partial' in ev) {
                 const usage = assistantUsageOf(ev.partial);
@@ -925,6 +1001,7 @@ export default (pi: ExtensionAPI) => {
     // nonzero streamed total (same monotonic MAX, no double count).
     pi.on('message_end', async (event) => {
         try {
+            if (!recordsOwnUsage) return;
             const usage = assistantUsageOf(event.message);
             if (usage) sessionUsageRecorder.record(canonicalizeProvider(usage.provider), usage.usage);
         } catch {
@@ -958,13 +1035,15 @@ export default (pi: ExtensionAPI) => {
                 }
             }
             // 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 */
+            if (sid) {
+                const cleanupUnsubscribe = subagentEventUnsubscribers.get(sid);
+                if (cleanupUnsubscribe) {
+                    try {
+                        cleanupUnsubscribe();
+                        subagentEventUnsubscribers.delete(sid);
+                    } catch {
+                        /* best-effort */
+                    }
                 }
             }
         } catch {
@@ -980,7 +1059,12 @@ export default (pi: ExtensionAPI) => {
             // 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 sel = selection ?? computeSelectionSync(
+                opsxConfig,
+                null,
+                null,
+                safeGetKnownRoleIds(pi.pi?.settings),
+            );
             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.
@@ -994,17 +1078,14 @@ export default (pi: ExtensionAPI) => {
 
     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);
-            };
+            const frontmatter = (role: Role): string | undefined =>
+                frontmatterModel(role, opsxConfig.roles[role]);
             await installAgents(
                 directory,
-                pinned('coder'),
-                pinned('reviewer'),
-                pinned('planner'),
-                pinned('proposal-reviewer'),
+                frontmatter('coder'),
+                frontmatter('reviewer'),
+                frontmatter('planner'),
+                frontmatter('proposal-reviewer'),
             );
             warn('[omp-opsx-addon] agents ready (pick-model idle until /pick-model refresh)');
         } catch (e) {
@@ -1020,7 +1101,7 @@ export default (pi: ExtensionAPI) => {
         const getApiKey = ctx.modelRegistry?.getApiKeyForProvider
             ? (provider: string) => ctx.modelRegistry.getApiKeyForProvider(provider)
             : undefined;
-        // 429/403 is the only observable exhaustion evidence for providers
+        // Provider exhaustion seen on the response/tool path; mark it locally
         // without a usage fetcher — record it in the process-local binary status
         // so the placeholder column reads 耗尽 (see lib/provider-status.ts).
         markExhausted(canonical);
@@ -1119,6 +1200,7 @@ export default (pi: ExtensionAPI) => {
                         effectiveConfig,
                         models,
                         health,
+                        currentKnownRoleIds(),
                         regionBlockedModels,
                         reach.unreachable,
                         reach.availableByProvider,
@@ -1154,7 +1236,7 @@ export default (pi: ExtensionAPI) => {
                         }
                     }
                     selection = freshSel;
-                    applyAgentModelOverrides(freshSel);
+                    applyRoleModel(freshSel);
                     if (changes.length > 0) {
                         pi.sendMessage({ customType: 'pick-model', content: `✅ 模型已刷新:\n${changes.join('\n')}`, display: true }, { triggerTurn: false });
                     } else {
@@ -1181,6 +1263,7 @@ export default (pi: ExtensionAPI) => {
                         effectiveConfig,
                         models,
                         health,
+                        currentKnownRoleIds(),
                         regionBlockedModels,
                         reach.unreachable,
                         reach.availableByProvider,
@@ -1205,7 +1288,7 @@ export default (pi: ExtensionAPI) => {
                     if (newPrimary) await pi.setModel(newPrimary);
                     selection = sel;
                     selectionHealthKey = buildSelectionHealthKey(health, reach, familyConstraint);
-                    applyAgentModelOverrides(sel, true);
+                    applyRoleModel(sel);
                     pi.sendMessage({
                         customType: 'pick-model',
                         content: changes.length > 0
@@ -1265,6 +1348,7 @@ export default (pi: ExtensionAPI) => {
                         effectiveConfig,
                         models,
                         health,
+                        currentKnownRoleIds(),
                         regionBlockedModels,
                         reach.unreachable,
                         reach.availableByProvider,
@@ -1324,7 +1408,7 @@ export default (pi: ExtensionAPI) => {
                     if (newPrimary) await pi.setModel(newPrimary);
                     selection = sel;
                     selectionHealthKey = buildSelectionHealthKey(health, reach, familyConstraint);
-                    applyAgentModelOverrides(sel);
+                    applyRoleModel(sel);
                     const content = `✅ 已切换 selector 约束 (${formatFamilyConstraint(familyConstraint)}):\n${changes.join('\n')}${hint ? `\n${hint}` : ''}`;
                     pi.sendMessage({
                         customType: 'pick-model',
@@ -1379,4 +1463,14 @@ export default (pi: ExtensionAPI) => {
         if (selection) return selection;
         return ensureSelection(ctx);
     }
+
+    // Cross-broker project-scoped pipe core: registers opsx_pipe_list /
+    // _send / _recv / _wait and starts presence heartbeat + GC on
+    // session_start (managed timers inside lib/pipe-core).
+    registerPipeCore(pi);
+
+    // Cross-broker push/injector: watches the local mbox slot and injects
+    // inbound pipe messages as custom (opsx-pipe) turns; /opsx-pipe mute
+    // toggles the stop-injection flag (managed timers inside lib/pipe-push).
+    registerPipePush(pi);
 };