tokentracker-cli 0.88.6 → 0.88.8

package/src/commands/status.js

@@ -62,6 +62,8 @@ const {
   piAgentDirCollidesWithOmp,
   resolveCraftSessionFiles,
   resolveCraftConfigDir,
+  resolveReasonixHome,
+  resolveReasonixTelemetryFiles,
   resolveKilocodeTaskFiles,
   resolveRoocodeTaskFiles,
   resolveZedDbPath,
@@ -72,6 +74,8 @@ const {
   resolveGooseDbPath,
   listDroidSettingsFiles,
   resolveDroidSessionsDir,
+  resolveDshHome,
+  resolveDshSessionFiles,
   resolveTraeStoragePath,
   readTraeEntitlementFromStorage,
   resolveGrokBuildSessions,
@@ -85,7 +89,7 @@ const {
 } = require("../lib/rollout");
 const wsl = require("../lib/wsl-probe");
 const { getWslMode, isInvalidWslMode, shouldProbeWsl, discoverWslHome } = wsl;
-const { resolveInstallPaths } = require("../lib/install-resolver");
+const { resolveInstallPaths, resolveZcodeNativeDbPath } = require("../lib/install-resolver");
 const { probeGrokHookState, resolveGrokHome } = require("../lib/grok-hook");
 const { probeOmpHookState } = require("../lib/omp-hook");
 
@@ -428,6 +432,11 @@ async function cmdStatus(argv = []) {
   const craftInstalled = Boolean(craftConfigDir && fssync.existsSync(craftConfigDir));
   const craftFiles = craftInstalled ? resolveCraftSessionFiles(process.env) : [];
 
+  // Reasonix — passive scan of content-free cumulative telemetry sidecars.
+  const reasonixHome = resolveReasonixHome(process.env);
+  const reasonixInstalled = Boolean(reasonixHome && fssync.existsSync(reasonixHome));
+  const reasonixFiles = reasonixInstalled ? resolveReasonixTelemetryFiles(process.env) : [];
+
   // Kilo CLI (kilo.ai @kilocode/plugin) — passive scan of kilo.db.
   const xdgDataHome = process.env.XDG_DATA_HOME || path.join(home, ".local", "share");
   const kiloHome = process.env.KILO_HOME || path.join(xdgDataHome, "kilo");
@@ -456,10 +465,7 @@ async function cmdStatus(argv = []) {
   const mimoDbPath = mimoActive.join(" | ");
 
   // ZCode (Z.ai's coding agent — OpenCode-fork SQLite) — passive scan of db.sqlite.
-  const zcodeHome = process.env.ZCODE_HOME || path.join(home, ".zcode");
-  const zcodeNativeValue = process.platform === "win32" && typeof process.env.APPDATA === "string"
-    ? path.join(process.env.APPDATA.trim(), ".zcode", "cli", "db", "db.sqlite")
-    : path.join(zcodeHome, "cli", "db", "db.sqlite");
+  const zcodeNativeValue = resolveZcodeNativeDbPath({ home });
   const wslZcodeDir = process.platform === "win32" && wsl.shouldProbeWsl(process.env)
     ? wsl.discoverWslHome(".zcode")
     : null;
@@ -613,6 +619,10 @@ async function cmdStatus(argv = []) {
   const droidSessionsDir = resolveDroidSessionsDir(process.env);
   const droidSettingsFiles = listDroidSettingsFiles(process.env);
   const droidInstalled = droidSettingsFiles.length > 0;
+  const dshHome = resolveDshHome(process.env);
+  const dshSessionsDir = path.join(dshHome, "sessions");
+  const dshSessionFiles = await resolveDshSessionFiles(process.env);
+  const dshInstalled = dshSessionFiles.length > 0;
 
   // Trae SOLO (ByteDance AI IDE) — passive entitlement snapshot reader.
   const traeStoragePath = resolveTraeStoragePath(process.env);
@@ -866,6 +876,9 @@ async function cmdStatus(argv = []) {
         craft: craftInstalled
           ? { installed: true, files: craftFiles.length }
           : { installed: false },
+        reasonix: reasonixInstalled
+          ? { installed: true, files: reasonixFiles.length }
+          : { installed: false },
         anythingllm: anythingllmInstalled
           ? { installed: true, detail: anythingllmDbPath }
           : { installed: false },
@@ -900,6 +913,9 @@ async function cmdStatus(argv = []) {
         droid: droidInstalled
           ? { installed: true, files: droidSettingsFiles.length, detail: droidSessionsDir }
           : { installed: false },
+        dsh: dshInstalled
+          ? { installed: true, files: dshSessionFiles.length, detail: dshSessionsDir }
+          : { installed: false },
         trae: traeInstalled
           ? {
               installed: true,
@@ -1001,6 +1017,9 @@ async function cmdStatus(argv = []) {
       craftInstalled
         ? `- Craft Agents: passive reader (${craftFiles.length} session jsonl file${craftFiles.length !== 1 ? "s" : ""} found)`
         : null,
+      reasonixInstalled
+        ? `- Reasonix: passive reader (${reasonixFiles.length} telemetry file${reasonixFiles.length !== 1 ? "s" : ""} found)`
+        : null,
       anythingllmInstalled
         ? `- AnythingLLM Desktop: passive reader (${anythingllmDbPath})`
         : null,
@@ -1059,6 +1078,9 @@ async function cmdStatus(argv = []) {
       droidInstalled
         ? `- Droid (Factory): passive reader (${droidSettingsFiles.length} session${droidSettingsFiles.length !== 1 ? "s" : ""} in ${droidSessionsDir}, cumulative-delta)`
         : null,
+      dshInstalled
+        ? `- DeepSeek Harness: passive reader (${dshSessionFiles.length} session${dshSessionFiles.length !== 1 ? "s" : ""} in ${dshSessionsDir})`
+        : null,
       traeInstalled
         // Deliberately NOT "passive reader": every other line with that wording
         // means tokens are being counted. Trae encrypts its session transcripts

package/src/commands/sync.js

@@ -5,7 +5,7 @@ const fssync = require("node:fs");
 const cp = require("node:child_process");
 const readline = require("node:readline");
 
-const { resolveInstallPaths, ensureFlatCursor } = require("../lib/install-resolver");
+const { resolveInstallPaths, resolveZcodeNativeDbPath, ensureFlatCursor } = require("../lib/install-resolver");
 const { multiInstallParse, mergeBothFileSources } = require("../lib/multi-install-parser");
 const wsl = require("../lib/wsl-probe");
 const {
@@ -80,6 +80,8 @@ const {
   piAgentDirCollidesWithOmp,
   resolveCraftSessionFiles,
   parseCraftIncremental,
+  resolveReasonixTelemetryFiles,
+  parseReasonixIncremental,
   resolveGrokBuildSessions,
   parseGrokBuildIncremental,
   listAntigravityTranscripts,
@@ -106,6 +108,8 @@ const {
   parseDroidIncremental,
   droidSessionIdFromPath,
   resolveDroidModel,
+  resolveDshSessionFiles,
+  parseDshIncremental,
   bucketKey,
   toUtcHalfHourStart,
   totalsKey,
@@ -244,8 +248,10 @@ const CODEX_COLD_SCAN_AUDIT_MAX_SYNCS = 288;
 // one-time repair purges all source=mimo data from the local queues + cursor
 // state so the next sync (providerID-filtered reader) rebuilds it correctly.
 const MIMO_PROVIDER_REPAIR_KEY = "mimoClaudeMislabelRepair_2026_06";
+const DSH_LEGACY_SOURCE_MIGRATION_KEY = "deepseekHarnessSourceMigration_2026_08";
 const AUTO_SYNC_SOURCE_ALIASES = new Map([
   ["code", "every-code"],
+  ["deepseek", "dsh"],
   ["everycode", "every-code"],
   ["kilo", "kilo-cli"],
   ["kilo-code", "kilocode"],
@@ -263,6 +269,7 @@ const AUTO_SYNC_SOURCES = new Set([
   "craft",
   "cursor",
   "droid",
+  "dsh",
   "every-code",
   "gemini",
   "goose",
@@ -280,6 +287,7 @@ const AUTO_SYNC_SOURCES = new Set([
   "pi",
   "qoder",
   "qoder-cn",
+  "reasonix",
   "roocode",
   "workbuddy",
   "zcode",
@@ -289,6 +297,7 @@ const BACKGROUND_AUTO_SYNC_SOURCES = new Set([
   // Keep unscoped native 5-minute syncs bounded to dated local session trees.
   "codex",
   "every-code",
+  "reasonix",
 ]);
 
 function warnProviderParseFailure(label, err, opts) {
@@ -576,7 +585,6 @@ async function cmdSync(argv, context = {}) {
     const xdgDataHome = process.env.XDG_DATA_HOME || path.join(home, ".local", "share");
     const kiloHome = process.env.KILO_HOME || path.join(xdgDataHome, "kilo");
     const mimoHome = process.env.MIMO_HOME || path.join(xdgDataHome, "mimocode");
-    const zcodeHome = process.env.ZCODE_HOME || path.join(home, ".zcode");
 
     // OpenClaw session plugin integration: lifecycle hooks request an
     // OpenClaw-only auto sync so unrelated providers do not get walked.
@@ -1369,9 +1377,7 @@ async function cmdSync(argv, context = {}) {
     // ── ZCode (Z.ai's coding agent — OpenCode-fork SQLite) ──
     let zcodeResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
     if (sourceAllowed("zcode")) {
-      const zcodeNativeValue = process.platform === "win32" && typeof process.env.APPDATA === "string"
-        ? path.join(process.env.APPDATA.trim(), ".zcode", "cli", "db", "db.sqlite")
-        : path.join(zcodeHome, "cli", "db", "db.sqlite");
+      const zcodeNativeValue = resolveZcodeNativeDbPath({ home });
       const wslZcodeDir = process.platform === "win32" && wsl.shouldProbeWsl(process.env)
         ? wsl.discoverWslHome(".zcode")
         : null;
@@ -1398,6 +1404,32 @@ async function cmdSync(argv, context = {}) {
       };
     }
 
+    // ── DeepSeek Harness — passive read of ~/.dsh/sessions session logs ──
+    let dshResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+    if (sourceAllowed("dsh")) {
+      await migrateLegacyDeepseekHarnessSource({ cursors, queuePath, queueStatePath });
+      const dshSessionFiles = await resolveDshSessionFiles(process.env);
+      if (dshSessionFiles.length > 0) {
+        if (progress?.enabled) {
+          progress.start(
+            `Parsing DeepSeek Harness ${renderBar(0)} 0/${formatNumber(
+              dshSessionFiles.length,
+            )} sessions | buckets 0`,
+          );
+        }
+        try {
+          dshResult = await parseDshIncremental({
+            sessionFiles: dshSessionFiles,
+            cursors,
+            queuePath,
+            onProgress: makeProviderProgress("DeepSeek Harness"),
+          });
+        } catch (err) {
+          warnProviderParseFailure("DeepSeek Harness", err, opts);
+        }
+      }
+    }
+
     // ── AnythingLLM Desktop (workspace_chats.response.metrics) ──
     let anythingllmResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
     if (sourceAllowed("anythingllm")) {
@@ -2075,6 +2107,25 @@ async function cmdSync(argv, context = {}) {
       }
     }
 
+    // Reasonix — content-free cumulative telemetry sidecars only.
+    let reasonixResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+    const reasonixFiles = sourceAllowed("reasonix")
+      ? mergeBothFileSources({ resolveFiles: resolveReasonixTelemetryFiles, env: process.env })
+      : [];
+    if (reasonixFiles.length > 0) {
+      try {
+        reasonixResult = await parseReasonixIncremental({
+          telemetryFiles: reasonixFiles,
+          cursors,
+          queuePath,
+          env: process.env,
+          onProgress: makeProviderProgress("Reasonix"),
+        });
+      } catch (err) {
+        warnProviderParseFailure("Reasonix", err, opts);
+      }
+    }
+
     // ── Grok Build (xAI) ──
     let grokResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
     // Full passive scan of all Grok sessions (historical + any not covered by hook)
@@ -2513,6 +2564,7 @@ async function cmdSync(argv, context = {}) {
       ompResult.recordsProcessed +
       piResult.recordsProcessed +
       craftResult.recordsProcessed +
+      reasonixResult.recordsProcessed +
       grokResult.recordsProcessed +
       copilotResult.recordsProcessed +
       anythingllmResult.recordsProcessed +
@@ -2523,6 +2575,7 @@ async function cmdSync(argv, context = {}) {
       roocodeResult.recordsProcessed +
       zedResult.recordsProcessed +
       gooseResult.recordsProcessed +
+      dshResult.recordsProcessed +
       droidResult.recordsProcessed;
     const totalBuckets =
       parseResult.bucketsQueued +
@@ -2545,6 +2598,7 @@ async function cmdSync(argv, context = {}) {
       ompResult.bucketsQueued +
       piResult.bucketsQueued +
       craftResult.bucketsQueued +
+      reasonixResult.bucketsQueued +
       grokResult.bucketsQueued +
       copilotResult.bucketsQueued +
       anythingllmResult.bucketsQueued +
@@ -2555,6 +2609,7 @@ async function cmdSync(argv, context = {}) {
       roocodeResult.bucketsQueued +
       zedResult.bucketsQueued +
       gooseResult.bucketsQueued +
+      dshResult.bucketsQueued +
       droidResult.bucketsQueued;
     const skipNoOpCursorCommit =
       opts.auto &&
@@ -2888,6 +2943,8 @@ module.exports = {
   repairCodebuddyLogJsonlOverlap,
   repairWorkbuddyContextUsage,
   WORKBUDDY_CONTEXT_USAGE_REPAIR_KEY,
+  migrateLegacyDeepseekHarnessSource,
+  DSH_LEGACY_SOURCE_MIGRATION_KEY,
   repairCodexRescanInflation,
   repairCodexForkReplayInflation,
   repairCodexInterleavedUsageInflation,
@@ -2912,6 +2969,121 @@ module.exports = {
   CLOUD_CONVERSATIONS_BACKFILL_KEY,
 };
 
+// The pre-merge Harness prototype briefly emitted source="deepseek" before
+// settling on the official CLI id, source="dsh". Relabel the local history,
+// append explicit zero rows for every old cloud key, and replay from offset 0.
+// That preserves the latest canonical totals while making remote whole-row
+// upserts remove the stale alias instead of displaying both sources or summing
+// the same session twice.
+async function migrateLegacyDeepseekHarnessSource({ cursors, queuePath, queueStatePath } = {}) {
+  if (!cursors || typeof cursors !== "object") return false;
+  const migrations = (cursors.migrations ||= {});
+  if (migrations[DSH_LEGACY_SOURCE_MIGRATION_KEY]) return false;
+
+  let raw = "";
+  try {
+    raw = await fs.readFile(queuePath, "utf8");
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+
+  const output = [];
+  const legacyKeys = new Map();
+  const latestMigratedRows = new Map();
+  const latestExplicitCanonicalRows = new Map();
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch (_error) {
+      output.push(line);
+      continue;
+    }
+
+    const isLegacy =
+      row?.source === "deepseek" &&
+      typeof row.model === "string" &&
+      typeof row.hour_start === "string";
+    if (isLegacy) {
+      const key = `${row.model}|${row.hour_start}`;
+      legacyKeys.set(key, { model: row.model, hour_start: row.hour_start });
+      row = {
+        ...row,
+        source: "dsh",
+        billable_total_tokens: row.billable_total_tokens ?? row.total_tokens,
+      };
+    }
+    const serialized = JSON.stringify(row);
+    output.push(serialized);
+    if (row?.source === "dsh" && typeof row.model === "string" && typeof row.hour_start === "string") {
+      const key = `${row.model}|${row.hour_start}`;
+      if (isLegacy) latestMigratedRows.set(key, serialized);
+      else latestExplicitCanonicalRows.set(key, serialized);
+    }
+  }
+
+  if (legacyKeys.size === 0) {
+    migrations[DSH_LEGACY_SOURCE_MIGRATION_KEY] = {
+      status: "noop",
+      appliedAt: new Date().toISOString(),
+      reason: "no-legacy-deepseek-rows",
+    };
+    return false;
+  }
+
+  // Re-append the last canonical row for each affected key so local readers'
+  // last-row-wins contract remains correct even when an old alias line was
+  // physically later than an already-emitted dsh row.
+  for (const key of legacyKeys.keys()) {
+    const canonical = latestExplicitCanonicalRows.get(key) || latestMigratedRows.get(key);
+    if (canonical) output.push(canonical);
+  }
+  for (const { model, hour_start } of legacyKeys.values()) {
+    output.push(JSON.stringify({
+      source: "deepseek",
+      model,
+      hour_start,
+      input_tokens: 0,
+      cached_input_tokens: 0,
+      cache_creation_input_tokens: 0,
+      output_tokens: 0,
+      reasoning_output_tokens: 0,
+      total_tokens: 0,
+      billable_total_tokens: 0,
+      conversation_count: 0,
+    }));
+  }
+
+  await ensureDir(path.dirname(queuePath));
+  const tmpPath = `${queuePath}.tmp.${process.pid}.${Date.now()}`;
+  await fs.writeFile(tmpPath, `${output.join("\n")}\n`, "utf8");
+  await fs.rename(tmpPath, queuePath);
+
+  if (typeof queueStatePath === "string" && queueStatePath) {
+    let state = {};
+    try {
+      state = JSON.parse(await fs.readFile(queueStatePath, "utf8"));
+      if (!state || typeof state !== "object") state = {};
+    } catch (_error) {
+      state = {};
+    }
+    state.offset = 0;
+    state.updatedAt = new Date().toISOString();
+    state.note = "reset_after_deepseek_harness_source_migration_2026_08";
+    await ensureDir(path.dirname(queueStatePath));
+    await fs.writeFile(queueStatePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+  }
+
+  migrations[DSH_LEGACY_SOURCE_MIGRATION_KEY] = {
+    status: "applied",
+    appliedAt: new Date().toISOString(),
+    migratedBuckets: legacyKeys.size,
+    retractedBuckets: legacyKeys.size,
+  };
+  return true;
+}
+
 function normalizeString(value) {
   if (typeof value !== "string") return null;
   const trimmed = value.trim();

package/src/lib/install-resolver.js

@@ -1,4 +1,5 @@
 const fssync = require("node:fs");
+const os = require("node:os");
 const path = require("node:path");
 const wsl = require("./wsl-probe");
 
@@ -48,6 +49,39 @@ function pathExists(p, existsSync) {
   try { return (existsSync || fssync.existsSync)(p) ? p : null; } catch (_e) { return null; }
 }
 
+// ZCode stores its CLI DB under the user's home dir on every platform
+// (~/.zcode/cli/db/db.sqlite), Windows included. The win32 APPDATA guess
+// (introduced with the WSL dual-install work) silently missed the native
+// install, so probe home first and keep APPDATA only as a fallback for
+// installs that do live under Roaming. Falls back to the home path when
+// neither exists so resolveInstallPaths can null it uniformly.
+function resolveZcodeNativeDbPath({
+  home = os.homedir(),
+  env = process.env,
+  platform = process.platform,
+  deps = {},
+} = {}) {
+  const existsSync = deps.existsSync || fssync.existsSync;
+  const zcodeHomeOverride =
+    typeof env.ZCODE_HOME === "string" ? env.ZCODE_HOME.trim() : "";
+  const zcodeHome = zcodeHomeOverride
+    ? path.resolve(zcodeHomeOverride)
+    : path.join(home, ".zcode");
+  // An explicit ZCODE_HOME pins the install: when its database is missing we
+  // must not fall back to an APPDATA database, or sync could read a different
+  // ZCode installation than the one the user pointed at.
+  const candidates = [
+    path.join(zcodeHome, "cli", "db", "db.sqlite"),
+    ...(!zcodeHomeOverride &&
+    platform === "win32" &&
+    typeof env.APPDATA === "string" &&
+    env.APPDATA.trim()
+      ? [path.join(env.APPDATA.trim(), ".zcode", "cli", "db", "db.sqlite")]
+      : []),
+  ];
+  return candidates.find((p) => existsSync(p)) || candidates[0];
+}
+
 function hasAnyChild(p, children, existsSync) {
   const ex = existsSync || fssync.existsSync;
   return children.some((c) => { try { return ex(path.join(p, c)); } catch (_e) { return false; } });
@@ -99,6 +133,7 @@ function ensureFlatCursor(cursors, providerName, env, preferredKey) {
 
 module.exports = {
   resolveInstallPaths,
+  resolveZcodeNativeDbPath,
   ensureNamespacedCursors,
   ensureFlatCursor,
 };

package/src/lib/opencode-go-limits.js

@@ -5,23 +5,27 @@ const { readSqliteJsonRowsAsync } = require("./sqlite-reader");
 
 // OpenCode Go usage limits.
 //
-// Two data sources are available:
+// Three data sources are available, in priority order:
 //
-//   1. Web scrape of the workspace dashboard
-//      (https://opencode.ai/workspace/<id>/go) for the server's authoritative
-//      rolling (5h) / weekly / monthly usagePercent and subscription state.
-//      The cookie is sent as `Cookie: auth=<OPENCODE_GO_AUTH_COOKIE>` per
-//      slkiser/opencode-quota#41.
+//   1. The official OpenCode Go usage API
+//      (GET https://opencode.ai/zen/go/v1/usage) with
+//      `Authorization: Bearer <OPENCODE_GO_API_KEY>`. It returns the server's
+//      authoritative rolling (5h), weekly, and monthly usage windows.
 //
-//   2. Local opencode.db cost aggregation, explicitly enabled with
+//   2. Web scrape of the workspace dashboard
+//      (https://opencode.ai/workspace/<id>/go) for existing users configured
+//      with OPENCODE_GO_AUTH_COOKIE. This is retained as a compatibility path.
+//
+//   3. Local opencode.db cost aggregation, explicitly enabled with
 //      TOKENTRACKER_OPENCODE_GO_LOCAL_ESTIMATE=1. The `opencode` CLI records
 //      every Go turn's USD `cost` in SQLite, so cost ÷ Go's dollar caps is a
 //      useful local estimate. It cannot prove that the account still has an
 //      active Go subscription, because the database contains historical turns
 //      but no current entitlement state.
 //
-// The returned shape is shared by both sources. `source` is `'web'` for
-// authoritative dashboard data or `'local-estimate'` for the opt-in estimate.
+// The returned shape is shared by all sources. `source` is `'api'` for the
+// official endpoint, `'web'` for the compatibility scrape, or `'local-estimate'`
+// for the opt-in estimate.
 
 const SCRAPED_NUMBER_PATTERN = "([0-9]+(?:\\.[0-9]+)?)";
 
@@ -38,11 +42,12 @@ function windowFieldRegex(windowKey, field) {
   return new RegExp(`${windowKey}[^}]*?${field}"?\\s*[:=]+\\s*${SCRAPED_NUMBER_PATTERN}`);
 }
 
+const GO_USAGE_API_URL = "https://opencode.ai/zen/go/v1/usage";
 const DASHBOARD_URL_PREFIX = "https://opencode.ai/workspace/";
 const DASHBOARD_URL_SUFFIX = "/go";
 const USER_AGENT =
   "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Firefox/148.0";
-const DEFAULT_SCRAPE_TIMEOUT_MS = 10_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
 const LOCAL_ESTIMATE_ENV = "TOKENTRACKER_OPENCODE_GO_LOCAL_ESTIMATE";
 
 function isTruthyEnvValue(value) {
@@ -78,6 +83,13 @@ function readConfig(env = process.env) {
   return { workspaceId, authCookie };
 }
 
+function readApiKey(env = process.env) {
+  if (!env || typeof env !== "object") return "";
+  return typeof env.OPENCODE_GO_API_KEY === "string"
+    ? env.OPENCODE_GO_API_KEY.trim()
+    : "";
+}
+
 function clampPercent(value) {
   if (value === null || value === undefined || value === "") return null;
   let n = Number(value);
@@ -486,6 +498,84 @@ function localGoResult(local) {
   };
 }
 
+// --- Official usage API (exact server-side usage, API-key-gated) -------------
+
+async function fetchOpencodeGoApiLimits({ apiKey, fetchImpl, nowMs, timeoutMs }) {
+  let response;
+  try {
+    response = await withTimeout(fetchImpl, timeoutMs)(GO_USAGE_API_URL, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: "application/json",
+        "User-Agent": USER_AGENT,
+      },
+    });
+  } catch (err) {
+    return { configured: true, error: sanitizeMessage(err?.message || err) };
+  }
+
+  if (response.status === 401) {
+    return {
+      configured: true,
+      error: "OpenCode Go API key is missing, invalid, expired, or not entitled to an OpenCode Go subscription.",
+      auth_error: true,
+    };
+  }
+  if (response.status === 403) {
+    return {
+      configured: true,
+      error: "OpenCode Go subscription required for this API key.",
+      auth_error: true,
+    };
+  }
+  if (!response.ok) {
+    return { configured: true, error: `OpenCode Go usage API error ${response.status}` };
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(await response.text());
+  } catch (err) {
+    return {
+      configured: true,
+      error: `Could not parse OpenCode Go usage API response: ${sanitizeMessage(err?.message || err)}`,
+    };
+  }
+
+  const rolling = buildWindow({
+    usagePercent: payload?.rollingUsage?.usagePercent,
+    resetInSec: payload?.rollingUsage?.resetInSec,
+    nowMs,
+  });
+  const weekly = buildWindow({
+    usagePercent: payload?.weeklyUsage?.usagePercent,
+    resetInSec: payload?.weeklyUsage?.resetInSec,
+    nowMs,
+  });
+  const monthly = buildWindow({
+    usagePercent: payload?.monthlyUsage?.usagePercent,
+    resetInSec: payload?.monthlyUsage?.resetInSec,
+    nowMs,
+  });
+
+  if (!rolling && !weekly && !monthly) {
+    return {
+      configured: true,
+      error: "OpenCode Go usage API response did not include any known usage windows.",
+    };
+  }
+
+  return {
+    configured: true,
+    error: null,
+    subscription_status: "active",
+    primary_window: rolling,
+    secondary_window: weekly,
+    tertiary_window: monthly,
+  };
+}
+
 // --- Web scrape (exact server-side usage, cookie-gated) ---------------------
 
 async function scrapeOpencodeGoWeb({ cfg, fetchImpl, nowMs, timeoutMs }) {
@@ -571,14 +661,31 @@ async function fetchOpencodeGoLimits({
   env = process.env,
   fetchImpl = fetch,
   nowMs = Date.now(),
-  timeoutMs = DEFAULT_SCRAPE_TIMEOUT_MS,
+  timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
   sqliteOptions = {},
 } = {}) {
+  const apiKey = readApiKey(env);
   const cfg = readConfig(env);
   const allowLocalEstimate = localEstimateEnabled(env);
 
-  // A configured cookie gives us the only authoritative subscription state.
-  // Never replace an explicit inactive page with historical local usage.
+  // Prefer the documented API whenever an API key is explicitly configured.
+  // An authentication failure is actionable and must not be hidden by silently
+  // falling back to a possibly stale cookie. For a transient API failure, an
+  // existing cookie remains a compatibility fallback.
+  if (apiKey) {
+    const api = await fetchOpencodeGoApiLimits({ apiKey, fetchImpl, nowMs, timeoutMs });
+    if (!api?.error && (api.primary_window || api.secondary_window || api.tertiary_window)) {
+      return { ...api, source: "api" };
+    }
+    if (api?.auth_error) {
+      const { auth_error, ...result } = api;
+      return result;
+    }
+    if (!cfg) return api || { configured: true, error: "OpenCode Go unavailable" };
+  }
+
+  // Keep the cookie-backed dashboard path for existing configurations and as a
+  // fallback when the official API is temporarily unavailable.
   if (cfg) {
     const web = await scrapeOpencodeGoWeb({ cfg, fetchImpl, nowMs, timeoutMs });
     if (web?.subscription_status === "inactive") return web;
@@ -602,7 +709,9 @@ async function fetchOpencodeGoLimits({
 
 module.exports = {
   fetchOpencodeGoLimits,
+  fetchOpencodeGoApiLimits,
   readConfig,
+  readApiKey,
   localEstimateEnabled,
   detectSubscriptionStatus,
   extractWindows,