@bitkyc08/opencodex 2.7.8 → 2.7.9-preview.20260712

package/src/server/system-env.ts

@@ -0,0 +1,314 @@
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config";
+import { resolveAutoContext, type AutoContextMode } from "../claude/context-windows";
+import type { OcxConfig } from "../types";
+
+// ---------------------------------------------------------------------------
+// Shell-hook env file: written on inject, sourced by the shell hook in .zshrc.
+// This works for ALL new shells immediately, unlike launchctl setenv which only
+// reaches processes launched directly by launchd (not Terminal.app children).
+// ---------------------------------------------------------------------------
+
+export function getShellEnvFilePath(): string {
+  return join(getConfigDir(), "claude-env.sh");
+}
+
+function writeShellEnvFile(port: number, config: OcxConfig, modelEnv: Record<string, string> = {}, auto?: AutoContextMode): void {
+  const lines = [
+    `# Generated by opencodex — do not edit manually`,
+    `export ANTHROPIC_BASE_URL="http://127.0.0.1:${port}"`,
+    `export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`,
+  ];
+  if (config.apiKeys?.length) {
+    lines.push(`export ANTHROPIC_AUTH_TOKEN="${config.apiKeys[0].key.replace(/"/g, '\\"')}"`);
+  }
+  // New lever keys are CONDITIONAL exports (audit 139 R2#1): a value the user already
+  // exported in their shell wins even though launchctl knows nothing about it.
+  const conditional = (name: string, value: string) =>
+    `[ -z "\${${name}+x}" ] && export ${name}="${value.replace(/"/g, '\\"')}"`;
+  // Model slots (default + tiers + legacy small-fast) with [1m] applied (devlog 260712 B2).
+  if (modelEnv.ANTHROPIC_MODEL) {
+    lines.push(`export ANTHROPIC_MODEL="${modelEnv.ANTHROPIC_MODEL.replace(/"/g, '\\"')}"`);
+  } else if (config.claudeCode?.model) {
+    lines.push(`export ANTHROPIC_MODEL="${config.claudeCode.model}"`);
+  }
+  for (const [name, value] of Object.entries(modelEnv)) {
+    if (name === "ANTHROPIC_MODEL") continue;
+    lines.push(conditional(name, value));
+  }
+  const maxCtx = config.claudeCode?.maxContextTokens;
+  if (typeof maxCtx === "number" && Number.isFinite(maxCtx) && maxCtx > 0) {
+    lines.push(conditional("CLAUDE_CODE_MAX_CONTEXT_TOKENS", String(Math.floor(maxCtx))));
+    lines.push(conditional("DISABLE_COMPACT", "1"));
+  }
+  // Auto-context (devlog 260712 020): same contract as `ocx claude` / launchctl.
+  const autoShell = auto ?? resolveAutoContext(config.claudeCode);
+  if (autoShell.enabled) lines.push(conditional("CLAUDE_CODE_AUTO_COMPACT_WINDOW", String(autoShell.compactWindow)));
+  if (config.claudeCode?.alwaysEnableEffort === true) {
+    lines.push(conditional("CLAUDE_CODE_ALWAYS_ENABLE_EFFORT", "1"));
+  }
+  mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
+  writeFileSync(getShellEnvFilePath(), lines.join("\n") + "\n", { encoding: "utf8", mode: 0o600 });
+}
+
+function removeShellEnvFile(): void {
+  try { unlinkSync(getShellEnvFilePath()); } catch { /* already gone */ }
+}
+
+// ---------------------------------------------------------------------------
+// .zshrc hook auto-install: adds a one-liner that sources claude-env.sh.
+// Idempotent — skips if the hook line already exists.
+// ---------------------------------------------------------------------------
+
+const SHELL_HOOK_MARKER = "# opencodex claude-env hook";
+const SHELL_HOOK_LINE = `${SHELL_HOOK_MARKER}\n[ -f ~/.opencodex/claude-env.sh ] && source ~/.opencodex/claude-env.sh`;
+
+export function installShellHook(): { installed: boolean; reason?: string } {
+  if (process.platform !== "darwin") return { installed: false, reason: "not macOS" };
+  const home = process.env.HOME;
+  if (!home) return { installed: false, reason: "no HOME" };
+  const zshrcPath = join(home, ".zshrc");
+  try {
+    let content = "";
+    try { content = readFileSync(zshrcPath, "utf8"); } catch { /* file doesn't exist yet */ }
+    if (content.includes(SHELL_HOOK_MARKER)) return { installed: false, reason: "already installed" };
+    const addition = `\n${SHELL_HOOK_LINE}\n`;
+    writeFileSync(zshrcPath, content + addition, { encoding: "utf8", mode: 0o644 });
+    return { installed: true };
+  } catch (err) {
+    return { installed: false, reason: `write failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+export function uninstallShellHook(): { removed: boolean; reason?: string } {
+  if (process.platform !== "darwin") return { removed: false, reason: "not macOS" };
+  const home = process.env.HOME;
+  if (!home) return { removed: false, reason: "no HOME" };
+  const zshrcPath = join(home, ".zshrc");
+  try {
+    const content = readFileSync(zshrcPath, "utf8");
+    if (!content.includes(SHELL_HOOK_MARKER)) return { removed: false, reason: "not installed" };
+    // Remove the hook block (marker line + source line + surrounding newlines)
+    const cleaned = content.replace(/\n?# opencodex claude-env hook\n\[.*claude-env\.sh.*\n?/g, "\n");
+    writeFileSync(zshrcPath, cleaned, { encoding: "utf8", mode: 0o644 });
+    return { removed: true };
+  } catch {
+    return { removed: false, reason: "read/write failed" };
+  }
+}
+
+const SYSTEM_ENV_NAMES = [
+  "ANTHROPIC_BASE_URL",
+  "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY",
+  "ANTHROPIC_AUTH_TOKEN",
+] as const;
+
+interface SystemEnvTracking {
+  pid: number;
+  port: number;
+  injectedAt: string;
+  /** Keys that were actually set by injection (revert only unsets these). */
+  injectedKeys?: string[];
+}
+
+type SystemEnvResult = { injected: boolean; reason?: string };
+type RevertResult = { reverted: boolean; reason?: string };
+type CleanupResult = { cleaned: boolean; reason?: string };
+
+export function getSystemEnvTrackingPath(): string {
+  return join(getConfigDir(), "system-env-port");
+}
+
+export function launchctlGetenv(name: string): string | undefined {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) return undefined;
+  try {
+    const value = execSync(`launchctl getenv ${name}`, { encoding: "utf8" }).trim();
+    return value || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function readTracking(): SystemEnvTracking | undefined {
+  try {
+    const tracking = JSON.parse(readFileSync(getSystemEnvTrackingPath(), "utf8")) as Partial<SystemEnvTracking>;
+    if (!Number.isInteger(tracking.port) || typeof tracking.pid !== "number" || typeof tracking.injectedAt !== "string") {
+      return undefined;
+    }
+    return tracking as SystemEnvTracking;
+  } catch {
+    return undefined;
+  }
+}
+
+function shellArg(value: string): string {
+  return /^[A-Za-z0-9_./:-]+$/.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+function setLaunchctlEnv(name: string, value: string): void {
+  execSync(`launchctl setenv ${name} ${shellArg(value)}`);
+}
+
+function unsetLaunchctlEnv(name: string): void {
+  execSync(`launchctl unsetenv ${name}`);
+}
+
+function ownedBaseUrl(port: number): string {
+  return `http://127.0.0.1:${port}`;
+}
+
+/**
+ * In-process effective model-env (default + tier slots, [1m] applied) under the shared
+ * 3s bound (audit R4#3). Returns {} on timeout/failure so injection degrades safely.
+ */
+async function computeEffectiveModelEnv(config: OcxConfig, auto?: AutoContextMode): Promise<{ modelEnv: Record<string, string>; windows: Record<string, number> }> {
+  const { boundedContextWindows, buildClaudeContextWindows, effectiveModelEnv } = await import("../claude/context-windows");
+  const windows = await boundedContextWindows(async () => {
+    const { gatherRoutedModels, visibleNativeSlugs } = await import("../codex/catalog");
+    return buildClaudeContextWindows([...visibleNativeSlugs(config)], await gatherRoutedModels(config));
+  });
+  return { modelEnv: effectiveModelEnv(config.claudeCode, windows ?? {}, auto), windows: windows ?? {} };
+}
+
+export async function injectSystemEnv(port: number, config: OcxConfig): Promise<SystemEnvResult> {
+  if (process.platform !== "darwin") return { injected: false, reason: "not macOS" };
+  if (config.claudeCode?.enabled === false) return { injected: false, reason: "claude disabled" };
+
+  // Default OFF — only inject when explicitly enabled by the user.
+  if (config.claudeCode?.systemEnv !== true) return { injected: false, reason: "systemEnv disabled" };
+
+  await cleanStaleSystemEnv();
+
+  const currentBaseUrl = launchctlGetenv("ANTHROPIC_BASE_URL");
+  if (currentBaseUrl && !/^http:\/\/127\.0\.0\.1:\d+$/.test(currentBaseUrl)) {
+    return { injected: false, reason: "user has custom ANTHROPIC_BASE_URL" };
+  }
+  // After stale cleanup, if a tracking file still exists with a DIFFERENT port,
+  // another live instance owns the env — don't overwrite it.
+  const existingTracking = readTracking();
+  if (existingTracking && existingTracking.port !== port) {
+    return { injected: false, reason: `another instance owns env (port ${existingTracking.port})` };
+  }
+
+  setLaunchctlEnv("ANTHROPIC_BASE_URL", ownedBaseUrl(port));
+  setLaunchctlEnv("CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "1");
+  const injectedKeys = [
+    "ANTHROPIC_BASE_URL",
+    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY",
+  ];
+  if (config.apiKeys?.length) {
+    setLaunchctlEnv("ANTHROPIC_AUTH_TOKEN", config.apiKeys[0].key);
+    injectedKeys.push("ANTHROPIC_AUTH_TOKEN");
+  }
+  // Lever keys (devlog 136 B6): user-wins — skip any key the user already set in the
+  // launchd domain, and track ONLY the keys we actually injected so revert cannot
+  // delete a pre-existing user value (audit 139 #3).
+  const injectLever = (name: string, value: string) => {
+    if (launchctlGetenv(name) !== undefined) return;
+    setLaunchctlEnv(name, value);
+    injectedKeys.push(name);
+  };
+  // Model slots (default + tier defaults + legacy small-fast) with [1m] auto-marking
+  // (devlog 260712 B2, audit R2#3/R4#3): in-process context-window computation under
+  // the same 3s bound; on timeout the tier keys are simply not injected this run.
+  // Auto-context: a user-owned launchd value drives the marking predicate so the
+  // marker and threshold never separate (audit 021 #2); injectLever's user-wins
+  // check below keeps that value untouched.
+  const userAutoCompact = launchctlGetenv("CLAUDE_CODE_AUTO_COMPACT_WINDOW");
+  const auto = resolveAutoContext(config.claudeCode, userAutoCompact);
+  const { modelEnv, windows } = await computeEffectiveModelEnv(config, auto);
+  for (const [name, value] of Object.entries(modelEnv)) {
+    if (name === "ANTHROPIC_MODEL") continue; // legacy slot handled by shell file only (back-compat)
+    injectLever(name, value);
+  }
+  const maxCtx = config.claudeCode?.maxContextTokens;
+  if (typeof maxCtx === "number" && Number.isFinite(maxCtx) && maxCtx > 0) {
+    injectLever("CLAUDE_CODE_MAX_CONTEXT_TOKENS", String(Math.floor(maxCtx)));
+    injectLever("DISABLE_COMPACT", "1");
+  }
+  // Auto-context (devlog 260712 020): user-wins lever, inert when maxContextTokens set.
+  if (auto.enabled) injectLever("CLAUDE_CODE_AUTO_COMPACT_WINDOW", String(auto.compactWindow));
+  if (config.claudeCode?.alwaysEnableEffort === true) {
+    injectLever("CLAUDE_CODE_ALWAYS_ENABLE_EFFORT", "1");
+  }
+
+  // Shell-hook env file: works for new shells in already-running Terminal.app.
+  writeShellEnvFile(port, config, modelEnv, auto);
+
+  // Gateway-model cache pre-write (devlog 030): plain `claude` sessions read the
+  // picker list from ~/.claude/cache/gateway-models.json and cannot refresh it
+  // without a token — keep it in sync with this proxy's /v1/models. Best-effort.
+  try {
+    const { refreshGatewayModelCacheFromProxy } = await import("../claude/gateway-cache");
+    await refreshGatewayModelCacheFromProxy(port);
+  } catch { /* best-effort */ }
+
+  // Roster agent definitions (devlog 070): same launch-time sync for plain `claude`.
+  // Reuses the window map computed above (audit 071 #5 — no second acquisition).
+  try {
+    const { injectClaudeAgentDefs } = await import("../claude/agents-inject");
+    injectClaudeAgentDefs(config, windows);
+  } catch { /* best-effort */ }
+
+  mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
+  writeFileSync(getSystemEnvTrackingPath(), JSON.stringify({
+    pid: process.pid,
+    port,
+    injectedAt: new Date().toISOString(),
+    injectedKeys,
+  }), { encoding: "utf8", mode: 0o600 });
+
+  return { injected: true };
+}
+
+export function revertSystemEnv(): RevertResult {
+  if (process.platform !== "darwin") return { reverted: false, reason: "not macOS" };
+
+  const tracking = readTracking();
+  if (!tracking) return { reverted: false, reason: "no tracking file" };
+
+  try {
+    if (launchctlGetenv("ANTHROPIC_BASE_URL") !== ownedBaseUrl(tracking.port)) {
+      return { reverted: false, reason: "ownership mismatch" };
+    }
+
+    // Only unset keys that were actually injected (preserves pre-existing user tokens).
+    const keysToUnset = tracking.injectedKeys ?? SYSTEM_ENV_NAMES as unknown as string[];
+    for (const name of keysToUnset) {
+      try {
+        unsetLaunchctlEnv(name);
+      } catch {
+        // Continue removing the remaining variables during shutdown.
+      }
+    }
+    removeShellEnvFile();
+    try {
+      unlinkSync(getSystemEnvTrackingPath());
+    } catch {
+      // The environment was reverted even if the tracking file disappeared concurrently.
+    }
+    return { reverted: true };
+  } catch {
+    return { reverted: false, reason: "revert failed" };
+  }
+}
+
+export async function cleanStaleSystemEnv(): Promise<CleanupResult> {
+  const tracking = readTracking();
+  if (!tracking) return { cleaned: false, reason: "no tracking file" };
+
+  try {
+    const response = await fetch(`${ownedBaseUrl(tracking.port)}/healthz`, {
+      signal: AbortSignal.timeout(1_000),
+    });
+    if (response.ok) return { cleaned: false, reason: "proxy still alive" };
+  } catch {
+    // A failed or timed-out health check means the tracked proxy is stale.
+  }
+
+  const reverted = revertSystemEnv();
+  if (!reverted.reverted) return { cleaned: false, reason: reverted.reason };
+  return { cleaned: true };
+}

package/src/types.ts

@@ -224,6 +224,15 @@ export interface OcxUrlCitation {
   title?: string;
 }
 
+/**
+ * Canonical usage convention (devlog/260711_claude_inbound/070):
+ * - `inputTokens` is the TOTAL prompt size, INCLUDING cache reads and cache writes
+ *   (OpenAI Responses convention). Anthropic parse sites normalize into this shape.
+ * - `cachedInputTokens` is cache READ tokens only (a subset of `inputTokens`).
+ * - `cacheReadInputTokens`/`cacheCreationInputTokens` carry the read/write split when
+ *   the provider reports both; reads mirror `cachedInputTokens`.
+ * - `totalTokens` = inputTokens + outputTokens. Never re-add cache detail on top.
+ */
 export interface OcxUsage {
   inputTokens: number;
   outputTokens: number;
@@ -235,10 +244,90 @@ export interface OcxUsage {
   estimated?: boolean;
 }
 
+/**
+ * Claude Code inbound settings (devlog/260711_claude_inbound). Consumed by the
+ * /v1/messages surface, the `ocx claude` launcher, and the GUI Claude page.
+ */
+export interface OcxClaudeCodeConfig {
+  /** Kill switch for the /v1/messages inbound (GUI "Claude ON" toggle). Default: enabled. */
+  enabled?: boolean;
+  /**
+   * Verbatim passthrough of unmapped claude/anthropic models to api.anthropic.com with the
+   * caller's own sk-ant-* credential (Claude Code subscription OAuth). Default: enabled.
+   */
+  nativePassthrough?: boolean;
+  /** Upstream for the native passthrough (tests/enterprise gateways). Default: https://api.anthropic.com */
+  anthropicBaseUrl?: string;
+  /** Default model slot injected as ANTHROPIC_MODEL by `ocx claude`. */
+  model?: string;
+  /** Haiku/small-fast slot injected as ANTHROPIC_DEFAULT_HAIKU_MODEL (+ legacy SMALL_FAST). */
+  smallFastModel?: string;
+  /** Inbound model id remaps: exact id first, then date-stripped (`-\d{8}$`). */
+  modelMap?: Record<string, string>;
+  /**
+   * Inject ANTHROPIC_BASE_URL etc. into the macOS user domain via `launchctl setenv`
+   * so plain `claude` commands route through the proxy without `ocx claude`. Reverted
+   * on stop/shutdown. Default: true when `enabled` is not false. macOS only.
+   */
+  systemEnv?: boolean;
+  /**
+   * Context-window override for Claude Code/Desktop clients (devlog 136 B6):
+   * injected as CLAUDE_CODE_MAX_CONTEXT_TOKENS + DISABLE_COMPACT=1 (the official
+   * env pair — recognized claude-shaped ids need both). WARNING: DISABLE_COMPACT
+   * turns off auto-compaction. Unset = client defaults.
+   */
+  maxContextTokens?: number;
+  /**
+   * Opt-in CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1 injection. Default OFF: opus-shaped
+   * aliases already carry output_config.effort on the wire (devlog 136 실측), and
+   * forcing effort on every request can leak reasoning params to non-reasoning routes.
+   */
+  alwaysEnableEffort?: boolean;
+  /**
+   * Subagent tier slots (devlog 260712 B2): injected as ANTHROPIC_DEFAULT_*_MODEL so
+   * Claude Code's Agent-tool aliases (opus/sonnet/haiku/fable + parent-inherit) route
+   * to proxy models. haiku falls back to smallFastModel (one effective value feeds
+   * both ANTHROPIC_DEFAULT_HAIKU_MODEL and legacy ANTHROPIC_SMALL_FAST_MODEL).
+   */
+  tierModels?: { opus?: string; sonnet?: string; haiku?: string; fable?: string };
+  /**
+   * Auto-context (devlog 260712 020): when not false, routed/native models whose
+   * authoritative window is > 200k AND >= the compact window get the [1m] marker
+   * (Claude Code then accounts 1M) and CLAUDE_CODE_AUTO_COMPACT_WINDOW is injected
+   * so compaction fires at the real budget. 2.1.207 semantics (binary-verified):
+   * effective compact window = min(believed window, env) — one global env behaves
+   * like a per-model floor. Default: enabled. Inert while maxContextTokens is set
+   * (the legacy DISABLE_COMPACT pair takes rule-1 precedence in the CLI).
+   */
+  autoContext?: boolean;
+  /** Compact-window tokens for auto-context. Default 350_000. */
+  autoCompactWindow?: number;
+  /**
+   * Bundled-skill content elision for ROUTED (non-Anthropic) models (devlog 260712
+   * 060): Skill-tool results whose skill name matches an entry here are replaced
+   * with a short stub in the anthropic->responses translation. Third-party models
+   * are not trained on these Anthropic doc bundles, and claude-api alone injects
+   * ~136k tokens (GitHub anthropics/claude-code#74473). Native Anthropic
+   * passthrough never goes through the translation, so Claude models keep the
+   * full content. Default: ["claude-api"]. Empty array = explicitly off.
+   */
+  blockedSkills?: string[];
+  /**
+   * Sync the featured subagent roster (config.subagentModels + main model) into
+   * ~/.claude/agents/ocx-*.md custom agent definitions at launch (devlog 260712
+   * 070) so any routed model is dispatchable as a subagent_type — the Agent
+   * tool's model argument is a hard 4-alias enum, but definition frontmatter is
+   * free. Only ocx-*.md files are owned/pruned. Default: enabled.
+   */
+  injectAgents?: boolean;
+}
+
 export interface OcxConfig {
   port: number;
   providers: Record<string, OcxProviderConfig>;
   defaultProvider: string;
+  /** Claude Code inbound + launcher settings. */
+  claudeCode?: OcxClaudeCodeConfig;
   /**
    * Up to 5 routed model ids ("<provider>/<model>") to feature FIRST in the injected Codex catalog.
    * Codex's spawn_agent only advertises the first 5 routed models, so this picks which 5 appear.
@@ -251,6 +340,12 @@ export interface OcxConfig {
    * the Codex ladder (src/reasoning-effort.ts CODEX_REASONING_LEVELS) at the API boundary.
    */
   injectionEffort?: string;
+  /**
+   * When true, OpenAI-routed requests include `service_tier: "priority"` (fast inference).
+   * When false, service_tier is stripped so requests use default speed.
+   * Undefined = passthrough (don't modify what the client sends).
+   */
+  fastMode?: boolean;
   /**
    * Custom override for the injected multi-agent guidance body (the text inside the
    * <multi_agent_mode> tags). When set, it replaces the built-in prompt on whichever
@@ -551,6 +646,19 @@ export interface OcxProviderConfig {
    * controlled by their own opt-in config.
    */
   unsafeAllowNativeLocalExec?: boolean;
+  /**
+   * Cursor adapter only: native local exec policy mode (exec-policy.ts).
+   * "off" (default) rejects all server-driven local exec; "on" always allows
+   * (same as legacy unsafeAllowNativeLocalExec:true); "codex-sandbox" allows only
+   * when the request's instructions/developer text declares the Codex
+   * danger-full-access sandbox. NOTE: the declaration is CALLER-CONTROLLED prose —
+   * the proxy cannot verify it. Enable "codex-sandbox" only where every client
+   * that can reach the data plane is trusted: the default loopback bind admits
+   * ANY process on this host without auth (including other local users on
+   * multi-user machines), and isAllowedRequestOrigin blocks non-loopback
+   * browser origins by default but not loopback-origin or origin-less callers.
+   */
+  nativeLocalExec?: "off" | "codex-sandbox" | "on";
 }
 
 export interface CodexAccount {

package/src/usage/log.ts

@@ -27,8 +27,14 @@ export function usageTotalTokens(usage: OcxUsage | undefined): number | undefine
   return usageDisplayTotalTokens(usage);
 }
 
-function isEstimatedUsageProvider(provider: string): boolean {
-  return provider === "kiro" || provider.startsWith("kiro-") || provider === "cursor";
+/**
+ * Providers whose adapters can only estimate usage (no authoritative per-turn frame).
+ * Callers should pass the route ADAPTER when available; the name-prefix match is a
+ * fallback for paths that only know the configured provider name (e.g. "cursor-mykey").
+ */
+function isEstimatedUsageProvider(providerOrAdapter: string): boolean {
+  return providerOrAdapter === "kiro" || providerOrAdapter.startsWith("kiro-")
+    || providerOrAdapter === "cursor" || providerOrAdapter.startsWith("cursor-");
 }
 
 export function usageForFinalLog(provider: string, usage: OcxUsage | undefined): OcxUsage | undefined {

package/src/usage/summary.ts

@@ -14,6 +14,8 @@ export interface UsageSummaryTotals {
   inputTokens: number;
   outputTokens: number;
   cachedInputTokens: number;
+  cacheReadInputTokens: number;
+  cacheCreationInputTokens: number;
   reasoningOutputTokens: number;
   totalTokens: number;
   coverageRatio: number;
@@ -108,6 +110,8 @@ function blankTotals(): UsageSummaryTotals {
     inputTokens: 0,
     outputTokens: 0,
     cachedInputTokens: 0,
+    cacheReadInputTokens: 0,
+    cacheCreationInputTokens: 0,
     reasoningOutputTokens: 0,
     totalTokens: 0,
     coverageRatio: 0,
@@ -131,7 +135,20 @@ function addTokens(totals: UsageSummaryTotals, entry: PersistedUsageEntry): void
   if (!entry.usage) return;
   totals.inputTokens += entry.usage.inputTokens;
   totals.outputTokens += entry.usage.outputTokens;
-  if (typeof entry.usage.cachedInputTokens === "number") totals.cachedInputTokens += entry.usage.cachedInputTokens;
+  // Prefer the explicit read/write split; legacy claude-route rows stored read+write
+  // combined in cachedInputTokens with only the creation split present (devlog 070),
+  // so recover reads by subtracting the write share for those rows.
+  const creation = entry.usage.cacheCreationInputTokens;
+  const read = typeof entry.usage.cacheReadInputTokens === "number"
+    ? entry.usage.cacheReadInputTokens
+    : typeof entry.usage.cachedInputTokens === "number" && typeof creation === "number"
+      ? Math.max(0, entry.usage.cachedInputTokens - creation)
+      : entry.usage.cachedInputTokens;
+  if (typeof read === "number") {
+    totals.cachedInputTokens += read;
+    totals.cacheReadInputTokens += read;
+  }
+  if (typeof creation === "number") totals.cacheCreationInputTokens += creation;
   if (typeof entry.usage.reasoningOutputTokens === "number") totals.reasoningOutputTokens += entry.usage.reasoningOutputTokens;
   totals.totalTokens += usageDisplayTotalTokens(entry.usage, entry.totalTokens) ?? 0;
 }

package/src/usage/totals.ts

@@ -1,25 +1,14 @@
 import type { OcxUsage } from "../types";
 
-function cacheDetailTokens(usage: OcxUsage): number | undefined {
-  const hasRead = typeof usage.cacheReadInputTokens === "number";
-  const hasCreate = typeof usage.cacheCreationInputTokens === "number";
-  if (!hasRead && !hasCreate) return undefined;
-  return (usage.cacheReadInputTokens ?? 0) + (usage.cacheCreationInputTokens ?? 0);
-}
-
-export function usageInputTokensWithCacheDetail(usage: OcxUsage): number {
-  const cacheDetailTotal = cacheDetailTokens(usage);
-  return usage.inputTokens + (cacheDetailTotal ?? 0);
-}
-
+/**
+ * Canonical display total (devlog 070): `inputTokens` is already INCLUSIVE of cache
+ * read/write, so the total is simply input+output. Cache detail is never re-added —
+ * that was the 2x inflation bug on cache-heavy Claude rows. `Math.max` keeps legacy
+ * persisted rows (pre-070 exclusive input) honest via their stored explicit total.
+ */
 export function usageDisplayTotalTokens(usage: OcxUsage | undefined, storedTotal?: number): number | undefined {
   if (!usage) return storedTotal;
   const baseTotal = usage.inputTokens + usage.outputTokens;
   const explicitTotal = usage.totalTokens ?? storedTotal;
-  const cacheDetailTotal = cacheDetailTokens(usage);
-  if (cacheDetailTotal !== undefined) {
-    const detailedTotal = baseTotal + cacheDetailTotal;
-    return typeof explicitTotal === "number" ? Math.max(explicitTotal, detailedTotal) : detailedTotal;
-  }
-  return explicitTotal ?? baseTotal;
+  return typeof explicitTotal === "number" ? Math.max(explicitTotal, baseTotal) : baseTotal;
 }