fix(provider-muse): Muse Code's subscription usage shows in Usage limits

apps/mobile/src/features/threads/ComposerUsageLimits.tsx

@@ -5,7 +5,11 @@ import { SymbolView } from "../../components/AppSymbol";
 import { AppText as Text } from "../../components/AppText";
 import { AccountLimits, ResetCredits } from "../usage/UsageLimitsSection";
 
-const DRIVER_LABEL: Partial<Record<string, string>> = { codex: "Codex", claudeAgent: "Claude" };
+const DRIVER_LABEL: Partial<Record<string, string>> = {
+  codex: "Codex",
+  claudeAgent: "Claude",
+  muse: "Muse Code",
+};
 
 /**
  * The /usage-limits result, docked above the composer. It is the Usage → Limits

apps/mobile/src/features/usage/UsageLimitsPooled.tsx

@@ -30,6 +30,7 @@ const DRIVER_LABEL: Partial<Record<string, string>> = {
   codex: "Codex",
   claudeAgent: "Claude",
   antigravity: "Antigravity",
+  muse: "Muse Code",
 };
 const PACE_LABEL = { ahead: "Ahead of pace", on: "On pace", under: "Under pace" } as const;
 

docs/user/providers-muse.md

@@ -43,6 +43,13 @@ Muse can list models that your account cannot use. If a message fails with
 "does not exist or you lack access", pick another model, or add one your account
 can use under **Custom models** in the instance settings.
 
+## Usage limits
+
+**Usage → Limits** shows your Meta subscription's session and weekly windows.
+Muse reports them with each reply, so they appear after Muse's first reply
+since the T3 server started. An instance configured with `META_API_KEY` does
+not report subscription limits.
+
 ## Permissions and limitations
 
 Muse offers two [permission modes](./permission-modes.md): **Supervised** asks

docs/user/usage.md

@@ -118,6 +118,10 @@ Grok reports the remaining subscription allowance and reset time for its current
 after signing in with `grok login`. Explicit `XAI_API_KEY` connections and custom authentication
 or endpoint configurations do not report subscription limits.
 
+Muse Code reports your Meta subscription's session and weekly windows with each reply, not on
+request, so they appear after Muse's first reply since the server started. A Muse instance
+configured with `META_API_KEY` does not report subscription limits.
+
 API-key accounts may not report subscription limits. This also applies to Claude connections
 using a proxy through `ANTHROPIC_AUTH_TOKEN`.
 

packages/provider-core/src/server/managedProvider.ts

@@ -207,6 +207,7 @@ export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(
           previous: state.snapshot.usageLimits,
           update,
           checkedAt: update.checkedAt,
+          ...(update.replace ? { replace: true } : {}),
         });
         // `applyUsageLimitsUpdate` hands back the same object when nothing
         // moved, which is the common case for Codex's per-tick notification.

packages/provider-core/src/server/snapshot.ts

@@ -18,9 +18,13 @@ export interface ManagedServerProvider {
   /**
    * Fold a runtime rate-limit update into the published snapshot without
    * waiting for the next status probe. Sparse: windows merge by id and an
-   * update with no usable window leaves the snapshot untouched.
+   * update with no usable window leaves the snapshot untouched. With
+   * `replace`, the update's windows are the whole set instead.
    */
   readonly applyUsageLimits: (
-    update: ProviderUsageLimitsUpdate & { readonly checkedAt: string },
+    update: ProviderUsageLimitsUpdate & {
+      readonly checkedAt: string;
+      readonly replace?: boolean;
+    },
   ) => Effect.Effect<void>;
 }

packages/provider-core/src/server/usageLimits.test.ts

@@ -62,6 +62,45 @@ describe("applyUsageLimitsUpdate", () => {
     ).toBe(published);
   });
 
+  it("replaces the windows outright when the update is the account's whole state", () => {
+    // Muse reports a window that has reset since with no reset time; a sparse
+    // merge would keep the expired one.
+    const restarted = {
+      id: "five_hour",
+      kind: "session",
+      label: "Session",
+      usedPercent: 0,
+      windowDurationMins: 300,
+    } as const;
+    expect(
+      applyUsageLimitsUpdate({
+        previous: published,
+        checkedAt: "2026-09-03T15:00:00.000Z",
+        update: { windows: [restarted] },
+        replace: true,
+      }),
+    ).toEqual({ checkedAt: "2026-09-03T15:00:00.000Z", windows: [restarted] });
+    // The same report again publishes nothing new.
+    expect(
+      applyUsageLimitsUpdate({
+        previous: published,
+        checkedAt,
+        update: { windows: [session, weekly] },
+        replace: true,
+      }),
+    ).toBe(published);
+    // A later report with the same windows publishes its time, so this account's
+    // report still counts as the freshest when Limits merges environments.
+    expect(
+      applyUsageLimitsUpdate({
+        previous: published,
+        checkedAt: "2026-09-03T12:00:05.000Z",
+        update: { windows: [session, weekly] },
+        replace: true,
+      }),
+    ).toEqual({ ...published, checkedAt: "2026-09-03T12:00:05.000Z" });
+  });
+
   it("preserves reset credits when a streamed window update changes usage", () => {
     const resetCredits = { availableCount: 2, nextExpiresAt: "2026-10-01T00:00:00.000Z" };
     const next = applyUsageLimitsUpdate({

packages/provider-core/src/server/usageLimits.ts

@@ -61,31 +61,48 @@ export function applyUsageLimitsUpdate(input: {
   readonly previous: ServerProviderUsageLimits | undefined;
   readonly update: ProviderUsageLimitsUpdate;
   readonly checkedAt: string;
+  /**
+   * The update is the account's whole state: windows it leaves out are
+   * dropped, and a reset time it omits is cleared rather than kept.
+   */
+  readonly replace?: boolean;
 }): ServerProviderUsageLimits | undefined {
   const { previous, update } = input;
+  const replace = input.replace === true;
   if (update.windows.length === 0 || previous?.unavailable?.reason === "unsupported") {
     return previous;
   }
-  const merged = new Map(previous?.windows.map((window) => [window.id, window] as const));
+  const published = new Map(previous?.windows.map((window) => [window.id, window] as const));
+  const merged = replace
+    ? new Map<ServerProviderUsageWindow["id"], ServerProviderUsageWindow>()
+    : new Map(published);
   // Codex sends this notification beside every token-usage tick, almost
   // always with unchanged numbers. Decide "nothing changed" per window on
-  // the way through so the no-op case never allocates a new snapshot.
-  let changed = false;
+  // the way through so the no-op case never allocates a new snapshot. A
+  // whole-state report that only moves the time is still news: Limits picks
+  // the freshest report for an account across environments by `checkedAt`.
+  let changed =
+    replace &&
+    (update.windows.length !== published.size || input.checkedAt !== previous?.checkedAt);
   for (const window of update.windows) {
-    const existing = merged.get(window.id);
+    const existing = published.get(window.id);
     const next: ServerProviderUsageWindow = {
       ...window,
       usedPercent: clampPercent(window.usedPercent),
-      ...(window.resetsAt === undefined && existing?.resetsAt !== undefined
+      ...(!replace && window.resetsAt === undefined && existing?.resetsAt !== undefined
         ? { resetsAt: existing.resetsAt }
         : {}),
-      ...(window.windowDurationMins === undefined && existing?.windowDurationMins !== undefined
+      ...(!replace &&
+      window.windowDurationMins === undefined &&
+      existing?.windowDurationMins !== undefined
         ? { windowDurationMins: existing.windowDurationMins }
         : {}),
     };
     if (existing === undefined || !usageWindowEquals(existing, next)) {
       merged.set(window.id, next);
       changed = true;
+    } else if (replace) {
+      merged.set(window.id, existing);
     }
   }
   if (!changed && previous !== undefined && previous.unavailable === undefined) {

packages/provider-muse/src/server/adapter.test.ts

@@ -33,7 +33,7 @@ import * as Stream from "effect/Stream";
 
 import * as TestProviderHost from "@t3tools/provider-testing/TestProviderHost";
 import * as McpProviderSessions from "@t3tools/provider-core/server/McpProviderSessions";
-import type { MuseItem } from "./protocol.ts";
+import type { MuseItem, MuseSubscriptionUsage } from "./protocol.ts";
 import type { MuseSdkHost } from "./sdk.ts";
 import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
 import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
@@ -191,7 +191,11 @@ const makeHarness = Effect.fnUntraced(function* (
   policy = runtimePolicy,
   overrides: Pick<
     MuseAdapterV2Options,
-    "createHost" | "nativeEventLogger" | "modelCatalog" | "continuationRequests"
+    | "createHost"
+    | "nativeEventLogger"
+    | "modelCatalog"
+    | "continuationRequests"
+    | "onSubscriptionUsage"
   > = {},
 ) {
   let hostCount = 0;
@@ -548,6 +552,39 @@ describe("MuseAdapterV2", () => {
     }).pipe(Effect.scoped, Effect.provide(testLayer)),
   );
 
+  it.effect("forwards subscription usage reports and skips unreadable ones", () =>
+    Effect.gen(function* () {
+      const fake = yield* makeFakeMuse();
+      const reported = yield* Deferred.make<MuseSubscriptionUsage>();
+      const harness = yield* makeHarness(
+        fake,
+        INSTANCE_ID,
+        undefined,
+        undefined,
+        undefined,
+        runtimePolicy,
+        {
+          onSubscriptionUsage: (usage) => Deferred.succeed(reported, usage).pipe(Effect.asVoid),
+        },
+      );
+      const { nativeId } = yield* startConversation(harness, fake);
+      yield* fake.emit("usage/changed", { tier: 1 });
+      yield* fake.emit("usage/changed", {
+        observedAtMs: 1_000,
+        tier: "meta-subscription",
+        window: { usedPercent: 3, resetsAtMs: 2_000, windowDurationMins: 300 },
+        weekly: { usedPercent: 46, resetsAtMs: 3_000 },
+      });
+      const usage = yield* Deferred.await(reported);
+      assert.strictEqual(usage.window.usedPercent, 3);
+      assert.strictEqual(usage.weekly.usedPercent, 46);
+      yield* fake.emit("turn/completed", { turnId: nativeId, terminal: "completed" });
+      const terminal = yield* harness.takeEvent("turn.terminal");
+      assert.strictEqual(terminal.status, "completed");
+      assert.strictEqual(fake.closeCount(), 0);
+    }).pipe(Effect.scoped, Effect.provide(testLayer)),
+  );
+
   it.effect("moves a resumed session on another model back to the catalog default", () =>
     Effect.gen(function* () {
       const fake = yield* makeFakeMuse();

packages/provider-muse/src/server/adapter.ts

@@ -50,6 +50,7 @@ import {
   MuseDelta,
   MuseItemEvent,
   MuseSessionResult,
+  MuseSubscriptionUsage,
   MuseTokenUsageEvent,
   MuseTodoList,
   MuseTurnRetryScheduled,
@@ -195,6 +196,8 @@ export interface MuseAdapterV2Options {
   readonly createHost?: typeof createMuseSdkHost;
   readonly requestTimeoutMs?: number;
   readonly nativeEventLogger?: ProviderEventLoggers.EventNdjsonLogger;
+  /** Each subscription-usage report Muse forwards (`usage/changed`); the driver publishes it. */
+  readonly onSubscriptionUsage?: (usage: MuseSubscriptionUsage) => Effect.Effect<void>;
   /** Where a turn Muse starts on its own (a finished workflow's report) asks for its run. */
   readonly continuationRequests?: {
     readonly offer: (
@@ -261,6 +264,7 @@ const INFORMATIONAL_NOTIFICATIONS = new Set([
   "session/tokenUsage",
   "session/todoListChanged",
   "turn/retryScheduled",
+  "usage/changed",
 ]);
 // Tools whose results already show as their own rows: T3's todo list and question
 // rows, and the workflow item a `workflow` call launches.
@@ -1284,6 +1288,12 @@ export const makeMuseAdapterV2 = Effect.fn("makeMuseAdapterV2")(function* (
         }
       });
       const handleNotification = Effect.fnUntraced(function* (method: string, data: unknown) {
+        // Subscription usage is connection-scoped: its payload names no session.
+        if (method === "usage/changed") {
+          const usage = yield* decode(MuseSubscriptionUsage, data);
+          if (options.onSubscriptionUsage) yield* options.onSubscriptionUsage(usage);
+          return;
+        }
         const params = yield* decode(recordSchema, data);
         if (params.sessionId !== nativeSessionId) return;
         if (method === "view/gap")

packages/provider-muse/src/server/driver.ts

@@ -1,10 +1,13 @@
 import { ProviderDriverKind } from "@t3tools/contracts";
 import { MuseSettings } from "../settings.ts";
 import * as HostProcess from "@t3tools/shared/HostProcess";
+import * as DateTime from "effect/DateTime";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
+import * as Ref from "effect/Ref";
 import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
 import * as HttpClient from "effect/http/HttpClient";
 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
 
@@ -22,6 +25,14 @@ import * as ProviderEventLoggers from "@t3tools/provider-core/server/ProviderEve
 import { makeManagedServerProvider } from "@t3tools/provider-core/server/managedProvider";
 import { enrichMuseSnapshot, latestMuseVersion, museMaintenance } from "./maintenance.ts";
 import { makeMuseEnvironment } from "./sdk.ts";
+import type { MuseSubscriptionUsage } from "./protocol.ts";
+import {
+  isNewerMuseUsageReport,
+  museSubscriptionUsageToLimits,
+  museSubscriptionUsageToUpdate,
+} from "./usageLimits.ts";
+import { makeUnavailableUsageLimits } from "@t3tools/provider-core/server/usageLimits";
+import type { ServerProviderDraft } from "@t3tools/provider-core/server/snapshotProbe";
 import {
   defaultProviderContinuationIdentity,
   type ProviderDriver,
@@ -92,6 +103,46 @@ export const MuseDriver: ProviderDriver<MuseSettings, MuseDriverEnv> = {
         continuationGroupKey: continuationIdentity.continuationKey,
       });
       const snapshotSettings = yield* makeProviderSnapshotSettingsSource(effectiveConfig);
+      // Meta reports subscription usage only with a reply, and a status check
+      // makes none. Keep the newest report from any of this instance's
+      // sessions so a refresh re-derives the windows instead of dropping
+      // them. Reports and status checks take turns through one permit, so
+      // comparing, retaining and publishing a report is a single step: an
+      // older report arriving late can neither overwrite nor publish over a
+      // newer one.
+      const retainedUsage = yield* Ref.make<MuseSubscriptionUsage | undefined>(undefined);
+      const usagePermit = yield* Semaphore.make(1);
+      // Only the instance's own environment counts: an inherited META_API_KEY
+      // was already dropped so Muse uses its login.
+      const usesApiKey = Object.entries(processEnvironment).some(
+        ([key, value]) => key.toUpperCase() === "META_API_KEY" && (value ?? "").trim() !== "",
+      );
+      const withUsageLimits = (snapshot: ServerProviderDraft) =>
+        usagePermit.withPermits(1)(
+          Effect.gen(function* () {
+            if (!effectiveConfig.enabled || !snapshot.installed) return snapshot;
+            const now = yield* DateTime.now;
+            if (usesApiKey) {
+              return {
+                ...snapshot,
+                usageLimits: makeUnavailableUsageLimits({
+                  checkedAt: DateTime.formatIso(now),
+                  reason: "unsupported",
+                  message: "Muse uses an API key here, which does not report subscription limits.",
+                }),
+              };
+            }
+            const usage = yield* Ref.get(retainedUsage);
+            const usageLimits = usage
+              ? museSubscriptionUsageToLimits({ usage, nowMs: DateTime.toEpochMillis(now) })
+              : makeUnavailableUsageLimits({
+                  checkedAt: DateTime.formatIso(now),
+                  reason: "probeFailed",
+                  message: "Muse reports usage limits with its next reply.",
+                });
+            return { ...snapshot, usageLimits };
+          }),
+        );
       const resolveInstallation = yield* makeCachedProviderMaintenanceResolution(
         resolveProviderMaintenanceCapabilitiesEffect(museMaintenance, {
           binaryPath: effectiveConfig.binaryPath,
@@ -126,6 +177,7 @@ export const MuseDriver: ProviderDriver<MuseSettings, MuseDriverEnv> = {
         initialSnapshot: (settings) =>
           makePendingMuseProvider(settings.provider).pipe(Effect.map(stampIdentity)),
         checkProvider: checkMuseProviderStatus(effectiveConfig, processEnvironment, cwd).pipe(
+          Effect.flatMap(withUsageLimits),
           Effect.map(stampIdentity),
           Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
           Effect.provideService(FileSystem.FileSystem, fileSystem),
@@ -163,6 +215,24 @@ export const MuseDriver: ProviderDriver<MuseSettings, MuseDriverEnv> = {
         environment: processEnvironment,
         modelCatalog,
         ...(eventLoggers.native ? { nativeEventLogger: eventLoggers.native } : {}),
+        onSubscriptionUsage: (usage) =>
+          usagePermit
+            .withPermits(1)(
+              Effect.gen(function* () {
+                // Every session's host reports; only the newest wins.
+                const newer = yield* Ref.modify(retainedUsage, (previous) =>
+                  isNewerMuseUsageReport(previous, usage)
+                    ? ([true, usage] as const)
+                    : ([false, previous] as const),
+                );
+                if (!newer || usesApiKey) return;
+                const now = yield* DateTime.now;
+                yield* snapshot.applyUsageLimits(
+                  museSubscriptionUsageToUpdate({ usage, nowMs: DateTime.toEpochMillis(now) }),
+                );
+              }),
+            )
+            .pipe(Effect.ignoreCause({ log: true })),
         continuationRequests,
       });
       const textGeneration = yield* makeMuseTextGeneration(effectiveConfig, {