@genee/omp-opsx-addon 0.1.0

package/lib/usage-poller.worker.ts

@@ -0,0 +1,31 @@
+/**
+ * Concurrency-test worker PROCESS: several of these run simultaneously, each
+ * hammering `writeSessionUsage` for its own session id against the SAME
+ * REALTIME cache file. The poller's cross-process realtime file lock must
+ * serialize their read-modify-write cycles so no entry is clobbered (see the
+ * "file lock" describe in usage-poller.test.ts). Scoped to the realtime file
+ * lock only — the fetch path is not exercised here.
+ *
+ * Usage: bun usage-poller.worker.ts <realtimeCacheFile> <sessionId> <iters>
+ */
+import { _setRealtimeFileForTest, writeSessionUsage } from './usage-poller.js';
+
+const [, , cacheFile, sessionId, itersStr] = process.argv;
+const iters = Number(itersStr);
+if (!cacheFile || !sessionId || !Number.isFinite(iters)) {
+    console.error('usage: usage-poller.worker.ts <realtimeCacheFile> <sessionId> <iters>');
+    process.exit(2);
+}
+_setRealtimeFileForTest(cacheFile);
+// Mimic the recorder's contract: each write carries the session's FULL
+// accumulated state (cumulative totals + per-second map keyed by absolute
+// unix seconds), so the final disk entry must hold every second's key.
+const seconds: Record<string, number> = {};
+let total = 0;
+for (let i = 0; i < iters; i++) {
+    total += 1;
+    seconds[String(1_000 + i)] = 1;
+    writeSessionUsage(sessionId, {
+        deepseek: { total, input: total, output: 0, seconds: { ...seconds } },
+    });
+}

package/lib/usage-redis-client.ts

@@ -0,0 +1,594 @@
+/**
+ * 最小 RESP2 Redis 客户端（零运行时依赖）。
+ *
+ * 职责：
+ * 1. RESP2 编解码：命令编码 `*<n>\r\n$<len>\r\n<bytes>\r\n...`，回复解析支持
+ *    `+OK`/`-ERR`/`:int`/`$bulk`/`$-1`/`*array`（递归解析嵌套数组）
+ * 2. 单连接串行命令 + 简单 pipeline（一次连发、按发送顺序回读）
+ * 3. 连接超时（默认 300ms）与命令超时（默认 500ms）生效；超时/断连抛错不吞
+ * 4. transport 注入 seam（默认 `Bun.connect` 实现），测试可替换
+ *
+ * 设计（遵循 design.md D1/D5）：
+ * - 命令面固定 6 条（PING/HINCRBY/HSET/HGETALL/DEL/EXPIRE）+ pipeline，无连接池/集群/哨兵
+ * - TCP 半包处理：`Buffer` 累积 + 按 `$len` 精确切包（bulk 内容不扫描），递归解析嵌套
+ * - 单连接串行：命令经内部 promise 链排队，任意时刻至多一个在途批次
+ * - 超时/断连/`close()` 后连接对象失效（dead），后续调用立即抛错，由上层降级
+ */
+
+// ── 类型 ────────────────────────────────────────────────────────────────
+
+/**
+ * RESP2 回复的运行时形态：
+ * - 简单字符串（`+OK` → `'OK'`）与 bulk 字符串 → `string`
+ * - 整数（`:n`）→ `number`
+ * - nil（`$-1` / `*-1`）→ `null`
+ * - 数组（`*n`，含嵌套）→ `RedisReply[]`
+ */
+export type RedisReply = string | number | null | RedisReply[];
+
+/**
+ * Redis 协议/客户端错误。服务器返回 `-ERR` 回复时抛此类型。
+ */
+export class RedisError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RedisError';
+  }
+}
+
+/** 一个已建立的 TCP 连接的抽象（transport 注入 seam 的最小面）。 */
+export interface RedisSocket {
+  /** 写入原始字节（RESP 编码后的命令）。 */
+  write(data: Uint8Array): void;
+  /** 注册数据回调：连接上到达的原始字节流。 */
+  onData(cb: (data: Uint8Array) => void): void;
+  /** 注册关闭回调：连接被对端关闭/断开。 */
+  onClose(cb: () => void): void;
+  /** 注册错误回调：连接级错误（如 ECONNRESET）。 */
+  onError(cb: (err: unknown) => void): void;
+  /** 关闭连接（客户端主动）。 */
+  end(): void;
+}
+
+/** 连接工厂签名，测试 seam 可替换。默认实现为 `Bun.connect`。 */
+export interface RedisTransport {
+  connect(opts: {
+    host: string;
+    port: number;
+    /** 连接超时 ms（默认 300，`redis_connect_timeout_ms` 语义）。 */
+    timeoutMs: number;
+  }): Promise<RedisSocket>;
+}
+
+/** `RedisClient` 构造参数。 */
+export interface RedisClientOptions {
+  /** Redis host，默认 `127.0.0.1`。 */
+  host?: string;
+  /** Redis port，默认 `6379`。 */
+  port?: number;
+  /** 连接超时 ms，默认 300。 */
+  connectTimeoutMs?: number;
+  /** 单命令往返超时 ms，默认 500。 */
+  commandTimeoutMs?: number;
+  /** 连接工厂（默认 `Bun.connect` 实现）。 */
+  transport?: RedisTransport;
+}
+
+// ── RESP2 命令编码 ──────────────────────────────────────────────────────
+
+/**
+ * 将命令参数编码为 RESP2 数组帧：`*<n>\r\n$<len>\r\n<bytes>\r\n...`。
+ * 每个参数按 UTF-8 字节长度编码。
+ */
+export function encodeCommand(args: string[]): Buffer {
+  const parts: Buffer[] = [Buffer.from(`*${args.length}\r\n`)];
+  for (const arg of args) {
+    const bytes = Buffer.from(arg, 'utf8');
+    parts.push(Buffer.from(`$${bytes.length}\r\n`), bytes, Buffer.from('\r\n'));
+  }
+  return Buffer.concat(parts);
+}
+
+// ── RESP2 回复解析（Buffer 累积 + 按 $len 切包）────────────────────────
+
+/**
+ * RESP2 回复解析器。
+ *
+ * 结构：累积缓冲 + 游标递归下降。
+ * - `push(chunk)` 把 TCP 到达的字节追加进累积缓冲（已消费前缀在下次 push 时回收）
+ * - `next()` 从游标处尝试解析一条完整回复；数据不足返回 `undefined`（半包待重组），
+ *   完整则提交游标并返回该回复；`-ERR` 回复抛 `RedisError`
+ * - bulk 按 `$len` 精确切包（内容字节不扫描 CRLF），数组递归解析嵌套回复
+ * - 仅当整条回复（含嵌套）解析成功才提交偏移，残缺帧不消费任何字节
+ */
+export class ReplyParser {
+  private buf: Buffer = Buffer.alloc(0);
+  private pos = 0;
+
+  /** 追加一段 TCP 数据。 */
+  push(chunk: Uint8Array): void {
+    const data = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    if (this.pos > 0) {
+      this.buf = this.buf.subarray(this.pos);
+      this.pos = 0;
+    }
+    this.buf = this.buf.length === 0 ? data : Buffer.concat([this.buf, data]);
+  }
+
+  /** 缓冲内是否还有未消费字节。 */
+  hasMore(): boolean {
+    return this.pos < this.buf.length;
+  }
+
+  /**
+   * 解析下一条完整回复。
+   * 返回 `undefined` 表示当前缓冲不足以构成一条完整回复（等更多数据）。
+   * 服务器返回 `-ERR` 时抛 `RedisError`。
+   */
+  next(): RedisReply | undefined {
+    if (this.pos >= this.buf.length) return undefined;
+    const parsed = this.parseAt(this.buf, this.pos);
+    if (parsed === null) return undefined;
+    this.pos = parsed.end;
+    if (parsed.reply instanceof RedisError) throw parsed.reply;
+    return parsed.reply;
+  }
+
+  /**
+   * 从 `start` 偏移处解析一条回复；数据不足返回 `null`（不消费任何字节）。
+   * 遇到 `-ERR` 返回 `RedisError` 实例（帧已消费，由调用方在提交游标后抛）。
+   */
+  private parseAt(
+    buf: Buffer,
+    start: number,
+  ): { reply: RedisReply | RedisError; end: number } | null {
+    if (start >= buf.length) return null;
+    const type = buf[start];
+    const lineStart = start + 1;
+    const lineEnd = buf.indexOf('\r\n', lineStart);
+    if (lineEnd === -1) return null; // 行未到齐（半包）
+    const line = buf.toString('utf8', lineStart, lineEnd);
+    const afterLine = lineEnd + 2;
+
+    switch (type) {
+      case 0x2b /* + */:
+        return { reply: line, end: afterLine };
+      case 0x2d /* - */:
+        return { reply: new RedisError(line), end: afterLine };
+      case 0x3a /* : */: {
+        const n = Number.parseInt(line, 10);
+        if (!Number.isFinite(n)) throw new RedisError(`Malformed integer reply: ${line}`);
+        return { reply: n, end: afterLine };
+      }
+      case 0x24 /* $ */: {
+        const len = Number.parseInt(line, 10);
+        if (!Number.isFinite(len)) throw new RedisError(`Malformed bulk length: ${line}`);
+        if (len === -1) return { reply: null, end: afterLine };
+        if (len < -1) throw new RedisError(`Invalid bulk length: ${len}`);
+        if (buf.length < afterLine + len + 2) return null; // 内容未到齐（半包）
+        return {
+          reply: buf.toString('utf8', afterLine, afterLine + len),
+          end: afterLine + len + 2,
+        };
+      }
+      case 0x2a /* * */: {
+        const n = Number.parseInt(line, 10);
+        if (!Number.isFinite(n)) throw new RedisError(`Malformed array length: ${line}`);
+        if (n === -1) return { reply: null, end: afterLine };
+        if (n < -1) throw new RedisError(`Invalid array length: ${n}`);
+        const items: RedisReply[] = [];
+        let p = afterLine;
+        for (let i = 0; i < n; i++) {
+          const item = this.parseAt(buf, p);
+          if (item === null) return null; // 嵌套回复未到齐
+          if (item.reply instanceof RedisError) return item; // 数组内错误回复中止整帧
+          items.push(item.reply);
+          p = item.end;
+        }
+        return { reply: items, end: p };
+      }
+      default:
+        throw new RedisError(`Unknown RESP type byte: 0x${type.toString(16)}`);
+    }
+  }
+}
+
+// ── 默认 transport（Bun.connect 实现）──────────────────────────────────
+
+/**
+ * Bun 运行时最小面（仓库未安装 bun-types，仅声明本模块用到的 `Bun.connect`）。
+ * 其余 Bun API 不在本模块使用。
+ */
+declare global {
+  var Bun: {
+    connect(opts: {
+      hostname: string;
+      port: number;
+      socket: {
+        data?(socket: unknown, data: Uint8Array): void;
+        open?(socket: unknown): void;
+        close?(socket: unknown, hadError: boolean): void;
+        end?(socket: unknown): void;
+        error?(socket: unknown, err: unknown): void;
+      };
+    }): Promise<{
+      write(data: Uint8Array | string): number;
+      flush(): void;
+      end(): void;
+    }>;
+  };
+}
+
+/** `Bun.connect` 默认 transport（带连接超时；超时后尽力回收迟到建立的连接）。 */
+const defaultRedisTransport: RedisTransport = {
+  connect(opts): Promise<RedisSocket> {
+    return new Promise<RedisSocket>((resolve, reject) => {
+      let settled = false;
+      let dataCb: ((data: Uint8Array) => void) | null = null;
+      let closeCb: (() => void) | null = null;
+      let errorCb: ((err: unknown) => void) | null = null;
+
+      const socketPromise = Bun.connect({
+        hostname: opts.host,
+        port: opts.port,
+        socket: {
+          data(_s, data) {
+            dataCb?.(data);
+          },
+          close(_s) {
+            closeCb?.();
+          },
+          // 对端半关闭（FIN）同样视为连接结束，避免悬挂等待
+          end(_s) {
+            closeCb?.();
+          },
+          error(_s, err) {
+            errorCb?.(err);
+          },
+        },
+      });
+
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        // 尽力回收超时后迟到建立的连接
+        socketPromise.then(
+          (s) => {
+            try {
+              s.end();
+            } catch {
+              /* ignore */
+            }
+          },
+          () => {
+            /* ignore */
+          },
+        );
+        reject(new Error(`Redis connect timeout after ${opts.timeoutMs}ms`));
+      }, opts.timeoutMs);
+
+      socketPromise.then(
+        (socket) => {
+          if (settled) return; // 连接超时已判定，socket 由定时器回收
+          settled = true;
+          clearTimeout(timer);
+          resolve({
+            write(data) {
+              socket.write(data);
+              socket.flush();
+            },
+            onData(cb) {
+              dataCb = cb;
+            },
+            onClose(cb) {
+              closeCb = cb;
+            },
+            onError(cb) {
+              errorCb = cb;
+            },
+            end() {
+              socket.end();
+            },
+          });
+        },
+        (err) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          reject(err instanceof Error ? err : new Error(String(err)));
+        },
+      );
+    });
+  },
+};
+
+// ── RedisClient ─────────────────────────────────────────────────────────
+
+const DEFAULT_CONNECT_TIMEOUT_MS = 300;
+const DEFAULT_COMMAND_TIMEOUT_MS = 500;
+
+interface PendingRequest {
+  /** 待读回复数（单命令 1；pipeline 为命令数）。 */
+  count: number;
+  replies: RedisReply[];
+  resolve: (replies: RedisReply[]) => void;
+  reject: (err: Error) => void;
+  timer: NodeJS.Timeout | null;
+}
+
+/**
+ * 最小 RESP2 Redis 客户端（单连接串行 + 简单 pipeline）。
+ *
+ * 生命周期：
+ * - 懒连接：首次命令触发 `transport.connect`（带连接超时）
+ * - 命令经内部 promise 链串行排队，任意时刻至多一个在途批次（含 pipeline）
+ * - 超时/断连/`close()` 后连接对象失效（dead），后续调用立即抛错
+ *
+ * 命令方法：`ping` / `hincrby` / `hset` / `hgetall` / `del` / `expire` + `pipeline`。
+ */
+export class RedisClient {
+  private readonly host: string;
+  private readonly port: number;
+  private readonly connectTimeoutMs: number;
+  private readonly commandTimeoutMs: number;
+  private readonly transport: RedisTransport;
+
+  private socket: RedisSocket | null = null;
+  private dead = false;
+  private readonly parser = new ReplyParser();
+  private pending: PendingRequest | null = null;
+  private chain: Promise<void> = Promise.resolve();
+
+  constructor(opts: RedisClientOptions = {}) {
+    this.host = opts.host ?? '127.0.0.1';
+    this.port = opts.port ?? 6379;
+    this.connectTimeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    this.commandTimeoutMs = opts.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+    this.transport = opts.transport ?? defaultRedisTransport;
+  }
+
+  // ── 命令面 ────────────────────────────────────────────────────────────
+
+  /** `PING` → `+PONG`；非 PONG 回复抛错。 */
+  async ping(): Promise<'PONG'> {
+    const reply = await this.execute(['PING']);
+    if (reply !== 'PONG') {
+      throw new RedisError(`PING returned unexpected reply: ${JSON.stringify(reply)}`);
+    }
+    return 'PONG';
+  }
+
+  /** `HINCRBY key field delta` → 累加后的整数值。 */
+  async hincrby(key: string, field: string, delta: number): Promise<number> {
+    const reply = await this.execute(['HINCRBY', key, field, String(delta)]);
+    return assertInteger(reply, 'HINCRBY');
+  }
+
+  /** `HSET key field value` → 本次新增的 field 数（覆盖已有 field 不计）。 */
+  async hset(key: string, field: string, value: string | number): Promise<number> {
+    const reply = await this.execute(['HSET', key, field, String(value)]);
+    return assertInteger(reply, 'HSET');
+  }
+
+  /**
+   * `HGETALL key` → 全部 field/value。
+   * 空 hash 返回 `{}`；key 不存在（服务器回 nil/空数组）返回 `null`。
+   */
+  async hgetall(key: string): Promise<Record<string, string> | null> {
+    const reply = await this.execute(['HGETALL', key]);
+    if (reply === null) return null;
+    if (!Array.isArray(reply)) {
+      throw new RedisError(`HGETALL returned non-array reply: ${JSON.stringify(reply)}`);
+    }
+    const out: Record<string, string> = {};
+    for (let i = 0; i + 1 < reply.length; i += 2) {
+      const field = reply[i];
+      const value = reply[i + 1];
+      if (typeof field === 'string' && typeof value === 'string') {
+        out[field] = value;
+      }
+    }
+    return out;
+  }
+
+  /** `DEL key` → 被删除的 key 数。 */
+  async del(key: string): Promise<number> {
+    const reply = await this.execute(['DEL', key]);
+    return assertInteger(reply, 'DEL');
+  }
+
+  /** `EXPIRE key ttlSec` → 1 已设 TTL / 0 未设置；兼容旧版 `+OK`（按 1 处理）。 */
+  async expire(key: string, ttlSec: number): Promise<number> {
+    const reply = await this.execute(['EXPIRE', key, String(ttlSec)]);
+    if (typeof reply === 'number') return reply;
+    if (reply === 'OK') return 1;
+    throw new RedisError(`EXPIRE returned unexpected reply: ${JSON.stringify(reply)}`);
+  }
+
+  /**
+   * 简单 pipeline：单连接一次连发所有命令，按发送顺序回读各条已解析回复。
+   * 返回数组与 `commands` 一一对应。
+   */
+  pipeline(commands: Array<string[]>): Promise<RedisReply[]> {
+    if (commands.length === 0) return Promise.resolve([]);
+    return this.enqueue(async () => {
+      await this.ensureConnected();
+      return this.sendAndRead(commands, commands.length);
+    });
+  }
+
+  /** 释放连接；之后所有命令立即抛错。 */
+  close(): void {
+    this.failPending(new Error('Redis client closed'));
+  }
+
+  // ── 内部：串行化与在途请求 ─────────────────────────────────────────────
+
+  private execute(args: string[]): Promise<RedisReply> {
+    if (args.length === 0) {
+      return Promise.reject(new RedisError('Empty command'));
+    }
+    return this.enqueue(async () => {
+      await this.ensureConnected();
+      const replies = await this.sendAndRead([args], 1);
+      return replies[0];
+    });
+  }
+
+  /** 命令 promise 链：任意时刻至多一个在途批次（单连接串行）。 */
+  private enqueue<T>(fn: () => Promise<T>): Promise<T> {
+    const run = this.chain.then(fn);
+    this.chain = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  }
+
+  private async ensureConnected(): Promise<void> {
+    if (this.socket) return;
+    if (this.dead) throw new Error('Redis client is closed; create a new client to reconnect');
+    let socket: RedisSocket;
+    try {
+      socket = await withTimeout(
+        this.transport.connect({ host: this.host, port: this.port, timeoutMs: this.connectTimeoutMs }),
+        this.connectTimeoutMs,
+        `Redis connect timeout after ${this.connectTimeoutMs}ms`,
+      );
+    } catch (err) {
+      this.dead = true;
+      throw err;
+    }
+    this.socket = socket;
+    socket.onData((chunk) => this.onData(chunk));
+    socket.onClose(() => this.onSocketClosed());
+    socket.onError((err) => this.onSocketError(err));
+  }
+
+  private sendAndRead(cmds: Array<string[]>, count: number): Promise<RedisReply[]> {
+    const socket = this.socket;
+    if (!socket) {
+      return Promise.reject(new Error('Redis client is not connected'));
+    }
+    return new Promise<RedisReply[]>((resolve, reject) => {
+      this.pending = { count, replies: [], resolve, reject, timer: null };
+      this.armTimer();
+      try {
+        for (const cmd of cmds) {
+          socket.write(encodeCommand(cmd));
+        }
+      } catch (err) {
+        this.failPending(err);
+      }
+    });
+  }
+
+  private armTimer(): void {
+    const pending = this.pending;
+    if (!pending) return;
+    this.clearTimer(pending);
+    pending.timer = setTimeout(() => {
+      this.failPending(new Error(`Redis command timeout after ${this.commandTimeoutMs}ms`));
+    }, this.commandTimeoutMs);
+  }
+
+  private clearTimer(pending: PendingRequest): void {
+    if (pending.timer !== null) {
+      clearTimeout(pending.timer);
+      pending.timer = null;
+    }
+  }
+
+  private onData(chunk: Uint8Array): void {
+    this.parser.push(chunk);
+    while (this.pending && this.parser.hasMore()) {
+      let reply: RedisReply | undefined;
+      try {
+        reply = this.parser.next();
+      } catch (err) {
+        // 单命令收到 `-ERR`：连接仍对齐，仅拒绝本次（连接存活）
+        if (err instanceof RedisError && this.pending && this.pending.count === 1) {
+          const pending = this.pending;
+          this.pending = null;
+          this.clearTimer(pending);
+          pending.reject(err);
+          return;
+        }
+        // 协议损坏 / pipeline 中途 `-ERR`：批次作废且连接不可继续信任
+        this.failPending(err);
+        return;
+      }
+      if (reply === undefined) break; // 半包，等更多数据
+      const pending = this.pending;
+      pending.replies.push(reply);
+      if (pending.replies.length >= pending.count) {
+        this.pending = null;
+        this.clearTimer(pending);
+        pending.resolve(pending.replies);
+      } else {
+        this.armTimer(); // 每收到一条回复滑动续期（单命令 = 仅一条）
+      }
+    }
+  }
+
+  private failPending(err: unknown): void {
+    const pending = this.pending;
+    if (pending) {
+      this.pending = null;
+      this.clearTimer(pending);
+      pending.reject(err instanceof Error ? err : new Error(String(err)));
+    }
+    this.markDead();
+  }
+
+  private onSocketClosed(): void {
+    if (!this.dead) {
+      this.failPending(new Error('Redis connection closed unexpectedly'));
+    }
+  }
+
+  private onSocketError(err: unknown): void {
+    if (!this.dead) {
+      const msg = err instanceof Error ? err.message : String(err);
+      this.failPending(new Error(`Redis connection error: ${msg}`));
+    }
+  }
+
+  private markDead(): void {
+    this.dead = true;
+    if (this.socket) {
+      try {
+        this.socket.end();
+      } catch {
+        /* ignore */
+      }
+      this.socket = null;
+    }
+  }
+}
+
+// ── 工具 ────────────────────────────────────────────────────────────────
+
+/** 在 `ms` 内未完成则 reject（连接超时兜底；默认 transport 内部亦自带超时）。 */
+function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      },
+    );
+  });
+}
+
+function assertInteger(reply: RedisReply, cmd: string): number {
+  if (typeof reply !== 'number') {
+    throw new RedisError(`${cmd} returned non-integer reply: ${JSON.stringify(reply)}`);
+  }
+  return reply;
+}

package/lib/usage-redis-multiproc.worker.ts

@@ -0,0 +1,80 @@
+/**
+ * Multi-process Redis relay worker for the 4.7 concurrency test. N of these
+ * run simultaneously against ONE shared realtime cache file + ONE mock Redis
+ * TCP server, each with its own poller/relay instance (independent probe
+ * state, independent write-through mirrors, independent periodic reconcile).
+ *
+ * Usage: bun usage-redis-multiproc.worker.ts <realtimeFile> <sessionId> <port> <ttlMs> <mode>
+ *   mode = 'write'  → cumulative flush writes + event-level sec deltas
+ *   mode = 'remove' → one write, then removeSessionUsage (session shutdown)
+ */
+import { dirname, join } from 'path';
+import {
+    _setRealtimeFileForTest,
+    _setFetchFileForTest,
+    _setLegacyCacheFileForTest,
+    startSharedPoller,
+    writeSessionUsage,
+    removeSessionUsage,
+    mirrorSessionDelta,
+} from './usage-poller.js';
+
+const [, , realtimeFile, sessionId, portStr, ttlMsStr, mode] = process.argv;
+const port = Number(portStr);
+const ttlMs = Number(ttlMsStr);
+if (!realtimeFile || !sessionId || !Number.isFinite(port) || !Number.isFinite(ttlMs)) {
+    console.error('usage: usage-redis-multiproc.worker.ts <realtimeFile> <sessionId> <port> <ttlMs> <mode>');
+    process.exit(2);
+}
+// Sandbox ALL cache paths: migrateLegacyCache must never read/write the real
+// ~/.omp/cache files (a live old-code process keeps the legacy file fresh).
+_setRealtimeFileForTest(realtimeFile);
+_setFetchFileForTest(join(dirname(realtimeFile), 'fetch.json'));
+_setLegacyCacheFileForTest(join(dirname(realtimeFile), 'legacy.json'));
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+const provider = `provider-${sessionId}`;
+// Frozen seconds in the recent past: reconcile covers them while the worker is
+// alive; the test asserts file == redis on exactly these keys.
+const baseSec = Math.floor(Date.now() / 1000) - 10;
+const frozenSeconds = { [String(baseSec)]: 1, [String(baseSec + 1)]: 2 };
+
+await startSharedPoller({ list: () => [] }, [], undefined, {
+    renderTickMs: 20,
+    tickMs: 60_000,
+    idleDirtyMs: 60_000,
+    redis: {
+        enabled: true,
+        host: '127.0.0.1',
+        port,
+        connectTimeoutMs: 300,
+        commandTimeoutMs: 300,
+        reconcileIntervalMs: 250,
+        probeIntervalMs: 500,
+        unhealthyRetryMs: 150,
+        ttlMs,
+    },
+});
+
+if (mode === 'write') {
+    const ITERS = 20;
+    for (let i = 1; i <= ITERS; i++) {
+        const secNow = String(Math.floor(Date.now() / 1000));
+        // Event-level mirror (HINCRBY) on the current second — exercises the
+        // concurrent-writer path on shared sec keys across processes.
+        mirrorSessionDelta(sessionId, provider, secNow, 1);
+        writeSessionUsage(sessionId, {
+            [provider]: { total: i, input: i, output: 0, seconds: frozenSeconds },
+        });
+        await sleep(30);
+    }
+    await sleep(400); // drain fire-and-forget mirrors + a final reconcile
+    console.log('WORKER_DONE');
+    process.exit(0); // the poller's renderTimer keeps the event loop alive
+} else {
+    writeSessionUsage(sessionId, { [provider]: { total: 1, input: 1, output: 0 } });
+    await sleep(150);
+    removeSessionUsage(sessionId);
+    await sleep(300); // drain the DEL (or its failure) before exiting
+    console.log('WORKER_DONE');
+    process.exit(0);
+}