codex-copilot-dx 0.6.19 → 0.6.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.6.19",
+  "version": "0.6.20",
   "description": "Use Codex Desktop, Claude Code, and Claude App with GitHub Copilot",
   "author": "Dale Xiao",
   "type": "module",

package/src/auth-profile.mjs

@@ -12,7 +12,7 @@ import {
   normalizeGithubIdentity,
 } from "./github-identity.mjs";
 import { withFileLock } from "./lock.mjs";
-import { parsePositiveInteger, RUNTIME_DEFAULTS } from "./runtime-config.mjs";
+import { parseSafePositiveInteger, RUNTIME_DEFAULTS } from "./runtime-config.mjs";
 
 export const AUTH_PROFILE_CODEX = "codex";
 export const AUTH_PROFILE_CLAUDE = "claude";
@@ -117,8 +117,8 @@ export function readAuthProfileCredentials(profile, { home = os.homedir() } = {}
 
 function lockOptions(env = process.env) {
   return {
-    timeoutMs: parsePositiveInteger(env.CCDX_TOKEN_LOCK_TIMEOUT_MS, RUNTIME_DEFAULTS.tokenLockTimeoutMs),
-    staleMs: parsePositiveInteger(env.CCDX_TOKEN_LOCK_STALE_MS, RUNTIME_DEFAULTS.tokenLockStaleMs),
+    timeoutMs: parseSafePositiveInteger(env.CCDX_TOKEN_LOCK_TIMEOUT_MS, RUNTIME_DEFAULTS.tokenLockTimeoutMs),
+    staleMs: parseSafePositiveInteger(env.CCDX_TOKEN_LOCK_STALE_MS, RUNTIME_DEFAULTS.tokenLockStaleMs),
   };
 }
 

package/src/auth.mjs

@@ -8,7 +8,7 @@ import {
   githubTokenFingerprint,
   normalizeGithubIdentity,
 } from "./github-identity.mjs";
-import { parsePositiveInteger, RUNTIME_DEFAULTS } from "./runtime-config.mjs";
+import { parseSafePositiveInteger, parseTimerMs, RUNTIME_DEFAULTS } from "./runtime-config.mjs";
 import { status } from "./status.mjs";
 import { withFileLock } from "./lock.mjs";
 
@@ -20,6 +20,7 @@ const ACCESS_TOKEN_URL = "https://github.com/login/oauth/access_token";
 const DEFAULT_DEVICE_INTERVAL_SECONDS = 5;
 const DEFAULT_DEVICE_EXPIRES_SECONDS = 900;
 const DEFAULT_DEVICE_CODE_TIMEOUT_MS = 30 * 1000;
+const DEFAULT_GITHUB_IDENTITY_TIMEOUT_MS = 30 * 1000;
 const MAX_DEVICE_FLOW_JSON_BYTES = 64 * 1024;
 const DISABLE_TOKEN_DISCOVERY_VALUES = new Set(["1", "true", "yes"]);
 const MAX_AUTH_JSON_BYTES = 1024 * 1024;
@@ -258,8 +259,8 @@ function isTokenDiscoveryDisabled(env = process.env) {
 
 function tokenLockOptions(env = process.env) {
   return {
-    timeoutMs: parsePositiveInteger(env.CCDX_TOKEN_LOCK_TIMEOUT_MS, RUNTIME_DEFAULTS.tokenLockTimeoutMs),
-    staleMs: parsePositiveInteger(env.CCDX_TOKEN_LOCK_STALE_MS, RUNTIME_DEFAULTS.tokenLockStaleMs),
+    timeoutMs: parseSafePositiveInteger(env.CCDX_TOKEN_LOCK_TIMEOUT_MS, RUNTIME_DEFAULTS.tokenLockTimeoutMs),
+    staleMs: parseSafePositiveInteger(env.CCDX_TOKEN_LOCK_STALE_MS, RUNTIME_DEFAULTS.tokenLockStaleMs),
   };
 }
 
@@ -425,19 +426,47 @@ function expectedGithubIdentity(home, env, token) {
   return token ? readGithubTokenMetadata(home, token) : null;
 }
 
-export async function fetchGithubIdentity(token, { fetchImpl = fetch, signal } = {}) {
+function githubIdentityTimeoutError(timeoutMs) {
+  const error = new Error(`GitHub identity request timed out after ${timeoutMs}ms`);
+  error.code = "CCDX_GITHUB_IDENTITY_TIMEOUT";
+  return error;
+}
+
+export async function fetchGithubIdentity(token, {
+  fetchImpl = fetch,
+  signal,
+  timeoutMs = DEFAULT_GITHUB_IDENTITY_TIMEOUT_MS,
+} = {}) {
   if (typeof token !== "string" || !token.trim()) return { ok: false, reason: "empty_token" };
+  const deadlineMs = parseTimerMs(timeoutMs, DEFAULT_GITHUB_IDENTITY_TIMEOUT_MS);
+  const controller = new AbortController();
+  const onCallerAbort = () => controller.abort(signal?.reason);
+  signal?.addEventListener("abort", onCallerAbort, { once: true });
+  if (signal?.aborted) onCallerAbort();
+  const timer = setTimeout(() => controller.abort(githubIdentityTimeoutError(deadlineMs)), deadlineMs);
+  let resp;
   try {
-    const resp = await fetchImpl(`${GITHUB_API}/user`, {
+    resp = await awaitWithSignal(() => fetchImpl(`${GITHUB_API}/user`, {
       headers: { Authorization: `token ${token.trim()}`, Accept: "application/json" },
-      signal,
-    });
+      signal: controller.signal,
+    }), controller.signal);
     if (!resp.ok) return { ok: false, status: resp.status, reason: "github_user_failed" };
-    const data = await resp.json();
+    const data = await awaitWithSignal(() => resp.json(), controller.signal);
     const identity = normalizeGithubIdentity(data);
     return identity ? { ok: true, ...identity } : { ok: false, reason: "github_identity_missing" };
   } catch (error) {
-    return { ok: false, transient: true, reason: "github_user_request_failed", error };
+    cancelResponseBody(resp);
+    const timedOut = controller.signal.aborted && !signal?.aborted
+      && controller.signal.reason?.code === "CCDX_GITHUB_IDENTITY_TIMEOUT";
+    return {
+      ok: false,
+      transient: true,
+      reason: timedOut ? "github_user_timeout" : "github_user_request_failed",
+      error,
+    };
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onCallerAbort);
   }
 }
 
@@ -661,6 +690,7 @@ export async function ensureAuth({
   log = console.log,
   openAndCopyFn = openAndCopy,
   deviceCodeTimeoutMs = DEFAULT_DEVICE_CODE_TIMEOUT_MS,
+  githubIdentityTimeoutMs = DEFAULT_GITHUB_IDENTITY_TIMEOUT_MS,
   sleepImpl = sleep,
   now = Date.now,
 } = {}) {
@@ -720,7 +750,11 @@ export async function ensureAuth({
       now,
     });
     if (result.state === "done") {
-      const identity = await fetchGithubIdentity(result.token, { fetchImpl, signal });
+      const identity = await fetchGithubIdentity(result.token, {
+        fetchImpl,
+        signal,
+        timeoutMs: githubIdentityTimeoutMs,
+      });
       writeToken(result.token, home, identity.ok ? identity : null);
       log(status("ok", "Login successful"));
       return;

package/src/auto-review-model.mjs

@@ -12,12 +12,12 @@ import {
   readUserSettings,
   writeAutoReviewModel,
 } from "./user-settings.mjs";
+import { parseTimerMs } from "./runtime-config.mjs";
 
 const DEFAULT_MODEL_FETCH_TIMEOUT_MS = 5000;
 
 function modelFetchTimeout(env) {
-  const value = Number(env.CCDX_MODEL_REFRESH_TIMEOUT_MS);
-  return Number.isSafeInteger(value) && value > 0 ? value : DEFAULT_MODEL_FETCH_TIMEOUT_MS;
+  return parseTimerMs(env.CCDX_MODEL_REFRESH_TIMEOUT_MS, DEFAULT_MODEL_FETCH_TIMEOUT_MS);
 }
 
 function sortedModelIds(modelIds, currentModel) {

package/src/cli-auth.mjs

@@ -15,7 +15,7 @@ import {
   withAuthProfileLock,
   writeClaudeAuthProfile,
 } from "./auth-profile.mjs";
-import { buildHeaders, DEFAULT_API_BASE, FALLBACK_VSCODE_VERSION } from "./copilot.mjs";
+import { buildHeaders, FALLBACK_VSCODE_VERSION, parseApiBase } from "./copilot.mjs";
 import {
   githubIdentitiesEqual,
   githubTokenFingerprint,
@@ -178,7 +178,7 @@ async function fetchCopilotCatalog(tokenData, {
   const timer = setTimeout(() => controller.abort(catalogTimeoutError(label, deadlineMs)), deadlineMs);
   let modelResponse;
   try {
-    const apiBase = tokenData?.endpoints?.api || DEFAULT_API_BASE;
+    const apiBase = parseApiBase(tokenData);
     const headers = buildHeaders({
       token: tokenData.token,
       version: vscodeVersion,

package/src/cli-error.mjs

@@ -22,7 +22,13 @@ function boundedTerminalText(value, fallback, maxCharacters) {
 }
 
 export function formatCliError(error) {
-  const message = boundedTerminalText(error?.message, "Command failed", MAX_MESSAGE_CHARACTERS);
+  let rawMessage;
+  try {
+    rawMessage = error?.message;
+  } catch {
+    rawMessage = undefined;
+  }
+  const message = boundedTerminalText(rawMessage, "Command failed", MAX_MESSAGE_CHARACTERS);
   let details;
   try {
     details = error?.details;

package/src/cli-models.mjs

@@ -5,7 +5,7 @@ import {
   AUTH_PROFILE_CODEX,
   readAuthProfileCredentials,
 } from "./auth-profile.mjs";
-import { buildHeaders, DEFAULT_API_BASE, FALLBACK_VSCODE_VERSION } from "./copilot.mjs";
+import { buildHeaders, FALLBACK_VSCODE_VERSION, parseApiBase } from "./copilot.mjs";
 import {
   isClaudeCopilotCatalogEntry,
   isClaudeCopilotModel,
@@ -134,7 +134,7 @@ export async function fetchLiveCopilotModels({
     if (!validation.ok) throw new Error(validationFailure(validation));
 
     const tokenData = validation.copilotTokenData;
-    const apiBase = tokenData.endpoints?.api || DEFAULT_API_BASE;
+    const apiBase = parseApiBase(tokenData);
     const headers = buildHeaders({
       token: tokenData.token,
       version: vscodeVersion,

package/src/cli-options.mjs

@@ -1,3 +1,5 @@
+import { MAX_TIMER_DELAY_MS } from "./runtime-config.mjs";
+
 const HELP_COMMANDS = new Set(["help", "--help", "-h"]);
 const VERSION_COMMANDS = new Set(["version", "--version", "-v"]);
 const START_OPTIONS = new Map([
@@ -262,13 +264,13 @@ export function parseRuntimeOptions(env = process.env) {
   return {
     adapterPort: integerEnv(env, "ADAPTER_PORT", 2026, { min: 1, max: 65535 }),
     adapterHost: String(env.ADAPTER_HOST || "127.0.0.1").trim() || "127.0.0.1",
-    modelRefreshTimeoutMs: integerEnv(env, "CCDX_MODEL_REFRESH_TIMEOUT_MS", 5000, { min: 1 }),
-    existingAdapterTimeoutMs: integerEnv(env, "CCDX_EXISTING_ADAPTER_TIMEOUT_MS", 500, { min: 1 }),
-    modelRefreshIntervalMs: integerEnv(env, "CCDX_MODEL_REFRESH_INTERVAL_MS", 2 * 60 * 60 * 1000, { min: 0 }),
-    upstreamTimeoutMs: integerEnv(env, "CCDX_UPSTREAM_TIMEOUT_MS", 120000, { min: 1 }),
-    streamHandshakeTimeoutMs: integerEnv(env, "CCDX_STREAM_HANDSHAKE_TIMEOUT_MS", 120000, { min: 1 }),
-    streamIdleTimeoutMs: integerEnv(env, "CCDX_STREAM_IDLE_TIMEOUT_MS", 120000, { min: 1 }),
-    shutdownTimeoutMs: integerEnv(env, "CCDX_SHUTDOWN_TIMEOUT_MS", 5000, { min: 1 }),
+    modelRefreshTimeoutMs: integerEnv(env, "CCDX_MODEL_REFRESH_TIMEOUT_MS", 5000, { min: 1, max: MAX_TIMER_DELAY_MS }),
+    existingAdapterTimeoutMs: integerEnv(env, "CCDX_EXISTING_ADAPTER_TIMEOUT_MS", 500, { min: 1, max: MAX_TIMER_DELAY_MS }),
+    modelRefreshIntervalMs: integerEnv(env, "CCDX_MODEL_REFRESH_INTERVAL_MS", 2 * 60 * 60 * 1000, { min: 0, max: MAX_TIMER_DELAY_MS }),
+    upstreamTimeoutMs: integerEnv(env, "CCDX_UPSTREAM_TIMEOUT_MS", 120000, { min: 1, max: MAX_TIMER_DELAY_MS }),
+    streamHandshakeTimeoutMs: integerEnv(env, "CCDX_STREAM_HANDSHAKE_TIMEOUT_MS", 120000, { min: 1, max: MAX_TIMER_DELAY_MS }),
+    streamIdleTimeoutMs: integerEnv(env, "CCDX_STREAM_IDLE_TIMEOUT_MS", 120000, { min: 1, max: MAX_TIMER_DELAY_MS }),
+    shutdownTimeoutMs: integerEnv(env, "CCDX_SHUTDOWN_TIMEOUT_MS", 5000, { min: 1, max: MAX_TIMER_DELAY_MS }),
   };
 }
 
@@ -276,7 +278,7 @@ export function parseAdapterProbeOptions(env = process.env) {
   return {
     adapterPort: integerEnv(env, "ADAPTER_PORT", 2026, { min: 1, max: 65535 }),
     adapterHost: String(env.ADAPTER_HOST || "127.0.0.1").trim() || "127.0.0.1",
-    existingAdapterTimeoutMs: integerEnv(env, "CCDX_EXISTING_ADAPTER_TIMEOUT_MS", 500, { min: 1 }),
+    existingAdapterTimeoutMs: integerEnv(env, "CCDX_EXISTING_ADAPTER_TIMEOUT_MS", 500, { min: 1, max: MAX_TIMER_DELAY_MS }),
   };
 }
 

package/src/copilot-token-session.mjs

@@ -60,6 +60,20 @@ function refreshError(message, { statusCode, transient = false } = {}) {
   return error;
 }
 
+function transientRefreshError(error) {
+  let message = "Copilot token request failed";
+  try {
+    if (typeof error?.message === "string" && error.message) message = error.message;
+  } catch {}
+  const wrapped = new Error(message, { cause: error });
+  try {
+    if (typeof error?.code === "string") wrapped.code = error.code;
+    if (Number.isInteger(error?.statusCode)) wrapped.statusCode = error.statusCode;
+  } catch {}
+  wrapped.transient = true;
+  return wrapped;
+}
+
 function copilotProfileLabel(profile) {
   if (profile === "codex") return "Copilot";
   const name = String(profile || "profile");
@@ -189,6 +203,7 @@ export function createCopilotTokenSession({
     allowAccountSwitch = false,
   }) {
     if (!data.token) throw new Error("Copilot token response missing token field");
+    const nextApiBase = parseApiBase(data);
     const fingerprint = githubTokenFingerprint(githubToken);
     const normalizedIdentity = normalizeGithubIdentity(identity);
     const tokenChanged = Boolean(githubFingerprint && fingerprint !== githubFingerprint);
@@ -204,7 +219,7 @@ export function createCopilotTokenSession({
       throw error;
     }
     copilotToken = data.token;
-    apiBase = parseApiBase(data);
+    apiBase = nextApiBase;
     copilotTokenExpiry = typeof data.expires_at === "number"
       ? data.expires_at * 1000
       : Date.now() + 25 * 60 * 1000;
@@ -232,7 +247,7 @@ export function createCopilotTokenSession({
         signal,
       }, { fetchImpl, ...tokenRetryOptions });
     } catch (error) {
-      if (!isAbortError(error, signal)) error.transient = true;
+      if (!isAbortError(error, signal)) throw transientRefreshError(error);
       throw error;
     }
     if (!response.ok) {

package/src/copilot.mjs

@@ -33,9 +33,28 @@ export function parseUpstreamRetryDelayMs(value) {
 }
 
 export function parseApiBase(data) {
-  return (data && data.endpoints && typeof data.endpoints.api === "string" && data.endpoints.api)
-    ? data.endpoints.api
-    : DEFAULT_API_BASE;
+  const configured = data?.endpoints?.api;
+  if (typeof configured !== "string" || !configured.trim()) return DEFAULT_API_BASE;
+  let parsed;
+  try {
+    parsed = new URL(configured.trim());
+  } catch {
+    throw Object.assign(new Error("Copilot API endpoint is invalid"), {
+      code: "CCDX_INVALID_COPILOT_API_ENDPOINT",
+    });
+  }
+  if (parsed.protocol !== "https:"
+    || !parsed.hostname
+    || parsed.username
+    || parsed.password
+    || parsed.search
+    || parsed.hash) {
+    throw Object.assign(new Error("Copilot API endpoint is invalid"), {
+      code: "CCDX_INVALID_COPILOT_API_ENDPOINT",
+    });
+  }
+  const pathname = parsed.pathname.replace(/\/+$/, "");
+  return `${parsed.origin}${pathname && pathname !== "/" ? pathname : ""}`;
 }
 
 export function responsesEndpointPath() {

package/src/doctor.mjs

@@ -10,7 +10,7 @@ import {
 } from "./auth-profile.mjs";
 import { claudeDesktopPaths } from "./claude-desktop-config.mjs";
 import { status } from "./status.mjs";
-import { buildHeaders, DEFAULT_API_BASE, FALLBACK_VSCODE_VERSION } from "./copilot.mjs";
+import { buildHeaders, FALLBACK_VSCODE_VERSION, parseApiBase } from "./copilot.mjs";
 import { adapterBaseUrl, checkRunningAdapter } from "./running-adapter.mjs";
 import { CODEX_AUTO_REVIEW_MODEL, isClaudeCopilotModel } from "./models.mjs";
 import { loadModelCache } from "./model-cache.mjs";
@@ -322,7 +322,7 @@ export async function inspectGitHubTokenOnline({
     }
 
     const tokenData = validation.copilotTokenData;
-    const apiBase = tokenData.endpoints?.api || DEFAULT_API_BASE;
+    const apiBase = parseApiBase(tokenData);
     const headers = buildHeaders({
       token: tokenData.token,
       version: FALLBACK_VSCODE_VERSION,

package/src/http-transport.mjs

@@ -407,6 +407,9 @@ export function createRequestAdmission({
         continue;
       }
       if (activeBytes + entry.weight > byteLimit) {
+        // Unknown-length requests reserve the whole budget. Once one is waiting,
+        // do not let later arrivals keep extending its wait indefinitely.
+        if (entry.weight === byteLimit) break;
         index += 1;
         continue;
       }
@@ -422,11 +425,13 @@ export function createRequestAdmission({
       return Promise.reject(admissionAbortError(signal));
     }
     const weight = requestAdmissionWeight(req, byteLimit);
-    if (queue.length >= queueLimit && activeBytes + weight > byteLimit) {
+    const blockedByExclusive = queue.some((entry) => !entry.cancelled && entry.weight === byteLimit);
+    const mustWait = blockedByExclusive || activeBytes + weight > byteLimit;
+    if (queue.length >= queueLimit && mustWait) {
       counters.rejected += 1;
       return Promise.reject(httpError(`Request queue is full (${queueLimit} waiting)`, 503));
     }
-    if (activeBytes + weight > byteLimit) counters.queued += 1;
+    if (mustWait) counters.queued += 1;
 
     return new Promise((resolve, reject) => {
       let timer;

package/src/pm-studio-bundle-content.mjs

@@ -0,0 +1,165 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { sha256Hex } from "./pm-studio-asar.mjs";
+
+const BUNDLE_CONTENT_SCHEME = "ccdx-bundle-content-v2";
+
+function setupError(code, message, details) {
+  const error = new Error(message);
+  error.code = code;
+  if (details !== undefined) error.details = details;
+  return error;
+}
+
+function hashRegularFile(filePath, expected, readBuffer) {
+  const hash = createHash("sha256");
+  const file = fs.openSync(filePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+  const buffer = readBuffer || Buffer.allocUnsafe(1024 * 1024);
+  try {
+    const before = fs.fstatSync(file, { bigint: true });
+    if (before.dev !== BigInt(expected.dev)
+      || before.ino !== BigInt(expected.ino)
+      || before.size !== BigInt(expected.size)) {
+      throw setupError("PM_STUDIO_BUNDLE_CHANGED", `PM Studio bundle changed while reading ${filePath}`);
+    }
+    for (;;) {
+      const length = fs.readSync(file, buffer, 0, buffer.length, null);
+      if (length === 0) break;
+      hash.update(buffer.subarray(0, length));
+    }
+    const after = fs.fstatSync(file, { bigint: true });
+    if (before.dev !== after.dev
+      || before.ino !== after.ino
+      || before.size !== after.size
+      || before.mtimeNs !== after.mtimeNs
+      || before.ctimeNs !== after.ctimeNs) {
+      throw setupError("PM_STUDIO_BUNDLE_CHANGED", `PM Studio bundle changed while hashing ${filePath}`);
+    }
+  } finally {
+    fs.closeSync(file);
+  }
+  return hash.digest("hex");
+}
+
+function parseXattrHex(output, root, ignoredXattrs) {
+  const records = [];
+  const ignored = new Set(ignoredXattrs);
+  const seen = new Set();
+  let current = null;
+  const flush = () => {
+    if (!current) return;
+    if (!ignored.has(current.name)) {
+      const key = `${current.path}\0${current.name}`;
+      if (seen.has(key)) throw setupError("PM_STUDIO_XATTR_INVALID", `Duplicate extended attribute ${current.name}`);
+      seen.add(key);
+      const value = Buffer.from(current.hex.join(""), "hex");
+      records.push(["xattr", current.path, current.name, value.length, sha256Hex(value)]);
+    }
+    current = null;
+  };
+
+  for (const line of String(output || "").split(/\r?\n/)) {
+    if (!line) continue;
+    const separator = line.lastIndexOf(": ");
+    if ((line === `${root}:` || line.startsWith(`${root}: `) || line.startsWith(`${root}${path.sep}`))
+      && separator >= root.length && line.endsWith(":")) {
+      flush();
+      const target = line.slice(0, separator);
+      const relative = target === root ? "." : path.relative(root, target).split(path.sep).join("/");
+      if (!relative || relative === ".." || relative.startsWith("../") || path.isAbsolute(relative)) {
+        throw setupError("PM_STUDIO_XATTR_INVALID", `Extended attribute path escapes PM Studio: ${target}`);
+      }
+      current = { path: relative, name: line.slice(separator + 2, -1), hex: [] };
+      continue;
+    }
+    if (!current) throw setupError("PM_STUDIO_XATTR_INVALID", "Could not parse PM Studio extended attributes");
+    const data = line.includes("  |") ? line.slice(0, line.indexOf("  |")) : line;
+    const tokens = data.trim().split(/\s+/);
+    if (!/^[0-9a-f]{8}$/i.test(tokens[0]) || tokens.slice(1).some((token) => !/^[0-9a-f]{2}$/i.test(token))) {
+      throw setupError("PM_STUDIO_XATTR_INVALID", "Could not parse PM Studio extended attribute bytes");
+    }
+    current.hex.push(...tokens.slice(1));
+  }
+  flush();
+  return records.sort((left, right) => Buffer.compare(
+    Buffer.from(`${left[1]}\0${left[2]}`),
+    Buffer.from(`${right[1]}\0${right[2]}`),
+  ));
+}
+
+export function inspectBundleContent(appPath, {
+  xattrOutput = "",
+  ignoredXattrs = [],
+  readBuffer,
+} = {}) {
+  const root = path.resolve(appPath);
+  const rootStat = fs.lstatSync(root);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+    throw setupError("PM_STUDIO_APP_INVALID", `PM Studio path is not a regular app bundle: ${appPath}`);
+  }
+  const records = [];
+  const normalizedPaths = new Map();
+  let regularFileCount = 0;
+  let regularBytes = 0;
+  let symlinkCount = 0;
+
+  const rememberPath = (relative) => {
+    const normalized = relative.normalize("NFC");
+    const existing = normalizedPaths.get(normalized);
+    if (existing && existing !== relative) {
+      throw setupError("PM_STUDIO_BUNDLE_PATH_COLLISION", `PM Studio contains colliding paths: ${existing} and ${relative}`);
+    }
+    normalizedPaths.set(normalized, relative);
+  };
+  rememberPath(".");
+  records.push(["directory", ".", rootStat.mode & 0o7777]);
+  const visit = (directory) => {
+    const names = fs.readdirSync(directory).sort((left, right) =>
+      Buffer.compare(Buffer.from(left), Buffer.from(right)));
+    for (const name of names) {
+      const fullPath = path.join(directory, name);
+      const stat = fs.lstatSync(fullPath);
+      const relative = path.relative(root, fullPath).split(path.sep).join("/");
+      const mode = stat.mode & 0o7777;
+      rememberPath(relative);
+      if (stat.isDirectory() && !stat.isSymbolicLink()) {
+        records.push(["directory", relative, mode]);
+        visit(fullPath);
+      } else if (stat.isSymbolicLink()) {
+        const target = fs.readlinkSync(fullPath);
+        const resolved = path.resolve(path.dirname(fullPath), target);
+        if (path.isAbsolute(target)
+          || (resolved !== root && !resolved.startsWith(`${root}${path.sep}`))
+          || !fs.existsSync(resolved)) {
+          throw setupError("PM_STUDIO_BUNDLE_SYMLINK_INVALID", `PM Studio contains an unsafe symlink: ${relative}`);
+        }
+        symlinkCount += 1;
+        records.push(["symlink", relative, mode, target]);
+      } else if (stat.isFile()) {
+        if (stat.nlink !== 1) {
+          throw setupError("PM_STUDIO_BUNDLE_HARDLINK_INVALID", `PM Studio contains a hard-linked file: ${relative}`);
+        }
+        regularFileCount += 1;
+        regularBytes += stat.size;
+        records.push(["file", relative, mode, stat.size, hashRegularFile(fullPath, stat, readBuffer)]);
+      } else {
+        throw setupError("PM_STUDIO_BUNDLE_ENTRY_INVALID", `PM Studio contains an unsupported entry: ${relative}`);
+      }
+    }
+  };
+  visit(root);
+
+  const xattrRecords = parseXattrHex(xattrOutput, root, ignoredXattrs);
+  const hash = createHash("sha256");
+  for (const record of [...records, ...xattrRecords]) hash.update(`${JSON.stringify(record)}\n`);
+  return {
+    scheme: BUNDLE_CONTENT_SCHEME,
+    sha256: hash.digest("hex"),
+    entryCount: records.length,
+    regularFileCount,
+    regularBytes,
+    symlinkCount,
+    xattrCount: xattrRecords.length,
+  };
+}

package/src/pm-studio-setup.mjs

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import {
   AUTH_PROFILE_CLAUDE,
@@ -20,12 +20,14 @@ import {
   patchAsarBuffer,
   sha256Hex,
 } from "./pm-studio-asar.mjs";
+import { inspectBundleContent } from "./pm-studio-bundle-content.mjs";
 import { withPmStudioSetupLock } from "./pm-studio-setup-lock.mjs";
 
+export { inspectBundleContent } from "./pm-studio-bundle-content.mjs";
+
 export const DEFAULT_PM_STUDIO_APP_PATH = "/Applications/PM Studio.app";
 export const PM_STUDIO_CLAUDE_AUTH_COMMAND = "ccdx auth login claude --reauth --github-login <personal-login>";
 const MIN_FREE_MARGIN_BYTES = 16 * 1024 * 1024;
-const BUNDLE_CONTENT_SCHEME = "ccdx-bundle-content-v2";
 
 function setupError(code, message, details) {
   const error = new Error(message);
@@ -60,158 +62,6 @@ function runChecked(processRunner, command, args, label) {
   return result;
 }
 
-function hashRegularFile(filePath, expected, readBuffer) {
-  const hash = createHash("sha256");
-  const file = fs.openSync(filePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
-  const buffer = readBuffer || Buffer.allocUnsafe(1024 * 1024);
-  try {
-    const before = fs.fstatSync(file, { bigint: true });
-    if (before.dev !== BigInt(expected.dev)
-      || before.ino !== BigInt(expected.ino)
-      || before.size !== BigInt(expected.size)) {
-      throw setupError("PM_STUDIO_BUNDLE_CHANGED", `PM Studio bundle changed while reading ${filePath}`);
-    }
-    for (;;) {
-      const length = fs.readSync(file, buffer, 0, buffer.length, null);
-      if (length === 0) break;
-      hash.update(buffer.subarray(0, length));
-    }
-    const after = fs.fstatSync(file, { bigint: true });
-    if (before.dev !== after.dev
-      || before.ino !== after.ino
-      || before.size !== after.size
-      || before.mtimeNs !== after.mtimeNs
-      || before.ctimeNs !== after.ctimeNs) {
-      throw setupError("PM_STUDIO_BUNDLE_CHANGED", `PM Studio bundle changed while hashing ${filePath}`);
-    }
-  } finally {
-    fs.closeSync(file);
-  }
-  return hash.digest("hex");
-}
-
-function parseXattrHex(output, root, ignoredXattrs) {
-  const records = [];
-  const ignored = new Set(ignoredXattrs);
-  const seen = new Set();
-  let current = null;
-  const flush = () => {
-    if (!current) return;
-    if (!ignored.has(current.name)) {
-      const key = `${current.path}\0${current.name}`;
-      if (seen.has(key)) throw setupError("PM_STUDIO_XATTR_INVALID", `Duplicate extended attribute ${current.name}`);
-      seen.add(key);
-      const value = Buffer.from(current.hex.join(""), "hex");
-      records.push(["xattr", current.path, current.name, value.length, sha256Hex(value)]);
-    }
-    current = null;
-  };
-
-  for (const line of String(output || "").split(/\r?\n/)) {
-    if (!line) continue;
-    const separator = line.lastIndexOf(": ");
-    if ((line === `${root}:` || line.startsWith(`${root}: `) || line.startsWith(`${root}${path.sep}`))
-      && separator >= root.length && line.endsWith(":")) {
-      flush();
-      const target = line.slice(0, separator);
-      const relative = target === root ? "." : path.relative(root, target).split(path.sep).join("/");
-      if (!relative || relative === ".." || relative.startsWith("../") || path.isAbsolute(relative)) {
-        throw setupError("PM_STUDIO_XATTR_INVALID", `Extended attribute path escapes PM Studio: ${target}`);
-      }
-      current = { path: relative, name: line.slice(separator + 2, -1), hex: [] };
-      continue;
-    }
-    if (!current) throw setupError("PM_STUDIO_XATTR_INVALID", "Could not parse PM Studio extended attributes");
-    const data = line.includes("  |") ? line.slice(0, line.indexOf("  |")) : line;
-    const tokens = data.trim().split(/\s+/);
-    if (!/^[0-9a-f]{8}$/i.test(tokens[0]) || tokens.slice(1).some((token) => !/^[0-9a-f]{2}$/i.test(token))) {
-      throw setupError("PM_STUDIO_XATTR_INVALID", "Could not parse PM Studio extended attribute bytes");
-    }
-    current.hex.push(...tokens.slice(1));
-  }
-  flush();
-  return records.sort((left, right) => Buffer.compare(
-    Buffer.from(`${left[1]}\0${left[2]}`),
-    Buffer.from(`${right[1]}\0${right[2]}`),
-  ));
-}
-
-export function inspectBundleContent(appPath, {
-  xattrOutput = "",
-  ignoredXattrs = [],
-  readBuffer,
-} = {}) {
-  const root = path.resolve(appPath);
-  const rootStat = fs.lstatSync(root);
-  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
-    throw setupError("PM_STUDIO_APP_INVALID", `PM Studio path is not a regular app bundle: ${appPath}`);
-  }
-  const records = [];
-  const normalizedPaths = new Map();
-  let regularFileCount = 0;
-  let regularBytes = 0;
-  let symlinkCount = 0;
-
-  const rememberPath = (relative) => {
-    const normalized = relative.normalize("NFC");
-    const existing = normalizedPaths.get(normalized);
-    if (existing && existing !== relative) {
-      throw setupError("PM_STUDIO_BUNDLE_PATH_COLLISION", `PM Studio contains colliding paths: ${existing} and ${relative}`);
-    }
-    normalizedPaths.set(normalized, relative);
-  };
-  rememberPath(".");
-  records.push(["directory", ".", rootStat.mode & 0o7777]);
-  const visit = (directory) => {
-    const names = fs.readdirSync(directory).sort((left, right) =>
-      Buffer.compare(Buffer.from(left), Buffer.from(right)));
-    for (const name of names) {
-      const fullPath = path.join(directory, name);
-      const stat = fs.lstatSync(fullPath);
-      const relative = path.relative(root, fullPath).split(path.sep).join("/");
-      const mode = stat.mode & 0o7777;
-      rememberPath(relative);
-      if (stat.isDirectory() && !stat.isSymbolicLink()) {
-        records.push(["directory", relative, mode]);
-        visit(fullPath);
-      } else if (stat.isSymbolicLink()) {
-        const target = fs.readlinkSync(fullPath);
-        const resolved = path.resolve(path.dirname(fullPath), target);
-        if (path.isAbsolute(target)
-          || (resolved !== root && !resolved.startsWith(`${root}${path.sep}`))
-          || !fs.existsSync(resolved)) {
-          throw setupError("PM_STUDIO_BUNDLE_SYMLINK_INVALID", `PM Studio contains an unsafe symlink: ${relative}`);
-        }
-        symlinkCount += 1;
-        records.push(["symlink", relative, mode, target]);
-      } else if (stat.isFile()) {
-        if (stat.nlink !== 1) {
-          throw setupError("PM_STUDIO_BUNDLE_HARDLINK_INVALID", `PM Studio contains a hard-linked file: ${relative}`);
-        }
-        regularFileCount += 1;
-        regularBytes += stat.size;
-        records.push(["file", relative, mode, stat.size, hashRegularFile(fullPath, stat, readBuffer)]);
-      } else {
-        throw setupError("PM_STUDIO_BUNDLE_ENTRY_INVALID", `PM Studio contains an unsupported entry: ${relative}`);
-      }
-    }
-  };
-  visit(root);
-
-  const xattrRecords = parseXattrHex(xattrOutput, root, ignoredXattrs);
-  const hash = createHash("sha256");
-  for (const record of [...records, ...xattrRecords]) hash.update(`${JSON.stringify(record)}\n`);
-  return {
-    scheme: BUNDLE_CONTENT_SCHEME,
-    sha256: hash.digest("hex"),
-    entryCount: records.length,
-    regularFileCount,
-    regularBytes,
-    symlinkCount,
-    xattrCount: xattrRecords.length,
-  };
-}
-
 function defaultInspectBundleContent({ appPath, recipe, processRunner, readBuffer }) {
   const xattrs = runChecked(processRunner, "/usr/bin/xattr", ["-r", "-s", "-x", "-l", appPath],
     "Reading PM Studio extended attributes");

package/src/runtime-config.mjs

@@ -17,17 +17,33 @@ export const RUNTIME_DEFAULTS = Object.freeze({
   tokenLockStaleMs: 15 * 60 * 1000,
 });
 
+// Node clamps larger timer delays to 1ms. Keep timer parsing separate from
+// byte/count limits so valid large resource budgets remain configurable.
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
 export function parsePositiveInteger(value, fallback, max = Number.POSITIVE_INFINITY) {
   const parsed = Number.parseInt(value, 10);
   return Number.isFinite(parsed) && parsed > 0 ? Math.min(parsed, max) : fallback;
 }
 
+export function parseSafePositiveInteger(value, fallback) {
+  const text = typeof value === "number" ? String(value) : String(value ?? "").trim();
+  if (!/^\d+$/.test(text)) return fallback;
+  const parsed = Number(text);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) return fallback;
+  return parsed;
+}
+
+export function parseTimerMs(value, fallback) {
+  return Math.min(parseSafePositiveInteger(value, fallback), MAX_TIMER_DELAY_MS);
+}
+
 export function loadRuntimeConfig(env = process.env) {
   return Object.freeze({
-    upstreamTimeoutMs: parsePositiveInteger(env.CCDX_UPSTREAM_TIMEOUT_MS, RUNTIME_DEFAULTS.upstreamTimeoutMs),
-    streamHandshakeTimeoutMs: parsePositiveInteger(env.CCDX_STREAM_HANDSHAKE_TIMEOUT_MS, RUNTIME_DEFAULTS.streamHandshakeTimeoutMs),
-    streamIdleTimeoutMs: parsePositiveInteger(env.CCDX_STREAM_IDLE_TIMEOUT_MS, RUNTIME_DEFAULTS.streamIdleTimeoutMs),
-    requestBodyTimeoutMs: parsePositiveInteger(env.CCDX_REQUEST_BODY_TIMEOUT_MS, RUNTIME_DEFAULTS.requestBodyTimeoutMs),
+    upstreamTimeoutMs: parseTimerMs(env.CCDX_UPSTREAM_TIMEOUT_MS, RUNTIME_DEFAULTS.upstreamTimeoutMs),
+    streamHandshakeTimeoutMs: parseTimerMs(env.CCDX_STREAM_HANDSHAKE_TIMEOUT_MS, RUNTIME_DEFAULTS.streamHandshakeTimeoutMs),
+    streamIdleTimeoutMs: parseTimerMs(env.CCDX_STREAM_IDLE_TIMEOUT_MS, RUNTIME_DEFAULTS.streamIdleTimeoutMs),
+    requestBodyTimeoutMs: parseTimerMs(env.CCDX_REQUEST_BODY_TIMEOUT_MS, RUNTIME_DEFAULTS.requestBodyTimeoutMs),
     maxSseBufferBytes: parsePositiveInteger(env.CCDX_MAX_SSE_BUFFER_BYTES, RUNTIME_DEFAULTS.maxSseBufferBytes),
     maxBodyBytes: parsePositiveInteger(env.CCDX_MAX_BODY_BYTES, RUNTIME_DEFAULTS.maxBodyBytes),
     maxDecodedBodyBytes: parsePositiveInteger(env.CCDX_MAX_DECODED_BODY_BYTES, RUNTIME_DEFAULTS.maxDecodedBodyBytes),
@@ -41,10 +57,10 @@ export function loadRuntimeConfig(env = process.env) {
       RUNTIME_DEFAULTS.maxUpstreamResponsesResponseBytes,
     ),
     maxQueuedRequests: parsePositiveInteger(env.CCDX_MAX_QUEUED_REQUESTS, RUNTIME_DEFAULTS.maxQueuedRequests),
-    requestQueueTimeoutMs: parsePositiveInteger(env.CCDX_REQUEST_QUEUE_TIMEOUT_MS, RUNTIME_DEFAULTS.requestQueueTimeoutMs),
+    requestQueueTimeoutMs: parseTimerMs(env.CCDX_REQUEST_QUEUE_TIMEOUT_MS, RUNTIME_DEFAULTS.requestQueueTimeoutMs),
     responseHistoryMaxBytes: parsePositiveInteger(env.CCDX_RESPONSE_HISTORY_MAX_BYTES, RUNTIME_DEFAULTS.responseHistoryMaxBytes),
     responseHistoryMaxEntries: parsePositiveInteger(env.CCDX_RESPONSE_HISTORY_MAX_ENTRIES, RUNTIME_DEFAULTS.responseHistoryMaxEntries),
-    tokenLockTimeoutMs: parsePositiveInteger(env.CCDX_TOKEN_LOCK_TIMEOUT_MS, RUNTIME_DEFAULTS.tokenLockTimeoutMs),
-    tokenLockStaleMs: parsePositiveInteger(env.CCDX_TOKEN_LOCK_STALE_MS, RUNTIME_DEFAULTS.tokenLockStaleMs),
+    tokenLockTimeoutMs: parseSafePositiveInteger(env.CCDX_TOKEN_LOCK_TIMEOUT_MS, RUNTIME_DEFAULTS.tokenLockTimeoutMs),
+    tokenLockStaleMs: parseSafePositiveInteger(env.CCDX_TOKEN_LOCK_STALE_MS, RUNTIME_DEFAULTS.tokenLockStaleMs),
   });
 }

package/src/token-counter-service.mjs

@@ -1,5 +1,6 @@
 import { Worker } from "node:worker_threads";
 import { anthropicTokenText } from "./anthropic.mjs";
+import { debugLog } from "./log.mjs";
 
 export const DEFAULT_TOKEN_COUNTER_TIMEOUT_MS = 120 * 1000;
 export const DEFAULT_TOKEN_COUNTER_MAX_QUEUED = 16;
@@ -8,6 +9,23 @@ function serviceError(message, statusCode) {
   return Object.assign(new Error(message), { statusCode });
 }
 
+const DIAGNOSTIC_PHASES = new Set(["create", "worker", "error", "exit", "postMessage"]);
+const DIAGNOSTIC_ERROR_NAMES = new Set(["Error", "TypeError", "RangeError", "SyntaxError", "WorkerExit"]);
+
+export function tokenCounterWorkerDiagnostic(phase, error) {
+  const safePhase = DIAGNOSTIC_PHASES.has(phase) ? phase : "unknown";
+  let rawName;
+  let rawCode;
+  try { rawName = error?.name; } catch {}
+  try { rawCode = error?.code; } catch {}
+  const safeName = DIAGNOSTIC_ERROR_NAMES.has(rawName) ? rawName : "Error";
+  if (typeof rawCode === "number") rawCode = String(rawCode);
+  const safeCode = typeof rawCode === "string" && /^(?:\d+|[A-Z][A-Z0-9_]{0,63})$/.test(rawCode)
+    ? rawCode
+    : "unknown";
+  return `Token counter worker failure: phase=${safePhase} name=${safeName} code=${safeCode}`;
+}
+
 function positiveInteger(value, fallback) {
   return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
 }
@@ -74,7 +92,8 @@ export function createTokenCounterService({
     if (!worker) {
       try {
         worker = workerFactory();
-      } catch {
+      } catch (error) {
+        debugLog(tokenCounterWorkerDiagnostic("create", error));
         const job = queue.shift();
         if (job) finish(job, job.reject, serviceError("Token counter worker failed", 500));
         queueMicrotask(pump);
@@ -85,6 +104,7 @@ export function createTokenCounterService({
         const job = active;
         active = null;
         if (message.error) {
+          debugLog(tokenCounterWorkerDiagnostic("worker", message.error));
           retireWorker();
           finish(job, job.reject, serviceError("Token counter worker failed", 500));
         } else {
@@ -92,14 +112,16 @@ export function createTokenCounterService({
         }
         pump();
       });
-      worker.on("error", () => {
+      worker.on("error", (error) => {
+        debugLog(tokenCounterWorkerDiagnostic("error", error));
         const job = active;
         active = null;
         retireWorker();
         if (job) finish(job, job.reject, serviceError("Token counter worker failed", 500));
         pump();
       });
-      worker.on("exit", () => {
+      worker.on("exit", (code) => {
+        if (active) debugLog(tokenCounterWorkerDiagnostic("exit", { name: "WorkerExit", code }));
         const job = active;
         active = null;
         worker = null;
@@ -114,7 +136,8 @@ export function createTokenCounterService({
     try {
       worker.postMessage({ id: job.id, text: job.text });
       job.text = null;
-    } catch {
+    } catch (error) {
+      debugLog(tokenCounterWorkerDiagnostic("postMessage", error));
       active = null;
       retireWorker();
       finish(job, job.reject, serviceError("Token counter worker failed", 500));

package/src/token-counter-worker.mjs

@@ -4,7 +4,13 @@ import { countTokenText } from "./anthropic.mjs";
 parentPort.on("message", async ({ id, text }) => {
   try {
     parentPort.postMessage({ id, result: await countTokenText(text) });
-  } catch {
-    parentPort.postMessage({ id, error: true });
+  } catch (error) {
+    parentPort.postMessage({
+      id,
+      error: {
+        name: typeof error?.name === "string" ? error.name : "Error",
+        code: typeof error?.code === "string" ? error.code : "unknown",
+      },
+    });
   }
 });

package/src/usage.mjs

@@ -4,11 +4,17 @@ import path from "node:path";
 import readline from "node:readline";
 import { cliOutputFormat, cliOutputWidth, formatResponsiveCliTable, terminalCell } from "./cli-table.mjs";
 import { parseByteLimit, rotateFileIfNeededSync, rotatedFilePath } from "./file-rotation.mjs";
+import { withFileLock } from "./lock.mjs";
 
 const DEFAULT_USAGE_PATH = path.join(os.homedir(), ".local", "share", "codex-copilot-dx", "usage.jsonl");
 const DEFAULT_USAGE_MAX_BYTES = 32 * 1024 * 1024;
+const USAGE_WRITE_LOCK_TIMEOUT_MS = 1_000;
+const USAGE_WRITE_LOCK_STALE_MS = 1_000;
+const USAGE_WRITE_LOCK_POLL_MS = 5;
+const USAGE_FLUSH_TIMEOUT_MS = 1_500;
 
-let writeQueue = Promise.resolve();
+const pendingWrites = [];
+let writeDrain = null;
 
 export function usageLogPath() {
   return process.env.CCDX_USAGE_PATH || DEFAULT_USAGE_PATH;
@@ -119,19 +125,63 @@ export function buildAnthropicUsageRecord({ surface = "messages", mode, model, r
   });
 }
 
+function takePendingWrites(filePath, maxBytes) {
+  const batch = [];
+  let retained = 0;
+  for (const entry of pendingWrites) {
+    if (entry.filePath === filePath && entry.maxBytes === maxBytes) batch.push(entry);
+    else pendingWrites[retained++] = entry;
+  }
+  pendingWrites.length = retained;
+  return batch;
+}
+
+async function writeUsageBatch(batch) {
+  const { filePath, maxBytes } = batch[0];
+  await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+  await withFileLock(`${path.resolve(filePath)}.lock`, async () => {
+    batch.push(...takePendingWrites(filePath, maxBytes));
+    for (const { line } of batch) {
+      rotateFileIfNeededSync(filePath, Buffer.byteLength(line), maxBytes);
+      await fs.promises.appendFile(filePath, line, { encoding: "utf8", mode: 0o600 });
+    }
+  }, {
+    timeoutMs: USAGE_WRITE_LOCK_TIMEOUT_MS,
+    staleMs: USAGE_WRITE_LOCK_STALE_MS,
+    pollMs: USAGE_WRITE_LOCK_POLL_MS,
+  });
+}
+
+function scheduleUsageWriteDrain() {
+  if (writeDrain) return;
+  writeDrain = Promise.resolve().then(async () => {
+    while (pendingWrites.length > 0) {
+      const first = pendingWrites.shift();
+      const batch = [first, ...takePendingWrites(first.filePath, first.maxBytes)];
+      try {
+        await writeUsageBatch(batch);
+      } catch (error) {
+        batch.push(...takePendingWrites(first.filePath, first.maxBytes));
+        console.error(`codex-copilot-dx usage log write failed: ${error.message}`);
+      } finally {
+        for (const entry of batch) entry.resolve();
+      }
+    }
+  }).finally(() => {
+    writeDrain = null;
+    if (pendingWrites.length > 0) scheduleUsageWriteDrain();
+  });
+}
+
 export function recordUsage(record) {
   if (!record || process.env.CCDX_DISABLE_USAGE === "1") return Promise.resolve();
   const filePath = usageLogPath();
   const line = `${JSON.stringify(record)}\n`;
-  writeQueue = writeQueue
-    .catch(() => {})
-    .then(async () => {
-      await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
-      rotateFileIfNeededSync(filePath, Buffer.byteLength(line), usageLogMaxBytes());
-      await fs.promises.appendFile(filePath, line, { encoding: "utf8", mode: 0o600 });
-    })
-    .catch((e) => console.error(`codex-copilot-dx usage log write failed: ${e.message}`));
-  return writeQueue;
+  const completed = new Promise((resolve) => {
+    pendingWrites.push({ filePath, line, maxBytes: usageLogMaxBytes(), resolve });
+  });
+  scheduleUsageWriteDrain();
+  return completed;
 }
 
 export function recordResponsesUsage(args) {
@@ -143,11 +193,28 @@ export function recordAnthropicUsage(args) {
 }
 
 export async function flushUsageWritesForTests() {
-  await writeQueue;
+  while (writeDrain || pendingWrites.length > 0) {
+    if (writeDrain) await writeDrain;
+    else scheduleUsageWriteDrain();
+  }
 }
 
-export async function flushUsageWrites() {
-  await writeQueue;
+export async function flushUsageWrites({
+  timeoutMs = USAGE_FLUSH_TIMEOUT_MS,
+  warn = console.error,
+} = {}) {
+  const timeout = Number.isFinite(timeoutMs) && timeoutMs >= 0
+    ? Math.floor(timeoutMs)
+    : USAGE_FLUSH_TIMEOUT_MS;
+  let timer;
+  const completed = await Promise.race([
+    flushUsageWritesForTests().then(() => true),
+    new Promise((resolve) => { timer = setTimeout(() => resolve(false), timeout); }),
+  ]);
+  if (timer) clearTimeout(timer);
+  if (!completed) {
+    try { warn(`codex-copilot-dx usage log flush timed out after ${timeout}ms`); } catch {}
+  }
 }
 
 async function* iterateUsageRecords(filePath, { warn = console.error } = {}) {