tokentracker-cli 0.95.1 → 0.96.0

package/src/lib/ark-agent-plan-limits.js

@@ -0,0 +1,437 @@
+"use strict";
+
+// Ark Agent Plan (火山方舟 Agent Plan) quota monitoring.
+//
+// Agent Plan (Small/Medium/Large/Max) and Coding Plan (Lite/Pro) are
+// two parallel subscription products that each refresh on three windows —
+// 5-hour (5h for Agent Plan, session for Coding Plan), weekly and monthly —
+// and are shared by compatible coding tools (Claude Code, Codex CLI,
+// OpenCode, TRAE, ...). Official docs present them as parallel, not
+// successor/replacement. TokenTracker already counts those tools' token
+// consumption from their local files, so this module deliberately adds
+// NO consumption source. It only surfaces the subscription quota
+// percentage, which is otherwise only visible in the Volcano console web
+// page. Coding Plan is handled by a separate provider module
+// `ark-coding-plan-limits.js` (dual Provider, issue #555).
+//
+// The quota is read through the user's own `arkcli` binary
+// (`arkcli usage plan --format json`), which is already installed and logged
+// in for users of the Ark CLI ecosystem. Feature-detected: when `arkcli` is
+// missing, the provider simply reports `configured: false` and stays out of
+// the way. Mirrors ark-coding-plan-limits.js; shares the command runner with
+// usage-limits.js through ./command-runner (no circular dependency).
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const { runCommand, resolveBinaryPath, statBinaryInDirs, commonGlobalBinDirectories } = require("./command-runner");
+
+const ARK_LIMITS_CACHE_FILE = "ark-agent-plan-limits-cache.json";
+const ARK_LIMITS_CACHE_UNKNOWN_RESET_TTL_MS = 12 * 60 * 60 * 1000;
+const ARK_USAGE_PLAN_TIMEOUT_MS = 10_000;
+const ARK_PROFILE_SHOW_TIMEOUT_MS = 2_500;
+const ARK_CLI_STDERR_TRIM = 400;
+const ARK_PROVIDER_TIMEOUT_MS = 15_000;
+const ARK_PROVIDER_BUDGET_GUARD_MS = 1_500;
+
+// arkcli period label -> canonical window slot.
+// Agent Plan uses `5h` for the 5-hour rolling window; `daily` is a
+// visual-only quota not shown in the 3-window panel.
+const ARK_PERIOD_WINDOW = {
+  "5h": "primary_window",
+  session: "primary_window",
+  weekly: "secondary_window",
+  monthly: "tertiary_window",
+};
+
+// Agent Plan personal product. Team products (agent-plan-team) are
+// seat-scoped and not surfaced in this personal-quota panel.
+const ARK_PERSONAL_PRODUCTS = ["agent-plan"];
+const ARK_PRODUCT_PRIORITY = ["agent-plan"];
+
+function clampPercent(value) {
+  return Math.max(0, Math.min(100, value));
+}
+
+function normalizeResetAt(value) {
+  if (value === null || value === undefined || value === "") return null;
+  if (typeof value === "number" || /^\d+(?:\.\d+)?$/.test(String(value).trim())) {
+    const raw = Number(value);
+    if (!Number.isFinite(raw)) return null;
+    const milliseconds = raw > 10_000_000_000 ? raw : raw * 1000;
+    const date = new Date(milliseconds);
+    return Number.isFinite(date.getTime()) ? date.toISOString() : null;
+  }
+  const timestamp = Date.parse(String(value));
+  return Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : null;
+}
+
+function planLabelForTier(tier) {
+  const normalized = String(tier || "").trim().toLowerCase();
+  const mapping = {
+    pro: "Pro",
+    lite: "Lite",
+    small: "Small",
+    medium: "Medium",
+    large: "Large",
+    max: "Max",
+  };
+  if (mapping[normalized]) return mapping[normalized];
+  return tier && String(tier).trim() ? String(tier).trim() : null;
+}
+
+/**
+ * Normalize the JSON payload returned by `arkcli plans get --format json`.
+ * Returns null when there is no Agent Plan entry.
+ */
+function normalizeArkAgentPlansResponse(body) {
+  if (!body || typeof body !== "object") return null;
+  const plans = Array.isArray(body.plans) ? body.plans : [];
+  for (const key of ARK_PRODUCT_PRIORITY) {
+    const plan = plans.find((entry) => entry?.key === key);
+    if (plan?.tier) return String(plan.tier);
+  }
+  return null;
+}
+// Backwards-compat alias used by older callers
+const normalizeArkPlansResponse = normalizeArkAgentPlansResponse;
+
+function arkProfileIdentity(body) {
+  const profile = body?.profile && typeof body.profile === "object" ? body.profile : body;
+  const name = typeof body?.profile === "string"
+    ? body.profile
+    : profile?.name || profile?.profile || profile?.profile_name;
+  let userId = profile?.user_id || profile?.userId || body?.user_id || body?.userId;
+  if (!userId) {
+    const trnMatch = String(profile?.owner_trn || "").match(/::(\d+):/);
+    if (trnMatch) userId = trnMatch[1];
+    else {
+      const keyMatch = String(profile?.identity_key || "").match(/-(\d+)$/);
+      if (keyMatch) userId = keyMatch[1];
+    }
+  }
+  const identity = [name, userId].filter(Boolean).join(":");
+  return identity || null;
+}
+
+function resolveArkProductItem(items) {
+  for (const product of ARK_PRODUCT_PRIORITY) {
+    const item = items.find((entry) => entry?.product === product && entry?.subscribed === true);
+    if (item) return item;
+  }
+  return null;
+}
+
+function percentFromPeriod(period) {
+  // null / undefined / blank percent must fall through to the used/total
+  // fallback: Number(null) and Number("") both coerce to 0, which would
+  // otherwise report a fake fresh 0% window instead of deriving real usage
+  // (the Agent Plan 5h period can omit percent entirely, #555).
+  const rawPercent = period?.percent;
+  if (rawPercent !== null && rawPercent !== undefined && String(rawPercent).trim() !== "") {
+    const direct = Number(rawPercent);
+    if (Number.isFinite(direct)) return direct;
+  }
+  const used = Number(period?.used);
+  const total = Number(period?.total);
+  if (Number.isFinite(used) && Number.isFinite(total) && total > 0) {
+    return (used / total) * 100;
+  }
+  return NaN;
+}
+
+/**
+ * Normalize the JSON payload returned by `arkcli usage plan --format json`.
+ * Returns `null` when the account has no active Agent Plan subscription
+ * (caller reports `configured: false`). Throws when the payload shape is
+ * unusable so the caller can fall back to the disk cache.
+ */
+function normalizeArkAgentPlanResponse(body) {
+  if (!body || typeof body !== "object") {
+    throw new Error("Ark Agent Plan response is not an object.");
+  }
+  const items = Array.isArray(body.items) ? body.items : [];
+  const item = resolveArkProductItem(items);
+  if (!item) return null;
+
+  const windows = {};
+  const periods = Array.isArray(item.periods) ? item.periods : [];
+  for (const period of periods) {
+    if (period?.label === "daily") continue;
+    const slot = ARK_PERIOD_WINDOW[period?.label];
+    if (!slot) continue;
+    const percent = percentFromPeriod(period);
+    if (!Number.isFinite(percent)) continue;
+    windows[slot] = {
+      used_percent: clampPercent(percent),
+      reset_at: normalizeResetAt(period.reset_at),
+      unit: "calls",
+    };
+  }
+  if (!windows.primary_window && !windows.secondary_window && !windows.tertiary_window) {
+    throw new Error("Ark Agent Plan response contains no usable quota periods.");
+  }
+
+  return {
+    configured: true,
+    error: null,
+    plan_label: planLabelForTier(item.tier),
+    product: item.product || null,
+    primary_window: windows.primary_window || null,
+    secondary_window: windows.secondary_window || null,
+    tertiary_window: windows.tertiary_window || null,
+    source: "provider-api",
+    profile_identity: arkProfileIdentity(body.viewer),
+  };
+}
+// Alias for shared shape
+const normalizeArkCodingPlanResponse = normalizeArkAgentPlanResponse;
+
+function arkAgentPlanCachePath({ home = os.homedir() } = {}) {
+  return path.join(home, ".tokentracker", "tracker", ARK_LIMITS_CACHE_FILE);
+}
+
+function readArkAgentPlanLimitsCache({ home = os.homedir(), nowMs = Date.now(), profileIdentity } = {}) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(arkAgentPlanCachePath({ home }), "utf8"));
+    if (profileIdentity && parsed?.profile_identity !== profileIdentity) return null;
+    const cachedAtMs = Date.parse(parsed?.cached_at || "");
+    if (!Number.isFinite(cachedAtMs) || cachedAtMs > nowMs + 60_000) return null;
+    const windows = [parsed?.primary_window, parsed?.secondary_window, parsed?.tertiary_window];
+    const surviving = windows.map((window) => {
+      if (!window) return null;
+      const resetAtMs = Date.parse(window.reset_at || "");
+      if (Number.isFinite(resetAtMs) && resetAtMs <= nowMs) return null;
+      return window;
+    });
+    if (surviving.every((window) => !window)) return null;
+    const bounded = surviving.map((window) => {
+      if (!window) return null;
+      return Number.isFinite(Date.parse(window.reset_at || ""))
+        || nowMs - cachedAtMs <= ARK_LIMITS_CACHE_UNKNOWN_RESET_TTL_MS
+        ? window
+        : null;
+    });
+    if (bounded.every((window) => !window)) return null;
+    return {
+      configured: true,
+      error: null,
+      plan_label: typeof parsed?.plan_label === "string" ? parsed.plan_label : null,
+      product: typeof parsed?.product === "string" ? parsed.product : null,
+      primary_window: bounded[0],
+      secondary_window: bounded[1],
+      tertiary_window: bounded[2],
+      cached: true,
+      stale: true,
+      cached_at: parsed.cached_at,
+      source: "disk-cache",
+    };
+  } catch (_error) {
+    return null;
+  }
+}
+
+function writeArkAgentPlanLimitsCache(limits, { home = os.homedir(), nowMs = Date.now() } = {}) {
+  if (!limits?.configured || limits.error) return;
+  const cachePath = arkAgentPlanCachePath({ home });
+  const payload = {
+    plan_label: limits.plan_label || null,
+    product: limits.product || null,
+    profile_identity: limits.profile_identity || null,
+    primary_window: limits.primary_window || null,
+    secondary_window: limits.secondary_window || null,
+    tertiary_window: limits.tertiary_window || null,
+    cached_at: new Date(nowMs).toISOString(),
+  };
+  try {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    const tmpPath = `${cachePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2), { encoding: "utf8", mode: 0o600 });
+    fs.renameSync(tmpPath, cachePath);
+  } catch (_error) {}
+}
+
+function hasArkCliInstallEvidence({ home = os.homedir(), platform = process.platform } = {}) {
+  const candidates = [
+    path.join(home, ".arkcli"),
+    path.join(home, ".config", "arkcli"),
+  ];
+  if (platform === "win32") {
+    candidates.push(path.join(home, "AppData", "Roaming", "arkcli"));
+  }
+  for (const dir of candidates) {
+    try {
+      if (fs.statSync(dir).isDirectory()) return true;
+    } catch (_error) {}
+  }
+  return false;
+}
+
+function trimStderr(stderr) {
+  const text = String(stderr || "").trim();
+  if (!text) return null;
+  return text.length > ARK_CLI_STDERR_TRIM
+    ? `${text.slice(0, ARK_CLI_STDERR_TRIM)}…`
+    : text;
+}
+
+/**
+ * Fetch Ark Agent Plan quota windows from the local `arkcli` binary.
+ */
+async function fetchArkAgentPlanLimits({
+  commandRunner,
+  home = os.homedir(),
+  nowMs = Date.now(),
+  platform = process.platform,
+  signal,
+  globalBinDirs,
+  providerTimeoutMs = ARK_PROVIDER_TIMEOUT_MS,
+} = {}) {
+  const startedAtMs = performance.now();
+  const budgetedTimeoutMs = (fullTimeoutMs) => {
+    if (!Number.isFinite(providerTimeoutMs) || providerTimeoutMs <= 0) return fullTimeoutMs;
+    const remainingMs = providerTimeoutMs - (performance.now() - startedAtMs);
+    if (remainingMs <= 0) return 0;
+    const guardedMs = Math.floor(remainingMs - ARK_PROVIDER_BUDGET_GUARD_MS);
+    if (guardedMs <= 0) return 0;
+    return Math.min(fullTimeoutMs, guardedMs);
+  };
+
+  const searchDirs = () => Array.isArray(globalBinDirs)
+    ? globalBinDirs
+    : commonGlobalBinDirectories({ home, platform });
+
+  let arkcliPath;
+  if (hasArkCliInstallEvidence({ home, platform })) {
+    try {
+      arkcliPath = await resolveBinaryPath("arkcli", { commandRunner, home, platform, signal, globalBinDirs });
+    } catch (_error) {
+      arkcliPath = null;
+    }
+  } else {
+    arkcliPath = statBinaryInDirs("arkcli", searchDirs(), platform);
+  }
+  if (!arkcliPath) return { configured: false };
+
+  const commandOptions = {
+    signal,
+    killProcessGroup: true,
+    platform,
+    useShell: platform === "win32",
+  };
+
+  const usageTimeoutMs = budgetedTimeoutMs(ARK_USAGE_PLAN_TIMEOUT_MS);
+  if (usageTimeoutMs <= 0) {
+    return { configured: true, error: "Ark Agent Plan provider timed out before arkcli could run." };
+  }
+
+  const result = await runCommand(
+    commandRunner,
+    arkcliPath,
+    ["usage", "plan", "--format", "json"],
+    { ...commandOptions, timeout: usageTimeoutMs },
+  );
+
+  const failWithCache = async (message) => {
+    const profileTimeoutMs = budgetedTimeoutMs(ARK_PROFILE_SHOW_TIMEOUT_MS);
+    const profileIdentity = profileTimeoutMs > 0
+      ? await runCommand(
+        commandRunner,
+        arkcliPath,
+        ["profile", "show", "--format", "json"],
+        { ...commandOptions, timeout: profileTimeoutMs },
+      ).then((profileResult) => {
+        if (profileResult?.error || profileResult?.status !== 0) return null;
+        try {
+          return arkProfileIdentity(JSON.parse(String(profileResult.stdout || "")));
+        } catch (_error) {
+          return null;
+        }
+      }).catch(() => null)
+      : null;
+    const cached = readArkAgentPlanLimitsCache({ home, nowMs, profileIdentity });
+    if (cached) return cached;
+    return { configured: true, error: message };
+  };
+
+  if (result?.error || result?.status !== 0) {
+    const isExit127 = result?.status === 127;
+    const baseDetail = result?.error?.message
+      || (result?.status !== 0 && result?.status !== null
+        ? `arkcli exited with code ${result.status}`
+        : "arkcli usage plan failed");
+    const detail = isExit127
+      ? "arkcli exited with code 127 — please update arkcli: npm i -g @volcengine/ark-cli"
+      : baseDetail;
+    const stderr = trimStderr(result?.stderr);
+    const message = stderr && !isExit127 ? `${detail}: ${stderr}` : detail;
+    return failWithCache(message);
+  }
+
+  let body;
+  try {
+    body = JSON.parse(String(result?.stdout || ""));
+  } catch (_error) {
+    return failWithCache("arkcli usage plan returned invalid JSON.");
+  }
+
+  let limits;
+  try {
+    limits = normalizeArkAgentPlanResponse(body);
+  } catch (error) {
+    return failWithCache(error?.message || "Ark Agent Plan response could not be parsed.");
+  }
+  if (!limits) {
+    const entry = Array.isArray(body?.items)
+      ? body.items.find(
+        (candidate) =>
+          ARK_PERSONAL_PRODUCTS.includes(candidate?.product) && candidate?.subscribed === false,
+      )
+      : null;
+    if (entry) {
+      try {
+        fs.unlinkSync(arkAgentPlanCachePath({ home }));
+      } catch (_error) {}
+    }
+    return { configured: false };
+  }
+
+  if (!limits.plan_label) {
+    const plansTimeoutMs = budgetedTimeoutMs(ARK_USAGE_PLAN_TIMEOUT_MS);
+    if (plansTimeoutMs > 0) {
+      const plansResult = await runCommand(
+        commandRunner,
+        arkcliPath,
+        ["plans", "get", "--format", "json"],
+        { ...commandOptions, timeout: plansTimeoutMs },
+      );
+      if (!plansResult?.error && plansResult?.status === 0) {
+        try {
+          const tier = normalizeArkAgentPlansResponse(JSON.parse(String(plansResult.stdout || "")));
+          if (tier) limits.plan_label = planLabelForTier(tier);
+        } catch (_error) {}
+      }
+    }
+  }
+
+  writeArkAgentPlanLimitsCache(limits, { home, nowMs });
+  return limits;
+}
+
+module.exports = {
+  ARK_PERIOD_WINDOW,
+  ARK_PERSONAL_PRODUCTS,
+  ARK_PRODUCT_PRIORITY,
+  normalizeArkAgentPlansResponse,
+  normalizeArkPlansResponse,
+  arkProfileIdentity,
+  normalizeArkAgentPlanResponse,
+  normalizeArkCodingPlanResponse,
+  readArkAgentPlanLimitsCache,
+  writeArkAgentPlanLimitsCache,
+  hasArkCliInstallEvidence,
+  fetchArkAgentPlanLimits,
+  resolveArkProductItem,
+  percentFromPeriod,
+};

package/src/lib/ark-coding-plan-limits.js

@@ -2,13 +2,17 @@
 
 // Ark Coding Plan (火山方舟 Coding Plan) quota monitoring.
 //
-// Coding Plan is a subscription-style quota product (Lite/Pro) that refreshes
-// on three windows — 5-hour (session), weekly and monthly — and is shared by
-// every compatible coding tool (Claude Code, Codex CLI, OpenCode, TRAE, ...).
-// TokenTracker already counts those tools' token consumption from their local
-// files, so this module deliberately adds NO consumption source. It only
-// surfaces the subscription quota percentage, which is otherwise only visible
-// in the Volcano console web page.
+// Coding Plan (Lite/Pro) and Agent Plan (Small/Medium/Large/Max) are
+// two parallel subscription products that each refresh on three windows —
+// 5-hour (session for Coding Plan, 5h for Agent Plan), weekly and monthly —
+// and are shared by compatible coding tools (Claude Code, Codex CLI,
+// OpenCode, TRAE, ...). Official docs present them as parallel, not
+// successor/replacement. TokenTracker already counts those tools' token
+// consumption from their local files, so this module deliberately adds
+// NO consumption source. It only surfaces the subscription quota
+// percentage, which is otherwise only visible in the Volcano console web
+// page. Agent Plan is handled by a separate provider module
+// `ark-agent-plan-limits.js` (dual Provider, issue #555).
 //
 // The quota is read through the user's own `arkcli` binary
 // (`arkcli usage plan --format json`), which is already installed and logged
@@ -43,14 +47,23 @@ const ARK_PROVIDER_TIMEOUT_MS = 15_000;
 // Same shape as codexResetCreditListTimeoutMs's guard in usage-limits.js.
 const ARK_PROVIDER_BUDGET_GUARD_MS = 1_500;
 
-// arkcli period label -> canonical window slot. `session` is the 5-hour
-// rolling window; `weekly` and `monthly` refresh on calendar boundaries.
+// arkcli period label -> canonical window slot.
+// Coding Plan uses `session` for the 5-hour rolling window; Agent Plan
+// uses `5h`. `weekly` and `monthly` are shared. `daily` (Agent Plan
+// visual quota) is intentionally not surfaced — it is a separate
+// per-day visual bucket that does not fit the three-window panel.
 const ARK_PERIOD_WINDOW = {
   session: "primary_window",
+  "5h": "primary_window",
   weekly: "secondary_window",
   monthly: "tertiary_window",
 };
 
+// Coding Plan personal product. Team products (coding-plan-team) are
+// seat-scoped and not surfaced in this personal-quota panel.
+const ARK_PERSONAL_PRODUCTS = ["coding-plan"];
+const ARK_PRODUCT_PRIORITY = ["coding-plan"];
+
 function clampPercent(value) {
   return Math.max(0, Math.min(100, value));
 }
@@ -73,22 +86,33 @@ function normalizeResetAt(value) {
 // "Ark Coding Plan Coding Plan Lite".
 function planLabelForTier(tier) {
   const normalized = String(tier || "").trim().toLowerCase();
-  if (normalized === "pro") return "Pro";
-  if (normalized === "lite") return "Lite";
+  const mapping = {
+    pro: "Pro",
+    lite: "Lite",
+    small: "Small",
+    medium: "Medium",
+    large: "Large",
+    max: "Max",
+  };
+  if (mapping[normalized]) return mapping[normalized];
   return tier && String(tier).trim() ? String(tier).trim() : null;
 }
 
 /**
  * Normalize the JSON payload returned by `arkcli plans get --format json`.
- * The tier ("lite" / "pro") lives on the plans payload, not on the usage
- * payload, so it is resolved here and merged into the plan label.
+ * The tier ("lite" / "pro" for Coding Plan) lives on the plans payload,
+ * not on the usage payload, so it is resolved here and merged into the
+ * plan label.
  * Returns null when there is no Coding Plan entry.
  */
 function normalizeArkPlansResponse(body) {
   if (!body || typeof body !== "object") return null;
   const plans = Array.isArray(body.plans) ? body.plans : [];
-  const plan = plans.find((entry) => entry?.key === "coding-plan");
-  return plan?.tier ? String(plan.tier) : null;
+  for (const key of ARK_PRODUCT_PRIORITY) {
+    const plan = plans.find((entry) => entry?.key === key);
+    if (plan?.tier) return String(plan.tier);
+  }
+  return null;
 }
 
 function arkProfileIdentity(body) {
@@ -114,26 +138,56 @@ function arkProfileIdentity(body) {
   return identity || null;
 }
 
+function resolveArkProductItem(items) {
+  for (const product of ARK_PRODUCT_PRIORITY) {
+    const item = items.find((entry) => entry?.product === product && entry?.subscribed === true);
+    if (item) return item;
+  }
+  return null;
+}
+
+function percentFromPeriod(period) {
+  // null / undefined / blank percent must fall through to the used/total
+  // fallback: Number(null) and Number("") both coerce to 0, which would
+  // otherwise report a fake fresh 0% window instead of deriving real usage
+  // (Agent Plan's 5h period can omit percent entirely, #555).
+  const rawPercent = period?.percent;
+  if (rawPercent !== null && rawPercent !== undefined && String(rawPercent).trim() !== "") {
+    const direct = Number(rawPercent);
+    if (Number.isFinite(direct)) return direct;
+  }
+  const used = Number(period?.used);
+  const total = Number(period?.total);
+  if (Number.isFinite(used) && Number.isFinite(total) && total > 0) {
+    return (used / total) * 100;
+  }
+  return NaN;
+}
+
 /**
  * Normalize the JSON payload returned by `arkcli usage plan --format json`.
  * Returns `null` when the account has no active Coding Plan subscription
  * (caller reports `configured: false`). Throws when the payload shape is
  * unusable so the caller can fall back to the disk cache.
+ * Only `coding-plan` (Lite/Pro, session label) is handled here;
+ * Agent Plan is handled by `ark-agent-plan-limits.js`.
  */
 function normalizeArkCodingPlanResponse(body) {
   if (!body || typeof body !== "object") {
     throw new Error("Ark Coding Plan response is not an object.");
   }
   const items = Array.isArray(body.items) ? body.items : [];
-  const item = items.find((entry) => entry?.product === "coding-plan");
-  if (!item || item.subscribed !== true) return null;
+  const item = resolveArkProductItem(items);
+  if (!item) return null;
 
   const windows = {};
   const periods = Array.isArray(item.periods) ? item.periods : [];
   for (const period of periods) {
+    // Agent Plan `daily` is a visual-only quota not shown in the 3-window panel.
+    if (period?.label === "daily") continue;
     const slot = ARK_PERIOD_WINDOW[period?.label];
     if (!slot) continue;
-    const percent = Number(period.percent);
+    const percent = percentFromPeriod(period);
     if (!Number.isFinite(percent)) continue;
     windows[slot] = {
       used_percent: clampPercent(percent),
@@ -149,6 +203,7 @@ function normalizeArkCodingPlanResponse(body) {
     configured: true,
     error: null,
     plan_label: planLabelForTier(item.tier),
+    product: item.product || null,
     primary_window: windows.primary_window || null,
     secondary_window: windows.secondary_window || null,
     tertiary_window: windows.tertiary_window || null,
@@ -194,6 +249,7 @@ function readArkCodingPlanLimitsCache({ home = os.homedir(), nowMs = Date.now(),
       configured: true,
       error: null,
       plan_label: typeof parsed?.plan_label === "string" ? parsed.plan_label : null,
+      product: typeof parsed?.product === "string" ? parsed.product : null,
       primary_window: bounded[0],
       secondary_window: bounded[1],
       tertiary_window: bounded[2],
@@ -212,6 +268,7 @@ function writeArkCodingPlanLimitsCache(limits, { home = os.homedir(), nowMs = Da
   const cachePath = arkCodingPlanCachePath({ home });
   const payload = {
     plan_label: limits.plan_label || null,
+    product: limits.product || null,
     profile_identity: limits.profile_identity || null,
     primary_window: limits.primary_window || null,
     secondary_window: limits.secondary_window || null,
@@ -384,12 +441,22 @@ async function fetchArkCodingPlanLimits({
   };
 
   if (result?.error || result?.status !== 0) {
-    const detail = result?.error?.message
+    const isExit127 = result?.status === 127;
+    const baseDetail = result?.error?.message
       || (result?.status !== 0 && result?.status !== null
         ? `arkcli exited with code ${result.status}`
         : "arkcli usage plan failed");
+    // 127 is the classic "command not found" — on a machine with arkcli
+    // installed it almost always means the installed arkcli is too old to
+    // support `usage plan --format json` or the binary shim is broken.
+    // Surface an actionable hint while still honoring the disk-cache fallback.
+    const detail = isExit127
+      ? "arkcli exited with code 127 — please update arkcli: npm i -g @volcengine/ark-cli"
+      : baseDetail;
     const stderr = trimStderr(result?.stderr);
-    return failWithCache(stderr ? `${detail}: ${stderr}` : detail);
+    // Avoid duplicating the stale 127 hint when stderr already contains it.
+    const message = stderr && !isExit127 ? `${detail}: ${stderr}` : detail;
+    return failWithCache(message);
   }
 
   let body;
@@ -406,17 +473,22 @@ async function fetchArkCodingPlanLimits({
     return failWithCache(error?.message || "Ark Coding Plan response could not be parsed.");
   }
   if (!limits) {
-    // Only a response that explicitly carries the coding-plan entry with
+    // Only a response that explicitly carries an Ark product entry with
     // `subscribed: false` confirms the plan was retired — drop the cache
     // then, or a later transient CLI failure would resurrect the retired
-    // plan's numbers through failWithCache. A payload with *no*
-    // coding-plan entry at all (`{}`, `{"items":[]}` — not logged in,
-    // backend degraded, product key renamed) is ambiguous and must NOT
-    // destroy the cache: transient signals never drive persistent state.
+    // plan's numbers through failWithCache. A payload with *no* Ark entry
+    // at all (`{}`, `{"items":[]}` — not logged in, backend degraded,
+    // product key renamed) is ambiguous and must NOT destroy the cache:
+    // transient signals never drive persistent state.
+    // Only coding-plan is considered here; agent-plan is handled by the
+    // parallel provider `ark-agent-plan-limits.js`.
     const entry = Array.isArray(body?.items)
-      ? body.items.find((candidate) => candidate?.product === "coding-plan")
+      ? body.items.find(
+        (candidate) =>
+          ARK_PERSONAL_PRODUCTS.includes(candidate?.product) && candidate?.subscribed === false,
+      )
       : null;
-    if (entry && entry.subscribed === false) {
+    if (entry) {
       try {
         fs.unlinkSync(arkCodingPlanCachePath({ home }));
       } catch (_error) {}
@@ -452,6 +524,8 @@ async function fetchArkCodingPlanLimits({
 
 module.exports = {
   ARK_PERIOD_WINDOW,
+  ARK_PERSONAL_PRODUCTS,
+  ARK_PRODUCT_PRIORITY,
   normalizeArkPlansResponse,
   arkProfileIdentity,
   normalizeArkCodingPlanResponse,
@@ -459,4 +533,7 @@ module.exports = {
   writeArkCodingPlanLimitsCache,
   hasArkCliInstallEvidence,
   fetchArkCodingPlanLimits,
+  // exposed for testing
+  resolveArkProductItem,
+  percentFromPeriod,
 };