@genee/omp-opsx-addon 0.7.0 → 0.9.0

package/lib/concurrency-control.ts

@@ -0,0 +1,1246 @@
+/**
+ * Adaptive per-provider concurrency: signal collection + control-loop
+ * orchestration.
+ *
+ * The pure AIMD state machine and the host-signal parsers live in
+ * `concurrency-tuner.ts`; the config/lease write path lives in
+ * `concurrency-writer.ts`. This module only wires the two together:
+ *
+ *   host render tick (the existing second-level tick; absolute-time gated by
+ *   `concurrency_eval_interval_ms` — this module MUST NOT create a timer)
+ *     ├─ ① explicit rate-limit / timeout events, delivered in-process
+ *     │    (`noteExplicitFailure`, reusing `error-scan`'s `hasRateLimitError`)
+ *     │    and aggregated across processes through the injected Redis port
+ *     ├─ ② queue waits from the incremental host-log reader (every pid under
+ *     │    the same config root; guardrail input only, never a bad event)
+ *     └─ ③④ generation-duration / throughput from `agent.db:model_perf`
+ *
+ * Every IO source is an injected port (fs / model_perf / redis / settings /
+ * lease), so the module runs with zero real IO in tests; the production
+ * implementations live here and are wired by the assembly layer.
+ */
+
+import { Database } from 'bun:sqlite';
+import { createHash } from 'node:crypto';
+import { closeSync, openSync, readSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import {
+    BLOCKED_MESSAGE,
+    WAIT_COMPLETED_MESSAGE,
+    TUNER_DEFAULTS,
+    clampLimit,
+    createProviderState,
+    diffModelPerf,
+    evaluateWindow,
+    formatConcurrencySummary,
+    parseInFlightLogLines,
+    queueWaitPercentiles,
+    updatePerfBaseline,
+    type BadEventKind,
+    type ModelPerfRow,
+    type PerfBaseline,
+    type ProviderConcurrencyState,
+    type ProviderPerfWindow,
+    type QueueWaitSample,
+    type TunerOptions,
+    type WindowSignals,
+} from './concurrency-tuner.js';
+import {
+    applyLimit,
+    buildMergedMap,
+    createLease,
+    readManagedLimits,
+    resolveTakeoverStart,
+    shouldWriteLimit,
+    writeManagedLimit,
+    type LeaseHandle,
+    type LeaseMode,
+    type SettingsPort,
+    type WriteManagedLimitResult,
+} from './concurrency-writer.js';
+import {
+    STATE_FILE_NAME,
+    applyDecayStep,
+    loadConcurrencyState,
+    restoreLimit,
+    saveConcurrencyState,
+    stopFailSafe,
+    toStateFile,
+    type ConcurrencyStateFile,
+    type PersistedProviderState,
+} from './concurrency-state.js';
+import { hasRateLimitError } from './error-scan.js';
+import { canonicalizeProvider } from './usage-resolver.js';
+import type { RedisReply } from './usage-redis-client.js';
+
+/** Warn sink; the assembly layer passes the plugin logger. */
+export type ConcurrencyWarn = (message: string) => void;
+
+/** Host log file name pattern (`omp.<date>.<pid>.log`). */
+export const LOG_FILE_PATTERN = /^omp\..*\.log$/;
+/** Newest log files read per tick (all pids under the same config root). */
+export const DEFAULT_MAX_LOG_FILES = 4;
+/** Tail probe size for the runtime debug-signal self-check. */
+export const DEFAULT_LOG_PROBE_BYTES = 64 * 1024;
+/** Hard cap on an unterminated log line before its bytes are dropped. */
+export const MAX_LOG_LINE_BYTES = 1 << 20;
+/** Recent log lines retained so a `blocked`/`wait completed` pair can span ticks. */
+export const MAX_BUFFERED_LOG_LINES = 5_000;
+/** File-lease name under the config root (Redis lease preferred). */
+export const LEASE_LOCK_FILENAME = 'opsx-concurrency-tuner.lock';
+/** `concurrency_write_min_interval_ms` default — minimum spacing between writes. */
+export const DEFAULT_WRITE_MIN_INTERVAL_MS = 20_000;
+/** Redis counter key namespace for cross-process ① aggregation. */
+export const RATE_LIMIT_REDIS_PREFIX = 'opsx:concurrency:rl';
+/** Aggregation counter TTL, in evaluation intervals. */
+export const AGGREGATION_TTL_INTERVALS = 4;
+
+// ── Injected ports ──────────────────────────────────────────────────────────
+
+/** Filesystem seam for the log reader (synchronous; the tick is sync-friendly). */
+export interface ConcurrencyFsPort {
+    /** Directory entry names; throws when the directory is unreadable. */
+    readdir(dir: string): string[];
+    /** Size/mtime (+ inode when the platform exposes one); throws when unreadable. */
+    stat(path: string): { size: number; mtimeMs: number; ino?: number };
+    /** UTF-8 text for byte range `[start, end)`; throws when unreadable. */
+    readRange(path: string, start: number, end: number): string;
+}
+
+/** Read-only `model_perf` source (cumulative counters). */
+export interface ModelPerfPort {
+    /** Cumulative rows; throws when the DB is missing/locked/without the table. */
+    readModelPerf(): ModelPerfRow[];
+}
+
+/** Minimal Redis seam: the batched-command surface of `RedisClient.pipeline()`. */
+export interface ConcurrencyRedisPort {
+    pipeline(commands: string[][]): Promise<RedisReply[]>;
+}
+
+/** Settings hot-apply seam (`pi.pi.settings`); `override` is whole-key. */
+export type { SettingsPort };
+
+/** Lease surface the loop drives, as produced by the writer's `createLease`. */
+export type ConcurrencyLease = LeaseHandle;
+
+export interface ConcurrencyLeaseArgs {
+    redis: ConcurrencyRedisPort | null;
+    lockPath: string;
+    owner: string;
+    ttlMs: number;
+    now: () => number;
+}
+
+export type ConcurrencyLeaseFactory = (args: ConcurrencyLeaseArgs) => Promise<ConcurrencyLease>;
+
+const defaultLeaseFactory: ConcurrencyLeaseFactory = (args) =>
+    createLease({
+        redis: args.redis,
+        lockPath: args.lockPath,
+        owner: args.owner,
+        ttlMs: args.ttlMs,
+        now: args.now,
+    });
+
+/** Production fs port backed by `node:fs`. */
+export function createNodeFsPort(): ConcurrencyFsPort {
+    return {
+        readdir: (dir) => readdirSync(dir),
+        stat: (path) => {
+            const st = statSync(path);
+            return {
+                size: st.size,
+                mtimeMs: st.mtimeMs,
+                ino: typeof st.ino === 'number' && st.ino > 0 ? st.ino : undefined,
+            };
+        },
+        readRange: (path, start, end) => {
+            const length = Math.max(0, end - start);
+            if (length === 0) return '';
+            const fd = openSync(path, 'r');
+            try {
+                const buf = Buffer.allocUnsafe(length);
+                const read = readSync(fd, buf, 0, length, start);
+                return buf.subarray(0, read).toString('utf8');
+            } finally {
+                closeSync(fd);
+            }
+        },
+    };
+}
+
+/** Read-only `bun:sqlite` port over `<agentDir>/agent.db`. */
+export function createSqliteModelPerfPort(dbPath: string): ModelPerfPort {
+    return {
+        readModelPerf(): ModelPerfRow[] {
+            const db = new Database(dbPath, { readonly: true });
+            try {
+                const rows = db
+                    .query('SELECT model_key, samples, output_tokens, gen_ms FROM model_perf')
+                    .all() as Array<Record<string, unknown>>;
+                const count = (value: unknown): number => {
+                    if (typeof value === 'number' && Number.isFinite(value)) return value;
+                    if (typeof value === 'bigint') return Number(value);
+                    return 0;
+                };
+                const out: ModelPerfRow[] = [];
+                for (const row of rows) {
+                    const modelKey = row.model_key;
+                    if (typeof modelKey !== 'string' || modelKey === '') continue;
+                    out.push({
+                        modelKey,
+                        samples: count(row.samples),
+                        outputTokens: count(row.output_tokens),
+                        genMs: count(row.gen_ms),
+                    });
+                }
+                return out;
+            } finally {
+                db.close();
+            }
+        },
+    };
+}
+
+// ── Path derivation (tasks 3.2 / 3.3) ───────────────────────────────────────
+
+/** `settings.getAgentDir()` when present, else `<homedir>/.omp/agent`. */
+export function deriveAgentDir(agentDir: string | null | undefined): string {
+    return agentDir && agentDir.length > 0 ? agentDir : join(homedir(), '.omp', 'agent');
+}
+
+/** Host log directory for an agent dir (`<agentDir>/../logs`). */
+export function deriveLogDir(agentDir: string | null | undefined): string {
+    return join(deriveAgentDir(agentDir), '..', 'logs');
+}
+
+/** `model_perf` DB path for an agent dir. */
+export function deriveDbPath(agentDir: string | null | undefined): string {
+    return join(deriveAgentDir(agentDir), 'agent.db');
+}
+
+/** Stable per-config-root hash used in Redis keys. */
+export function configRootHash(configPath: string): string {
+    return createHash('sha1').update(resolvePath(dirname(configPath))).digest('hex').slice(0, 12);
+}
+
+// ── Incremental host-log reader (signal ②) ──────────────────────────────────
+
+export interface IncrementalLogSourceOptions {
+    maxFiles?: number;
+    warn?: ConcurrencyWarn;
+}
+
+interface TrackedLogFile {
+    /** Byte offset of the next unread byte. */
+    offset: number;
+    ino: number | null;
+}
+
+/**
+ * Byte-offset tailer over the host's `omp.*.log` files.
+ *
+ * The reader is shared by every pid under the same config root, so a wait
+ * blocked in one process is visible here. A file seen for the first time is
+ * tailed from its current end (joining mid-stream must not replay stale
+ * `blocked` lines and pair them with fresh completions); a rotated (inode
+ * change) or truncated (size < offset) file is re-read from byte 0. Failure to
+ * list/stat/read is warned once and skipped — collection never throws.
+ */
+export class IncrementalLogSource {
+    private readonly tracked = new Map<string, TrackedLogFile>();
+    private readonly warned = new Set<string>();
+    private readonly maxFiles: number;
+    private readonly warn: ConcurrencyWarn;
+
+    constructor(
+        private readonly fs: ConcurrencyFsPort,
+        private readonly logDir: string,
+        options: IncrementalLogSourceOptions = {},
+    ) {
+        this.maxFiles = Math.max(1, options.maxFiles ?? DEFAULT_MAX_LOG_FILES);
+        this.warn = options.warn ?? (() => {});
+    }
+
+    /** New complete lines from every selected log file since the previous call. */
+    readNewLines(): string[] {
+        const lines: string[] = [];
+        for (const file of this.listLogFiles()) {
+            for (const line of this.readFile(file)) lines.push(line);
+        }
+        return lines;
+    }
+
+    /**
+     * Runtime self-check (tasks 3.2): does the newest log currently carry a
+     * `level=debug` in-flight `blocked` / `wait completed` line? Signal ② is
+     * empty when the host raises the log level or turns debug off, so the
+     * assembly runs this once and surfaces the outcome in the summary.
+     */
+    probeDebugInFlightLines(probeBytes = DEFAULT_LOG_PROBE_BYTES): boolean {
+        const files = this.listLogFiles();
+        if (files.length === 0) return false;
+        const newest = files.reduce((a, b) => (b.mtimeMs > a.mtimeMs ? b : a));
+        const start = Math.max(0, newest.size - Math.max(1, probeBytes));
+        let text: string;
+        try {
+            text = this.fs.readRange(newest.path, start, newest.size);
+        } catch {
+            this.warnOnce(`probe:${newest.path}`, `[omp-opsx-addon] concurrency: log self-check cannot read ${newest.path}`);
+            return false;
+        }
+        for (const raw of text.split('\n')) {
+            const line = raw.trim();
+            if (line === '') continue;
+            let rec: Record<string, unknown>;
+            try {
+                const parsed: unknown = JSON.parse(line);
+                if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) continue;
+                rec = parsed as Record<string, unknown>;
+            } catch {
+                continue;
+            }
+            if (rec.level !== 'debug') continue;
+            if (rec.message === BLOCKED_MESSAGE || rec.message === WAIT_COMPLETED_MESSAGE) return true;
+        }
+        return false;
+    }
+
+    private listLogFiles(): Array<{ path: string; size: number; mtimeMs: number; ino?: number }> {
+        let names: string[];
+        try {
+            names = this.fs.readdir(this.logDir);
+        } catch (err) {
+            this.warnOnce('readdir', `[omp-opsx-addon] concurrency: log dir unreadable (${this.logDir}): ${describe(err)}`);
+            return [];
+        }
+        const files: Array<{ path: string; size: number; mtimeMs: number; ino?: number }> = [];
+        for (const name of names) {
+            if (!LOG_FILE_PATTERN.test(name)) continue;
+            const path = join(this.logDir, name);
+            try {
+                const st = this.fs.stat(path);
+                files.push({ path, size: st.size, mtimeMs: st.mtimeMs, ino: st.ino });
+            } catch (err) {
+                this.warnOnce(`stat:${path}`, `[omp-opsx-addon] concurrency: log file unreadable (${path}): ${describe(err)}`);
+            }
+        }
+        const present = new Set(files.map((f) => f.path));
+        for (const path of [...this.tracked.keys()]) {
+            if (!present.has(path)) this.tracked.delete(path);
+        }
+        files.sort((a, b) => b.mtimeMs - a.mtimeMs);
+        return files.slice(0, this.maxFiles);
+    }
+
+    private readFile(file: { path: string; size: number; mtimeMs: number; ino?: number }): string[] {
+        const ino = typeof file.ino === 'number' ? file.ino : null;
+        const tracked = this.tracked.get(file.path);
+        if (!tracked) {
+            this.tracked.set(file.path, { offset: file.size, ino });
+            return [];
+        }
+        const rotated = ino !== null && tracked.ino !== null && ino !== tracked.ino;
+        if (rotated || file.size < tracked.offset) {
+            tracked.offset = 0;
+            tracked.ino = ino;
+        } else if (ino !== null) {
+            tracked.ino = ino;
+        }
+        if (file.size <= tracked.offset) return [];
+
+        let text: string;
+        try {
+            text = this.fs.readRange(file.path, tracked.offset, file.size);
+        } catch (err) {
+            this.warnOnce(`read:${file.path}`, `[omp-opsx-addon] concurrency: log file read failed (${file.path}): ${describe(err)}`);
+            return [];
+        }
+        const lastNewline = text.lastIndexOf('\n');
+        if (lastNewline < 0) {
+            if (file.size - tracked.offset > MAX_LOG_LINE_BYTES) {
+                this.warnOnce(
+                    `line:${file.path}`,
+                    `[omp-opsx-addon] concurrency: dropping unterminated log line > ${MAX_LOG_LINE_BYTES}B in ${file.path}`,
+                );
+                tracked.offset = file.size;
+            }
+            return [];
+        }
+        const consumed = text.slice(0, lastNewline + 1);
+        tracked.offset += Buffer.byteLength(consumed, 'utf8');
+        return consumed.split('\n').slice(0, -1);
+    }
+
+    private warnOnce(key: string, message: string): void {
+        if (this.warned.has(key)) return;
+        this.warned.add(key);
+        this.warn(message);
+    }
+}
+
+function describe(err: unknown): string {
+    return err instanceof Error ? err.message : String(err);
+}
+
+/** Cheap epoch-ms extraction for buffer retention (`fallback` when unusable). */
+function lineTimestamp(raw: string, fallback: number): number {
+    try {
+        const parsed: unknown = JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            const ts = (parsed as Record<string, unknown>).timestamp;
+            if (typeof ts === 'number' && Number.isFinite(ts)) return ts;
+            if (typeof ts === 'string') {
+                const ms = Date.parse(ts);
+                if (Number.isFinite(ms)) return ms;
+            }
+        }
+    } catch {
+        // not JSON — retention falls back to the tick clock
+    }
+    return fallback;
+}
+
+// ── ① explicit failure classification (task 3.4) ────────────────────────────
+
+/** Classes of signal ①: an explicit provider-level failure. */
+export type ExplicitFailureKind = 'rate-limit' | 'timeout';
+
+const TIMEOUT_OR_5XX_RE = /\btimed?\s*out\b|\btimeout\b|\bETIMEDOUT\b|\bECONNRESET\b|\bhttp[^\d]{0,3}5\d\d\b|\b5\d\d\b/;
+
+/**
+ * Classify an error/response text as signal ①. `rate-limit` reuses the existing
+ * 429 diagnosis (`hasRateLimitError`); 5xx / timeouts fold into `timeout`.
+ * Returns `null` for anything that is not a provider-level failure.
+ */
+export function classifyExplicitFailure(text: string): ExplicitFailureKind | null {
+    if (hasRateLimitError(text)) return 'rate-limit';
+    if (TIMEOUT_OR_5XX_RE.test(text)) return 'timeout';
+    return null;
+}
+
+interface FailureCounts {
+    rateLimit: number;
+    timeout: number;
+}
+
+function emptyCounts(): FailureCounts {
+    return { rateLimit: 0, timeout: 0 };
+}
+
+// ── Control loop ────────────────────────────────────────────────────────────
+
+/**
+ * Durable per-provider state for a starting loop. A missing file is the normal
+ * first-run path (silent); an unreadable one degrades to `{}` plus a warn, i.e.
+ * to the shared config value — never to「无限制」.
+ */
+function loadPersistedState(statePath: string, warn: ConcurrencyWarn): ConcurrencyStateFile {
+    try {
+        return loadConcurrencyState({ statePath, warn });
+    } catch (err) {
+        warn(
+            `[omp-opsx-addon] concurrency: state file ${statePath} read failed (${describe(err)}); falling back to the shared config value`,
+        );
+        return {};
+    }
+}
+
+export interface ConcurrencyControlOptions {
+    /** Config root `config.yml` the writer reads/merges/writes. */
+    configPath: string;
+    /** Managed providers (already resolved: `concurrency_providers` ∪ limits keys). */
+    managedProviders: readonly string[];
+    /** Live tuner knobs; read on every tick so `eval_interval` changes take effect. */
+    tuner: TunerOptions;
+    /** Injected clock (epoch ms). */
+    now: () => number;
+    /** Filesystem seam for the log reader. */
+    fs: ConcurrencyFsPort;
+    /** Lease owner id (`pid` + start time); used for the lease and the summary. */
+    owner: string;
+    /** Agent dir; log dir / DB path are derived from it when not given. */
+    agentDir?: string;
+    /** Explicit log directory (overrides the derived one). */
+    logDir?: string;
+    /** `model_perf` source. `null` disables the source; omitted → sqlite port. */
+    modelPerf?: ModelPerfPort | null;
+    /** `agent.db` path when the sqlite port is derived (default `<agentDir>/agent.db`). */
+    dbPath?: string;
+    /** Cross-process ① aggregation channel; `null`/omitted disables it (warn + local only). */
+    redis?: ConcurrencyRedisPort | null;
+    /** Settings hot-apply seam; omitted → file write only. */
+    settings?: SettingsPort | null;
+    /** Per-provider ceiling overrides (`concurrency_ceiling_by_provider`). */
+    ceilingByProvider?: Record<string, number>;
+    /** Warn sink. */
+    warn?: ConcurrencyWarn;
+    /** Lease TTL (`concurrency_lease_ttl_ms`). */
+    leaseTtlMs?: number;
+    /** Minimum spacing between two successful writes (`concurrency_write_min_interval_ms`). */
+    writeMinIntervalMs?: number;
+    /** File-lease path (default `<configRoot>/opsx-concurrency-tuner.lock`). */
+    lockPath?: string;
+    /** Writer lock path (default `<configPath>.lock`, per the existing protocol). */
+    writeLockPath?: string;
+    /** Newest log files read per tick. */
+    maxLogFiles?: number;
+    /** Lease factory seam (default: the writer's `createLease`). */
+    leaseFactory?: ConcurrencyLeaseFactory;
+}
+
+export interface ProviderTickView {
+    provider: string;
+    limit: number;
+    badKind: BadEventKind | null;
+    decreased: boolean;
+    increased: boolean;
+    queueSuppressed: boolean;
+    cooldownActive: boolean;
+    /** Signal ① count for this window (own + aggregated). */
+    rateLimitCount: number;
+    timeoutCount: number;
+    queueWaitP50Ms: number | null;
+    queueWaitP90Ms: number | null;
+    /** Median generation duration of this window's samples (`null` = no samples). */
+    latencyMedianMs: number | null;
+    /**
+     * The throughput baseline *after* this window (`null` = no usable window yet).
+     * Only a healthy, non-queue-masked window may move it (same verdict as the
+     * latency baseline); exposed so that rule is observable end-to-end.
+     */
+    tokensPerMsEwma: number | null;
+    written: boolean;
+}
+
+export interface ConcurrencyTickResult {
+    /** `false` when the absolute-time gate skipped this tick. */
+    evaluated: boolean;
+    providers: Record<string, ProviderTickView>;
+}
+
+/**
+ * Signal collector + control loop.
+ *
+ * {@link onTick} is the only scheduled entry point and it is driven by the
+ * host's existing render tick: the first call arms the absolute-time gate, and
+ * every later call evaluates at most once per `concurrency_eval_interval_ms`.
+ * The loop calls the pure {@link evaluateWindow} state machine and the writer's
+ * config/lease API; it owns no timer and no IO other than the injected ports.
+ */
+export class ConcurrencyController {
+    private readonly fs: ConcurrencyFsPort;
+    /** Config-root `opsx-concurrency-state.json` (design D7). */
+    private readonly statePath: string;
+    private readonly tuner: TunerOptions;
+    private readonly now: () => number;
+    private readonly warn: ConcurrencyWarn;
+    private readonly logSource: IncrementalLogSource;
+    private readonly modelPerf: ModelPerfPort | null;
+    private readonly redis: ConcurrencyRedisPort | null;
+    private readonly settings: SettingsPort | null;
+    private readonly leaseFactory: ConcurrencyLeaseFactory;
+    private readonly leaseTtlMs: number;
+    private readonly writeMinIntervalMs: number;
+    private readonly lockPath: string;
+    private readonly writeLockPath: string | undefined;
+    private readonly redisPrefix: string;
+
+    /** Managed providers, canonicalized, first-seen order preserved. */
+    readonly providers: readonly string[];
+    readonly owner: string;
+    readonly configPath: string;
+
+    private readonly states = new Map<string, ProviderConcurrencyState>();
+    /**
+     * Body handed to the last persist step. `toStateFile` uses it to keep an
+     * unchanged entry's `updatedAt`, so a no-op window serializes byte-identical
+     * to the file on disk and `saveConcurrencyState` skips the write (P2-2).
+     */
+    private lastStateFile: ConcurrencyStateFile | null = null;
+    private readonly baselines = new Map<string, PerfBaseline>();
+    private readonly lastWriteAt = new Map<string, number>();
+    private readonly lastWindowRateLimit = new Map<string, number>();
+    private readonly lastWindowTimeout = new Map<string, number>();
+    private readonly ceilingByProvider: Record<string, number>;
+
+    private localEvents = new Map<string, FailureCounts>();
+    private logBuffer: Array<{ at: number; raw: string }> = [];
+    private queueSamples: QueueWaitSample[] = [];
+    private previousPerfRows: ModelPerfRow[] = [];
+    private perfSeeded = false;
+    private lease: ConcurrencyLease | null = null;
+    private wasLeaseHolder = false;
+    private lastEvalAt: number | null = null;
+    private selfChecked = false;
+    private logSourceAvailable = true;
+    private aggregationAvailable = true;
+
+    constructor(options: ConcurrencyControlOptions) {
+        this.configPath = options.configPath;
+        this.owner = options.owner;
+        this.fs = options.fs;
+        this.tuner = options.tuner;
+        this.now = options.now;
+        this.warn = options.warn ?? (() => {});
+        this.ceilingByProvider = options.ceilingByProvider ?? {};
+        this.leaseTtlMs = options.leaseTtlMs ?? TUNER_DEFAULTS.evalIntervalMs * 2;
+        const agentDir = options.agentDir ?? null;
+        this.lockPath = options.lockPath ?? join(dirname(resolvePath(options.configPath)), LEASE_LOCK_FILENAME);
+        this.writeLockPath = options.writeLockPath;
+        this.redisPrefix = `${RATE_LIMIT_REDIS_PREFIX}:${configRootHash(options.configPath)}`;
+        this.leaseFactory = options.leaseFactory ?? defaultLeaseFactory;
+        this.writeMinIntervalMs = options.writeMinIntervalMs ?? DEFAULT_WRITE_MIN_INTERVAL_MS;
+        this.modelPerf = options.modelPerf === undefined
+            ? createSqliteModelPerfPort(options.dbPath ?? deriveDbPath(agentDir))
+            : options.modelPerf;
+        this.redis = options.redis ?? null;
+        this.settings = options.settings ?? null;
+        this.logSource = new IncrementalLogSource(this.fs, options.logDir ?? deriveLogDir(agentDir), {
+            maxFiles: options.maxLogFiles,
+            warn: this.warn,
+        });
+
+        const providers: string[] = [];
+        const seen = new Set<string>();
+        for (const id of options.managedProviders) {
+            const canonical = canonicalizeProvider(id);
+            if (!canonical || seen.has(canonical)) continue;
+            seen.add(canonical);
+            providers.push(canonical);
+        }
+        this.providers = providers;
+
+        // Seed from the config root before the first tick: the persisted learned
+        // limit wins, then the shared config value, then `initial` (all clamped).
+        // Doing it here — not lazily inside `evaluate` — keeps `stateFor` and
+        // `summaryLines` truthful from construction on (design D7).
+        this.statePath = join(dirname(resolvePath(options.configPath)), STATE_FILE_NAME);
+        this.seedStates(loadPersistedState(this.statePath, this.warn));
+    }
+
+    /**
+     * Advance the loop from the host's existing render tick. Absolute-time
+     * gated off the last evaluation: the first call arms the gate without
+     * evaluating (a zero-length window must not count as clean); later calls
+     * evaluate at most once per `tuner.evalIntervalMs`, so a changed interval
+     * takes effect on the next tick.
+     */
+    async onTick(): Promise<ConcurrencyTickResult> {
+        const now = this.now();
+        if (!this.selfChecked) {
+            this.selfChecked = true;
+            this.runLogSelfCheck();
+        }
+        const interval = Number.isFinite(this.tuner.evalIntervalMs) && this.tuner.evalIntervalMs > 0
+            ? this.tuner.evalIntervalMs
+            : TUNER_DEFAULTS.evalIntervalMs;
+        if (this.lastEvalAt === null) {
+            // Arm the gate and snapshot the log tail positions: the first
+            // window starts here, so its log bytes are read, not skipped.
+            this.lastEvalAt = now;
+            this.logSource.readNewLines();
+            return { evaluated: false, providers: {} };
+        }
+        const elapsed = now - this.lastEvalAt;
+        if (elapsed < interval) return { evaluated: false, providers: {} };
+        this.lastEvalAt = now;
+        const result = await this.evaluate(now, elapsed);
+        // Fire-and-forget persistence (task 5.1). It sits on the evaluated
+        // branch, so a busy render tick cannot rewrite the state file every
+        // second, and it is never awaited: the tick MUST NOT block on the disk.
+        // Writer-gated for two reasons: a non-writer's `L` is only a local
+        // mirror of the shared gate (persisting it would let a restart resume a
+        // stale prediction and have two processes fight over one file), and a
+        // read-only-degraded loop MUST NOT write anything at all
+        // (spec「租约机制整体不可用时只读降级」).
+        if (this.isWriter()) {
+            const state = toStateFile(this.states, now, this.lastStateFile);
+            this.lastStateFile = state;
+            void saveConcurrencyState({
+                statePath: this.statePath,
+                state,
+                warn: this.warn,
+            });
+        }
+        return result;
+    }
+
+    /** Record an explicit provider-level failure observed in-process (task 3.4). */
+    noteExplicitFailure(provider: string, text: string): boolean {
+        const kind = classifyExplicitFailure(text);
+        if (kind === null) return false;
+        const canonical = canonicalizeProvider(provider);
+        if (!canonical) return false;
+        const counts = this.localEvents.get(canonical) ?? emptyCounts();
+        if (kind === 'rate-limit') counts.rateLimit += 1;
+        else counts.timeout += 1;
+        this.localEvents.set(canonical, counts);
+        return true;
+    }
+
+    /** Whether the debug-level in-flight log signal (②) passed the runtime self-check. */
+    logSignalAvailable(): boolean {
+        return this.logSourceAvailable;
+    }
+
+    /** Whether cross-process ① aggregation through Redis is usable. */
+    aggregationUsable(): boolean {
+        return this.aggregationAvailable && this.redis !== null;
+    }
+
+    /** Current lease mode (`null` before the first evaluation). */
+    leaseMode(): LeaseMode | null {
+        return this.lease?.mode ?? null;
+    }
+
+    /** Whether this process may write to the shared config right now. */
+    private isWriter(): boolean {
+        return this.lease?.held === true && this.lease.mode !== 'readonly';
+    }
+
+    /**
+     * Lease holder as last observed: this process while it holds the lease, the
+     * peer's owner id when a peer holds it, `null` when nobody does. Lets a
+     * non-writer's summary name the holder instead of only denying being one.
+     */
+    leaseOwner(): string | null {
+        return this.lease?.held === true ? this.owner : this.lease?.holderId ?? null;
+    }
+
+    /** Current state of a provider (test/inspection seam). */
+    stateFor(provider: string): ProviderConcurrencyState | null {
+        return this.states.get(canonicalizeProvider(provider)) ?? null;
+    }
+
+    /** Summary lines for the `/pick-model` section (task 2.7 format). */
+    summaryLines(): string[] {
+        const now = this.now();
+        const views = this.providers.map((provider) => {
+            const state = this.states.get(provider) ?? this.stateSeed(provider, null);
+            const { p50, p90 } = queueWaitPercentiles(
+                this.queueSamples.filter((s) => s.provider === provider),
+                now,
+                this.tuner.queueWaitWindowMs,
+            );
+            return {
+                provider,
+                limit: state.limit,
+                floor: state.floor,
+                ceiling: state.ceiling,
+                rateLimitCount: this.lastWindowRateLimit.get(provider) ?? 0,
+                timeoutCount: this.lastWindowTimeout.get(provider) ?? 0,
+                queueWaitP50Ms: p50,
+                queueWaitP90Ms: p90,
+                lastWriteAt: this.lastWriteAt.get(provider) ?? null,
+            };
+        });
+        const lines: string[] = [];
+        if (!this.logSourceAvailable) {
+            lines.push('并发控制降级: 日志 debug 信号不可用（未探测到 blocked/wait completed 行），排队等待护栏已失效');
+        }
+        if (!this.aggregationAvailable || this.redis === null) {
+            lines.push('并发控制降级: Redis 汇聚不可用，限流信号仅本进程可见（以信号②③补偿）');
+        }
+        lines.push(...formatConcurrencySummary({
+            providers: views,
+            leaseOwner: this.leaseOwner(),
+            selfId: this.owner,
+        }));
+        return lines;
+    }
+
+    /**
+     * Release the lease (tuner stop / plugin unload) and run the shutdown
+     * fail-safe. Never deletes config keys and never writes a managed provider
+     * back to unlimited — the last finite value stays in the shared config.
+     */
+    async shutdown(): Promise<void> {
+        const lease = this.lease;
+        this.lease = null;
+        this.wasLeaseHolder = false;
+        if (lease) {
+            try {
+                await lease.release();
+            } catch (err) {
+                this.warn(`[omp-opsx-addon] concurrency: lease release failed: ${describe(err)}`);
+            }
+        }
+        await stopFailSafe({ statePath: this.statePath, warn: this.warn });
+    }
+
+    // ── evaluation ──────────────────────────────────────────────────────────
+
+    /**
+     * One evaluation window. `elapsedMs` is the observed gap since the previous
+     * evaluation: `concurrency_up_ms` measures clean time against it, while the
+     * gate in {@link onTick} owns the cadence.
+     */
+    private async evaluate(now: number, elapsedMs: number): Promise<ConcurrencyTickResult> {
+        const result: ConcurrencyTickResult = { evaluated: true, providers: {} };
+        const sharedMap = this.readSharedLimits();
+
+        await this.ensureLease(now);
+        const isWriter = this.isWriter();
+
+        if (isWriter && !this.wasLeaseHolder) {
+            this.alignToSharedValues(sharedMap);
+        }
+        this.wasLeaseHolder = isWriter;
+
+        this.collectLogSignals(now);
+        const perfWindows = this.collectPerfWindows();
+        const failures = await this.collectFailures(isWriter);
+
+        for (const provider of this.providers) {
+            const state = this.states.get(provider) ?? this.seedState(provider, sharedMap[provider] ?? null, null);
+            this.states.set(provider, state);
+            const perf = perfWindows.get(provider) ?? null;
+            const baseline = this.baselines.get(provider) ?? null;
+            const failure = failures.get(provider) ?? emptyCounts();
+            const genSamplesMs = perf ? genSamplesFromPerfWindow(perf, this.tuner.minSamples) : [];
+            // Signal ② is derived once per provider and then handed in explicitly:
+            // the evaluator's mask/guardrail and this window's reported p50/p90 are
+            // the same number, not two derivations of the same samples.
+            const queueWait = this.queueSamples.filter((s) => s.provider === provider);
+            const { p50, p90 } = queueWaitPercentiles(queueWait, now, this.tuner.queueWaitWindowMs);
+            const signals: WindowSignals = {
+                // R1 evidence: the window really carried generation samples (the
+                // `model_perf` delta is the only source — no synthetic filler), so
+                // an idle provider freezes instead of climbing.
+                observed: genSamplesMs.length > 0,
+                rateLimitCount: failure.rateLimit + failure.timeout,
+                genSamplesMs,
+                tokensPerMs: perf ? perf.tokensPerMs : null,
+                tokensPerMsEwma: baseline?.tokensPerMs ?? null,
+                queueWait,
+                queueWaitP50Ms: p50,
+            };
+            const evaluation = evaluateWindow(state, signals, now, this.tuner, elapsedMs);
+            // Decay (task 5.3): a provider that has gone
+            // `concurrency_decay_after_ms` without an observation moves one
+            // notch toward `initial` — and the move goes out through the very
+            // same gate/lease/writer path below, never a second write path.
+            const decay = applyDecayStep(evaluation.state, {
+                now,
+                decayAfterMs: this.tuner.decayAfterMs,
+                initial: evaluation.state.initial,
+                floor: evaluation.state.floor,
+            });
+            const next = decay.state;
+            this.states.set(provider, next);
+            // Baseline hygiene, on the very verdict the evaluator reached: a
+            // queue-masked or bad window MUST NOT move the throughput baseline
+            // either — else the load-driven dip becomes the new normal and blinds
+            // the fallback that is supposed to catch it.
+            if (perf && evaluation.baselineEligible) {
+                this.baselines.set(provider, updatePerfBaseline(baseline, perf, this.tuner));
+            }
+            this.lastWindowRateLimit.set(provider, failure.rateLimit);
+            this.lastWindowTimeout.set(provider, failure.timeout);
+
+            const view: ProviderTickView = {
+                provider,
+                limit: next.limit,
+                badKind: evaluation.badKind,
+                decreased: evaluation.decreased,
+                increased: evaluation.increased,
+                queueSuppressed: evaluation.queueSuppressed,
+                cooldownActive: evaluation.cooldownActive,
+                rateLimitCount: failure.rateLimit,
+                timeoutCount: failure.timeout,
+                queueWaitP50Ms: p50,
+                queueWaitP90Ms: p90,
+                latencyMedianMs: evaluation.latencyMedianMs,
+                tokensPerMsEwma: this.baselines.get(provider)?.tokensPerMs ?? null,
+                written: false,
+            };
+            // Write candidates: a move this window (up / down / decay), or a
+            // divergence from the shared value that no window can repair on its
+            // own — the first-window catch-up and a degenerate range
+            // (`floor == ceiling`, e.g. a per-provider ceiling override below the
+            // static value, where neither increase nor decrease can ever fire and
+            // the host gate would keep serving the stale value we display).
+            // `persistLimit` still applies the |Δ| >= 1 gate, the write interval
+            // and the lease — no second write path.
+            const shared = sharedMap[provider];
+            const divergedFromShared = typeof shared === 'number' && shared !== next.limit;
+            if ((evaluation.increased || evaluation.decreased || decay.moved || divergedFromShared) && isWriter) {
+                view.written = this.persistLimit(provider, next.limit, sharedMap, now);
+            }
+            result.providers[provider] = view;
+        }
+        return result;
+    }
+
+    private stateSeed(provider: string, sharedLimit: number | null): ProviderConcurrencyState {
+        return createProviderState({
+            sharedLimit,
+            start: this.tuner.start,
+            ceilingOverride: this.ceilingByProvider[provider] ?? null,
+            options: this.tuner,
+        });
+    }
+
+    /** Seed `states` for every managed provider from the durable file / shared config. */
+    private seedStates(persisted: ConcurrencyStateFile): void {
+        const shared = this.readSharedLimits();
+        for (const provider of this.providers) {
+            this.states.set(provider, this.seedState(provider, shared[provider] ?? null, persisted[provider] ?? null));
+        }
+    }
+
+    /**
+     * One provider's starting state (design D7). Without a durable entry this
+     * is just the seed value (`shared ?? concurrency_start`, clamped). With one,
+     * the learned limit and its trajectory resume:
+     *
+     * - `limit` — {@link restoreLimit} resolves persisted → shared → `initial`.
+     * - `initial` — the *persisted* decay target, not a re-derivation from the
+     *   current shared value: the controller writes `L` back into the shared
+     *   config, so re-deriving would make the learned limit its own decay target
+     *   and permanently disable decay after the first restart.
+     * - `lastObservationAt` — the persisted anchor, so decay resumes on the real
+     *   idle clock. A state that never observed anything anchors at the process
+     *   start: anchoring at 0 would make every window look「idle for an epoch」
+     *   and decay a freshly raised `L` straight back down.
+     */
+    private seedState(
+        provider: string,
+        sharedLimit: number | null,
+        persisted: PersistedProviderState | null,
+    ): ProviderConcurrencyState {
+        const seed = this.stateSeed(provider, sharedLimit);
+        if (!persisted) return { ...seed, lastObservationAt: this.now() };
+        return {
+            ...seed,
+            limit: restoreLimit(persisted, {
+                floor: seed.floor,
+                ceiling: seed.ceiling,
+                sharedValue: sharedLimit,
+                initial: seed.initial,
+            }),
+            initial: clampLimit(persisted.initial, seed.floor, seed.ceiling),
+            badStreak: persisted.badStreak,
+            cleanWindows: persisted.cleanStreak,
+            ewmaGenMs: persisted.ewmaGenMs ?? seed.ewmaGenMs,
+            lastObservationAt: persisted.lastObservationAt > 0 ? persisted.lastObservationAt : this.now(),
+        };
+    }
+
+    /**
+     * Re-seed every provider's `L` from the shared config value when this
+     * process first becomes the writer (spec: takeover must not fall back to a
+     * local `initial`/`concurrency_start`, and the alignment itself writes
+     * nothing).
+     */
+    private alignToSharedValues(sharedMap: Record<string, number>): void {
+        for (const provider of this.providers) {
+            const state = this.states.get(provider);
+            if (!state) continue;
+            state.limit = resolveTakeoverStart(sharedMap[provider] ?? null, {
+                floor: state.floor,
+                ceiling: state.ceiling,
+                start: state.initial,
+            });
+        }
+    }
+
+    private readSharedLimits(): Record<string, number> {
+        const map: Record<string, number> = {};
+        try {
+            for (const row of readManagedLimits(this.configPath, this.providers)) {
+                const canonical = canonicalizeProvider(row.provider);
+                if (canonical && typeof row.value === 'number' && Number.isFinite(row.value)) {
+                    map[canonical] = Math.trunc(row.value);
+                }
+            }
+        } catch (err) {
+            this.warn(`[omp-opsx-addon] concurrency: reading providers.maxInFlightRequests failed: ${describe(err)}`);
+        }
+        return map;
+    }
+
+    private async ensureLease(now: number): Promise<void> {
+        if (this.lease) {
+            if (this.lease.mode === 'readonly') return;
+            let renewed = false;
+            try {
+                renewed = await this.lease.renew();
+            } catch (err) {
+                this.warn(`[omp-opsx-addon] concurrency: lease renew failed: ${describe(err)}`);
+            }
+            this.lease.held = renewed;
+            if (!renewed) {
+                // Lost the lease: drop the handle so the next tick re-acquires it
+                // (renewing a lease someone else owns can never succeed).
+                const lost = this.lease;
+                this.lease = null;
+                try {
+                    await lost.release();
+                } catch (err) {
+                    this.warn(`[omp-opsx-addon] concurrency: lease release after loss failed: ${describe(err)}`);
+                }
+            }
+            return;
+        }
+        try {
+            this.lease = await this.leaseFactory({
+                redis: this.redis,
+                lockPath: this.lockPath,
+                owner: this.owner,
+                ttlMs: this.leaseTtlMs,
+                now: this.now,
+            });
+            if (this.lease.mode === 'readonly') {
+                this.warn('[omp-opsx-addon] concurrency: lease unavailable (Redis + file lease both failed); running read-only');
+            }
+        } catch (err) {
+            this.warn(`[omp-opsx-addon] concurrency: lease acquisition failed: ${describe(err)}`);
+            this.lease = { held: false, mode: 'readonly', holderId: null, renew: async () => false, release: async () => {} };
+        }
+    }
+
+    /**
+     * Signal ②: read the new bytes of every log file and re-pair the retained
+     * recent lines. Pairing is redone over the whole recent buffer because a
+     * `blocked` line and its `wait completed` line routinely land in different
+     * ticks; recomputing (instead of appending) also keeps them from being
+     * counted twice. Lines older than two guardrail windows are dropped.
+     */
+    private collectLogSignals(now: number): void {
+        let lines: string[];
+        try {
+            lines = this.logSource.readNewLines();
+        } catch (err) {
+            this.warn(`[omp-opsx-addon] concurrency: log collection failed: ${describe(err)}`);
+            return;
+        }
+        if (lines.length === 0 && this.logBuffer.length === 0) return;
+        for (const raw of lines) this.logBuffer.push({ at: lineTimestamp(raw, now), raw });
+        const cutoff = now - 2 * this.tuner.queueWaitWindowMs;
+        this.logBuffer = this.logBuffer.filter((entry) => entry.at >= cutoff);
+        if (this.logBuffer.length > MAX_BUFFERED_LOG_LINES) {
+            this.logBuffer = this.logBuffer.slice(-MAX_BUFFERED_LOG_LINES);
+        }
+        const parsed = parseInFlightLogLines(this.logBuffer.map((entry) => entry.raw));
+        this.queueSamples = parsed.samples.map((sample) => ({
+            ...sample,
+            provider: canonicalizeProvider(sample.provider),
+        }));
+    }
+
+    private collectPerfWindows(): Map<string, ProviderPerfWindow> {
+        const windows = new Map<string, ProviderPerfWindow>();
+        if (!this.modelPerf) return windows;
+        let rows: ModelPerfRow[];
+        try {
+            rows = this.modelPerf.readModelPerf();
+        } catch (err) {
+            this.warn(`[omp-opsx-addon] concurrency: model_perf read failed, skipping source: ${describe(err)}`);
+            return windows;
+        }
+        if (!this.perfSeeded) {
+            // The table holds cumulative counters: the first read is the window
+            // baseline, not a window's worth of history.
+            this.perfSeeded = true;
+            this.previousPerfRows = rows;
+            return windows;
+        }
+        for (const window of diffModelPerf(this.previousPerfRows, rows, this.tuner)) {
+            windows.set(canonicalizeProvider(window.provider), window);
+        }
+        this.previousPerfRows = rows;
+        return windows;
+    }
+
+    /**
+     * Signal ① for this window. Non-writers report their local counts into the
+     * per-provider Redis counters (atomically drained by the writer with
+     * `GETSET`), so a 429 observed only on a non-writer's LLM path still drives
+     * the shared down-scale. Redis unavailable → warn once and use local counts
+     * (spec: evaluation must continue on signals ②③).
+     */
+    private async collectFailures(isWriter: boolean): Promise<Map<string, FailureCounts>> {
+        const local = this.localEvents;
+        this.localEvents = new Map();
+        const source = new Map<string, FailureCounts>();
+        for (const [provider, counts] of local) source.set(provider, { ...counts });
+
+        if (this.redis === null) {
+            if (this.aggregationAvailable) {
+                this.aggregationAvailable = false;
+                this.warn('[omp-opsx-addon] concurrency: Redis aggregation unavailable, continuing on signals ②③');
+            }
+            return source;
+        }
+        try {
+            if (!isWriter) {
+                await this.reportLocalFailures(local);
+                return source;
+            }
+            const remote = await this.drainRemoteFailures();
+            for (const [provider, counts] of remote) {
+                const merged = source.get(provider) ?? emptyCounts();
+                merged.rateLimit += counts.rateLimit;
+                merged.timeout += counts.timeout;
+                source.set(provider, merged);
+            }
+            return source;
+        } catch (err) {
+            if (this.aggregationAvailable) {
+                this.aggregationAvailable = false;
+                this.warn(`[omp-opsx-addon] concurrency: Redis aggregation unavailable, continuing on signals ②③: ${describe(err)}`);
+            }
+            return source;
+        }
+    }
+
+    private async reportLocalFailures(local: Map<string, FailureCounts>): Promise<void> {
+        const commands: string[][] = [];
+        for (const [provider, counts] of local) {
+            if (counts.rateLimit > 0) {
+                commands.push(['INCRBY', this.failureKey(provider, 'rl'), String(counts.rateLimit)]);
+                commands.push(['EXPIRE', this.failureKey(provider, 'rl'), String(this.aggregationTtlSeconds())]);
+            }
+            if (counts.timeout > 0) {
+                commands.push(['INCRBY', this.failureKey(provider, 'to'), String(counts.timeout)]);
+                commands.push(['EXPIRE', this.failureKey(provider, 'to'), String(this.aggregationTtlSeconds())]);
+            }
+        }
+        if (commands.length === 0) return;
+        await this.redis!.pipeline(commands);
+    }
+
+    private async drainRemoteFailures(): Promise<Map<string, FailureCounts>> {
+        const commands: string[][] = [];
+        for (const provider of this.providers) {
+            for (const field of ['rl', 'to'] as const) {
+                commands.push(['GETSET', this.failureKey(provider, field), '0']);
+                commands.push(['EXPIRE', this.failureKey(provider, field), String(this.aggregationTtlSeconds())]);
+            }
+        }
+        if (commands.length === 0) return new Map();
+        const replies = await this.redis!.pipeline(commands);
+        const out = new Map<string, FailureCounts>();
+        let index = 0;
+        for (const provider of this.providers) {
+            const counts = { rateLimit: readCounter(replies[index]), timeout: readCounter(replies[index + 2]) };
+            index += 4;
+            if (counts.rateLimit > 0 || counts.timeout > 0) out.set(provider, counts);
+        }
+        return out;
+    }
+
+    private failureKey(provider: string, field: 'rl' | 'to'): string {
+        return `${this.redisPrefix}:${provider}:${field}`;
+    }
+
+    private aggregationTtlSeconds(): number {
+        const interval = Number.isFinite(this.tuner.evalIntervalMs) && this.tuner.evalIntervalMs > 0
+            ? this.tuner.evalIntervalMs
+            : TUNER_DEFAULTS.evalIntervalMs;
+        return Math.max(1, Math.ceil((interval * AGGREGATION_TTL_INTERVALS) / 1000));
+    }
+
+    private persistLimit(
+        provider: string,
+        limit: number,
+        sharedMap: Record<string, number>,
+        now: number,
+    ): boolean {
+        // Write gate (task 4.2): |Δ| >= 1 AND more than
+        // concurrency_write_min_interval_ms since this provider's last write.
+        const gate = shouldWriteLimit({
+            newValue: limit,
+            oldValue: sharedMap[provider] ?? null,
+            lastWriteAt: this.lastWriteAt.get(provider) ?? null,
+            now,
+            minIntervalMs: this.writeMinIntervalMs,
+        });
+        if (!gate.write) return false;
+
+        const merged = buildMergedMap(sharedMap, provider, limit);
+        let outcome: WriteManagedLimitResult;
+        try {
+            outcome = this.writeLockPath === undefined
+                ? writeManagedLimit({ configPath: this.configPath, provider, merged, now })
+                : writeManagedLimit({ configPath: this.configPath, provider, merged, lockPath: this.writeLockPath, now });
+        } catch (err) {
+            this.warn(`[omp-opsx-addon] concurrency: writing providers.maxInFlightRequests failed (keeping ${limit}): ${describe(err)}`);
+            return false;
+        }
+        if (!outcome.written) {
+            if (outcome.reason !== undefined && outcome.reason !== 'unchanged') {
+                this.warn(`[omp-opsx-addon] concurrency: ${provider} limit write skipped (${outcome.reason})`);
+            }
+            return false;
+        }
+        // Adopt the in-lock read: it is the freshest view of every provider, so
+        // the rest of this tick and the whole-key `settings.override` below never
+        // carry a snapshot taken before another process's write landed.
+        if (outcome.limits) {
+            for (const [id, value] of Object.entries(outcome.limits)) sharedMap[id] = value;
+        }
+        sharedMap[provider] = limit;
+        this.lastWriteAt.set(provider, now);
+        if (this.settings) {
+            try {
+                const applied = applyLimit({
+                    settings: this.settings,
+                    merged: outcome.limits ?? merged,
+                    provider,
+                    value: limit,
+                });
+                if (!applied.applied) {
+                    this.warn(`[omp-opsx-addon] concurrency: settings hot-apply skipped for ${provider} (${applied.reason ?? 'unknown'})`);
+                }
+            } catch (err) {
+                this.warn(`[omp-opsx-addon] concurrency: settings hot-apply failed for ${provider}: ${describe(err)}`);
+            }
+        }
+        return true;
+    }
+
+    private runLogSelfCheck(): void {
+        let available: boolean;
+        try {
+            available = this.logSource.probeDebugInFlightLines();
+        } catch (err) {
+            available = false;
+            this.warn(`[omp-opsx-addon] concurrency: log self-check failed: ${describe(err)}`);
+        }
+        this.logSourceAvailable = available;
+        if (!available) {
+            this.warn(
+                '[omp-opsx-addon] concurrency: signal ② (queue wait) unavailable — no level=debug '
+                + '"Provider in-flight limit blocked request" / "wait completed" lines in the host log; '
+                + 'queue-wait guardrail disabled (signals ①③④ still active)',
+            );
+        }
+    }
+}
+
+/** Map aggregated `model_perf` deltas onto the per-request sample list `evaluateWindow` expects. */
+export function genSamplesFromPerfWindow(window: ProviderPerfWindow, minSamples: number): number[] {
+    if (window.samples <= 0 || !Number.isFinite(window.genMsPerSample) || window.genMsPerSample <= 0) return [];
+    const capped = Math.min(window.samples, 64);
+    const count = window.samples >= minSamples ? Math.max(minSamples, capped) : window.samples;
+    return new Array<number>(count).fill(window.genMsPerSample);
+}
+
+function readCounter(reply: RedisReply | undefined): number {
+    if (typeof reply === 'number' && Number.isFinite(reply)) return Math.max(0, Math.trunc(reply));
+    if (typeof reply === 'string') {
+        const value = Number.parseInt(reply, 10);
+        return Number.isFinite(value) && value > 0 ? value : 0;
+    }
+    return 0;
+}
+
+/** Convenience factory mirroring the exported class. */
+export function createConcurrencyController(options: ConcurrencyControlOptions): ConcurrencyController {
+    return new ConcurrencyController(options);
+}