fix(usage): derive window names and unify pin selection (#5903)

* fix(usage): derive window names and unify pin selection

Quota slots do not identify a period. Derive numeric windows and IDs from reported duration and quota scope; keep unknown lengths neutral. Resolve source defaults and explicit pins through one model, with a persisted empty selection distinct from defaults.

* fix(plugins): declare the duration helper host requirement

* fix(usage): verify persisted selections at the storage boundary

plugins/kimi-usage-source/server/usage.test.ts

@@ -279,7 +279,7 @@ describe("Kimi usage source usage windows", () => {
       windows: [
         {
           id: "coding_usage",
-          label: "Weekly limit",
+          label: "Usage limit",
           usedPct: 61,
           remainingPct: 39,
           resetsAt: "2026-08-05T00:01:45Z",
@@ -428,3 +428,41 @@ it.each([401, 403])("reports an existing login rejected with HTTP %i", async (st
     else process.env["KIMI_TOKEN"] = previous;
   }
 });
+
+it("does not invent a weekly duration for unnamed top-level usage", async () => {
+  const directory = mkdtempSync(join(tmpdir(), "kimi-period-"));
+  try {
+    const locator = join(directory, "auth.json");
+    writeFileSync(locator, JSON.stringify({ access_token: "fixture" }));
+    const report = await fetchUsage({ store: "file", locator }, async () =>
+      Response.json({ usage: { limit: "100", remaining: "74" } }),
+    );
+    expect(report).toMatchObject({
+      status: "available",
+      windows: [{ id: "coding_usage", label: "Usage limit" }],
+    });
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+it("does not infer a duration from an unfamiliar time-unit name containing HOUR", async () => {
+  const directory = mkdtempSync(join(tmpdir(), "kimi-unit-"));
+  try {
+    const locator = join(directory, "auth.json");
+    writeFileSync(locator, JSON.stringify({ access_token: "fixture" }));
+    const report = await fetchUsage({ store: "file", locator }, async () =>
+      Response.json({
+        limits: [
+          {
+            window: { duration: 2, timeUnit: "TIME_UNIT_NOT_HOUR" },
+            detail: { limit: "100", used: "11" },
+          },
+        ],
+      }),
+    );
+    expect(report).toMatchObject({ status: "available", windows: [{ label: "Limit 1" }] });
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});

plugins/kimi-usage-source/server/usage.ts

@@ -90,18 +90,18 @@ function durationFrom(value: unknown): number | null {
   return Number.isFinite(duration) && duration > 0 ? duration : null;
 }
 
-function durationLabel(duration: number, timeUnit: string | undefined): string | null {
-  if (!timeUnit) return null;
+function durationLabel(duration: number | null, timeUnit: string | undefined): string | null {
+  if (duration === null || !timeUnit) return null;
 
   const normalizedUnit = timeUnit.replace(/^TIME_UNIT_/i, "").toUpperCase();
-  if (normalizedUnit.includes("MINUTE")) {
+  if (normalizedUnit === "MINUTE") {
     if (duration % 60 === 0) return `${duration / 60}-hour limit`;
     return `${duration}-minute limit`;
   }
-  if (normalizedUnit.includes("HOUR")) return `${duration}-hour limit`;
-  if (normalizedUnit.includes("DAY")) return `${duration}-day limit`;
-  if (normalizedUnit.includes("WEEK")) return `${duration}-week limit`;
-  if (normalizedUnit.includes("SECOND")) return `${duration}-second limit`;
+  if (normalizedUnit === "HOUR") return `${duration}-hour limit`;
+  if (normalizedUnit === "DAY") return `${duration}-day limit`;
+  if (normalizedUnit === "WEEK") return `${duration}-week limit`;
+  if (normalizedUnit === "SECOND") return `${duration}-second limit`;
   return null;
 }
 
@@ -201,7 +201,11 @@ function kimiUsageWindowsFromPayload(payload: unknown): UsageWindow[] {
     windows.push(
       windowFromFields({
         id: uniqueWindowId("coding_usage", seenWindowIds),
-        label: explicitUsageLabel(usage) ?? "Weekly limit",
+        // Top-level usage reports no period unless it supplies duration metadata.
+        label:
+          explicitUsageLabel(usage) ??
+          durationLabel(durationFrom(usage.duration), usage.timeUnit) ??
+          "Usage limit",
         fields: usage,
       }),
     );