@bitkyc08/opencodex 2.40.0 → 2.41.0

package/src/integrations/cursor-effort-table.ts

@@ -0,0 +1,143 @@
+/**
+ * Cursor's local-agent effort table, read from the installed bundle.
+ *
+ * Cursor Private Inference decides which model rows get a Reasoning control from a table
+ * compiled into extensions/cursor-agent-exec/dist/main.js, not from the gateway's
+ * reasoning_effort list (devlog 260902_cursor_bundle_effort_table/000). Reading that table
+ * from the install the dashboard already detects lets the prediction follow a Cursor update
+ * instead of a hand-copied mirror. Read-only, size-bounded, cached by (path, mtime, size);
+ * any parse failure yields null so the caller falls back to the static mirror.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { CursorInstall } from "./cursor-detect";
+
+export interface CursorEffortFamily {
+  id: string;
+  pattern: RegExp;
+  /** [] = family matched but Cursor shows no control. */
+  ladder: readonly string[];
+  param?: "reasoning_effort" | "output_config.effort";
+  defaultValue?: string;
+  outputCap?: number;
+  requiresReasoningCapability: boolean;
+}
+
+export interface CursorBareGpt5Rule {
+  pattern: RegExp;
+  ladder: readonly string[];
+  defaultValue: string;
+}
+
+export interface CursorEffortTable {
+  families: readonly CursorEffortFamily[];
+  /** The bare gpt-5 / gpt-5.x rule that runs when no family matched. */
+  bareGpt5: CursorBareGpt5Rule | null;
+  version: string | null;
+  bundlePath: string;
+}
+
+const BUNDLE_MAX_BYTES = 32 * 1024 * 1024;
+
+/** Bundle path under the install root cursor-detect reports. */
+export function cursorAgentBundlePath(install: Pick<CursorInstall, "path">, platform: string = process.platform): string {
+  const tail = ["extensions", "cursor-agent-exec", "dist", "main.js"];
+  return platform === "darwin"
+    ? join(install.path, "Contents", "Resources", "app", ...tail)
+    : join(install.path, "resources", "app", ...tail);
+}
+
+/**
+ * Parse the family table out of the minified source:
+ *   const w={param:"reasoning_effort",values:[...],defaultValue:"medium"};
+ *   ...const T={...},k={...},S={...},b=[{id:"...",matches:e=>/.../u.test(e),effort:k,outputCap:128e3},...];
+ * Identifier names are minifier-assigned, so binding is by structure: every
+ * <ident>={param:"...",values:[...],defaultValue:"..."} is an effort constant, and a family's
+ * effort: is either such an identifier or an inline object.
+ */
+export function parseCursorEffortTable(source: string): Omit<CursorEffortTable, "version" | "bundlePath"> | null {
+  const constants = new Map<string, { param: string; values: string[]; defaultValue: string }>();
+  const constRe = /(?:const |,)([A-Za-z_$][\w$]*)=\{param:"(reasoning_effort|output_config\.effort)",values:\[([^\]]*)\],defaultValue:"([a-z]+)"\}/gu;
+  for (const m of source.matchAll(constRe)) {
+    constants.set(m[1]!, { param: m[2]!, values: splitStrings(m[3]!), defaultValue: m[4]! });
+  }
+  const tableStart = source.indexOf('=[{id:"anthropic-');
+  if (tableStart === -1) return null;
+  const tableEnd = source.indexOf("];", tableStart);
+  if (tableEnd === -1) return null;
+  const body = source.slice(tableStart + 2, tableEnd + 1);
+  const entryRe = /\{id:"([^"]+)",matches:e=>\/((?:\\\/|[^/])+)\/([a-z]*)\.test\(e\)((?:,(?:effort:(?:[A-Za-z_$][\w$]*|\{[^}]*\})|outputCap:[\de.]+|effortRequiresReasoningCapability:!0))*)\}/gu;
+  const families: CursorEffortFamily[] = [];
+  // Every "{id:" opener in the window must be consumed by entryRe. A build that adds a
+  // property to one family would otherwise drop that family silently and the caller would
+  // report a bundle-sourced "no control" for it instead of falling back to the mirror.
+  const openers = body.split('{id:"').length - 1;
+  for (const m of body.matchAll(entryRe)) {
+    let pattern: RegExp;
+    try { pattern = new RegExp(m[2]!, m[3]!); } catch { return null; }
+    const tail = m[4]!;
+    const effortRef = /effort:([A-Za-z_$][\w$]*)(?:,|$)/u.exec(tail)?.[1];
+    const inline = /effort:\{param:"([^"]+)",values:\[([^\]]*)\],defaultValue:"([a-z]+)"\}/u.exec(tail);
+    const effort = inline
+      ? { param: inline[1]!, values: splitStrings(inline[2]!), defaultValue: inline[3]! }
+      : effortRef ? constants.get(effortRef) : undefined;
+    if (effortRef && !inline && !effort) return null; // unknown constant: structure changed
+    const cap = /outputCap:([\de.]+)/u.exec(tail)?.[1];
+    families.push({
+      id: m[1]!,
+      pattern,
+      ladder: effort?.values ?? [],
+      ...(effort ? { param: effort.param as CursorEffortFamily["param"], defaultValue: effort.defaultValue } : {}),
+      ...(cap ? { outputCap: Number(cap) } : {}),
+      requiresReasoningCapability: tail.includes("effortRequiresReasoningCapability:!0"),
+    });
+  }
+  if (families.length === 0 || families.length !== openers) return null;
+  // The tested variable and the returned constant are minifier-assigned names; bind by shape.
+  const bareRe = /if\(\/(\^gpt-5[^/]+)\/([a-z]*)\.test\([A-Za-z_$][\w$]*\)\)return ([A-Za-z_$][\w$]*)\}/u.exec(source);
+  const bareConst = bareRe ? constants.get(bareRe[3]!) : undefined;
+  let bareGpt5: CursorBareGpt5Rule | null = null;
+  if (bareRe && bareConst) {
+    let pattern: RegExp;
+    try { pattern = new RegExp(bareRe[1]!, bareRe[2]!); } catch { return null; }
+    bareGpt5 = { pattern, ladder: bareConst.values, defaultValue: bareConst.defaultValue };
+  }
+  return { families, bareGpt5 };
+}
+
+function splitStrings(list: string): string[] {
+  return [...list.matchAll(/"([^"]+)"/gu)].map(m => m[1]!);
+}
+
+export interface CursorEffortTableDeps {
+  platform: string;
+  stat(path: string): { mtimeMs: number; size: number } | null;
+  readText(path: string): string | null;
+}
+
+export function realCursorEffortTableDeps(): CursorEffortTableDeps {
+  return {
+    platform: process.platform,
+    stat: path => { try { const s = statSync(path); return { mtimeMs: s.mtimeMs, size: s.size }; } catch { return null; } },
+    readText: path => { try { return readFileSync(path, "utf8"); } catch { return null; } },
+  };
+}
+
+let cache: { key: string; table: CursorEffortTable | null } | null = null;
+
+/** Table from the Private Inference install, else null (caller falls back to the static mirror). */
+export function loadCursorEffortTable(install: CursorInstall | undefined, deps: CursorEffortTableDeps = realCursorEffortTableDeps()): CursorEffortTable | null {
+  if (!install) return null;
+  const bundlePath = cursorAgentBundlePath(install, deps.platform);
+  const st = deps.stat(bundlePath);
+  if (!st || st.size > BUNDLE_MAX_BYTES) return null;
+  const key = `${bundlePath}|${st.mtimeMs}|${st.size}`;
+  if (cache?.key === key) return cache.table;
+  const text = deps.readText(bundlePath);
+  const parsed = text ? parseCursorEffortTable(text) : null;
+  const table = parsed ? { ...parsed, version: install.version, bundlePath } : null;
+  cache = { key, table };
+  return table;
+}
+
+export function resetCursorEffortTableCacheForTests(): void { cache = null; }

package/src/integrations/state.ts

@@ -369,7 +369,7 @@ export function exportContextOf(input: {
      * loopback, and every client we write into deserves the same answer the
      * export command already gives.
      */
-    baseUrl: opencodeProxyBaseUrl(input.port, input.config.hostname),
+    baseUrl: opencodeProxyBaseUrl(input.port, input.config.hostname, input.config),
     models: input.models,
     config: input.config,
   };

package/src/integrations/writer.ts

@@ -12,7 +12,7 @@
 import { homedir } from "node:os";
 import { dirname } from "node:path";
 import { EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export";
-import { isLoopbackHostname } from "../codex/inject";
+import { shouldInjectApiAuthHeader } from "../codex/inject";
 import type { OcxConfig } from "../types";
 import { PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
 import {
@@ -290,7 +290,7 @@ function applyOrRefreshIntegration(
   if (io.statKind(detectDir) !== "dir") {
     return refuse(clientId, "not_installed", "absent", `${clientId} is not installed`);
   }
-  if (isLoopbackOnly(clientId) && !isLoopbackHostname(input.config.hostname)) {
+  if (isLoopbackOnly(clientId) && shouldInjectApiAuthHeader(input.config)) {
     return refuse(clientId, "non_loopback", classified.state,
       `The generated ${clientId} integration is loopback-only and does not emit the admission header a non-loopback bind requires. Give it loopback access instead, through a tunnel or a local forwarder.`);
   }

package/src/lib/app-owned-memory-stores.ts

@@ -38,6 +38,10 @@ import {
   discardRetainedUsageSnapshot,
   retainedUsageSnapshotStats,
 } from "../usage/log";
+import {
+  discardRetainedUsageAggregate,
+  usageAggregateRetainedStats,
+} from "../server/management/usage-aggregate-cache";
 import {
   cursorBlobRetainedStoreSnapshot,
   evictOldestCursorBlobForBudget,
@@ -61,18 +65,33 @@ function ringSnapshot(metrics: { entries: number; bytes: number; oldestAt: numbe
   };
 }
 
-/** The retained usage tail is a single all-or-nothing entry: evicting it drops the whole tail. */
+/** Legacy parsed tail and streaming aggregate share one stable public store id. */
 function usageSnapshotRetainedStoreSnapshot(): RetainedStoreSnapshot {
-  const stats = retainedUsageSnapshotStats();
+  const legacy = retainedUsageSnapshotStats();
+  const aggregate = usageAggregateRetainedStats();
+  const oldest = [legacy.oldestAt, aggregate.oldestAt]
+    .filter((value): value is number => value !== null)
+    .sort((a, b) => a - b)[0] ?? null;
   return {
-    count: stats.count,
-    bytes: stats.bytes,
-    evictableBytes: stats.bytes,
-    pinnedBytes: 0,
-    oldestAt: stats.oldestAt,
+    count: legacy.count + aggregate.count,
+    bytes: legacy.bytes + aggregate.bytes,
+    evictableBytes: legacy.bytes + aggregate.evictableBytes,
+    pinnedBytes: aggregate.pinnedBytes,
+    oldestAt: oldest,
   };
 }
 
+function evictOldestUsageSnapshot(): number {
+  const legacy = retainedUsageSnapshotStats();
+  const aggregate = usageAggregateRetainedStats();
+  if (legacy.bytes > 0
+    && (aggregate.evictableBytes === 0
+      || (legacy.oldestAt ?? Number.POSITIVE_INFINITY) <= (aggregate.oldestAt ?? Number.POSITIVE_INFINITY))) {
+    return discardRetainedUsageSnapshot();
+  }
+  return discardRetainedUsageAggregate();
+}
+
 function providerDebugSnapshot(): RetainedStoreSnapshot {
   return ringSnapshot(debugBufferMetrics());
 }
@@ -154,7 +173,7 @@ export const APP_OWNED_RETAINED_STORE_REGISTRATIONS = [
     id: "usage_snapshot",
     category: "caches",
     snapshot: usageSnapshotRetainedStoreSnapshot,
-    evictOldest: discardRetainedUsageSnapshot,
+    evictOldest: evictOldestUsageSnapshot,
   },
   {
     id: "cursor_blobs",

package/src/lib/bounded-body.ts

@@ -1,3 +1,5 @@
+import { idleDeadline } from "./abort";
+
 /** Maximum number of response-body bytes that may be retained for an error. */
 export const BOUNDED_BODY_MAX_BYTES = 65_536;
 
@@ -49,6 +51,8 @@ export interface BoundedBytesOptions {
 	signal?: AbortSignal;
 	/** Maximum number of raw bytes retained from the response body. */
 	maxBytes: number;
+	/** Deadline between non-empty raw chunks. Omitted means no body-read deadline. */
+	inactivityTimeoutMs?: number;
 }
 
 export interface BoundedBytesResult {
@@ -136,6 +140,15 @@ export async function readBoundedResponseBytes(
 	let retainedBytes = 0;
 	let mustCancel = false;
 	let cancelReason: unknown;
+	const inactivityReason = new DOMException("Response body stalled", "TimeoutError");
+	let rejectForInactivity: ((reason: unknown) => void) | undefined;
+	const inactive = new Promise<never>((_resolve, reject) => {
+		rejectForInactivity = reject;
+	});
+	const inactivity = options.inactivityTimeoutMs === undefined
+		? null
+		: idleDeadline(options.inactivityTimeoutMs, () => rejectForInactivity?.(inactivityReason));
+	inactivity?.reset();
 
 	let rejectForAbort: ((reason: unknown) => void) | undefined;
 	const aborted = new Promise<never>((_resolve, reject) => {
@@ -151,7 +164,7 @@ export async function readBoundedResponseBytes(
 			const read = reader.read();
 			// Observe a late read rejection when abort/cancellation wins the race.
 			void read.catch(() => undefined);
-			const outcome = await Promise.race([read, aborted]);
+			const outcome = await Promise.race([read, aborted, inactive]);
 			if (signal?.aborted) {
 				mustCancel = true;
 				cancelReason = signal.reason;
@@ -163,6 +176,7 @@ export async function readBoundedResponseBytes(
 				return { bytes: retained.subarray(0, retainedBytes), oversized: false };
 			}
 			if (!value || value.byteLength === 0) continue;
+			inactivity?.reset();
 
 			if (value.byteLength > maxBytes - retainedBytes) {
 				mustCancel = true;
@@ -187,6 +201,7 @@ export async function readBoundedResponseBytes(
 		cancelReason = error;
 		throw error;
 	} finally {
+		inactivity?.cancel();
 		signal?.removeEventListener("abort", onAbort);
 		if (mustCancel) cancelWithoutWaiting(reader, cancelReason);
 		try {

package/src/oauth/generic-account-failover.ts

@@ -202,11 +202,11 @@ export function rotateGenericOAuthAccountOn429(
   // A single stored account has nowhere to go; rotating to itself would just replay the 429.
   if (!set || set.accounts.length < 2) return null;
 
-  const parsed = parseRetryAfterMs(retryAfterHeader, now);
+  const parsed = parseRetryAfterMs(retryAfterHeader, now, { preserveImmediate: true });
   // An account whose allowance is provably spent gets a reset-aligned cooldown instead of
   // the default minute: retrying it every 60s until the window rolls over is pure waste.
   // A Retry-After from upstream still wins — it is the server's own instruction.
-  const exhausted = parsed === null ? exhaustedCooldownMs(providerName, failedAccountId, now) : null;
+  const exhausted = parsed === undefined ? exhaustedCooldownMs(providerName, failedAccountId, now) : null;
   const cooldownMs = exhausted ?? Math.min(parsed ?? DEFAULT_COOLDOWN_MS, MAX_COOLDOWN_MS);
   health.set(healthKey(providerName, failedAccountId), {
     cooldownUntil: now + cooldownMs,

package/src/oauth/index.ts

@@ -39,6 +39,7 @@ import { loginAntigravity, refreshAntigravityToken } from "./google-antigravity"
 import { loginCursor, refreshCursorToken } from "./cursor";
 import { loginGithubCopilot, refreshGithubCopilotToken, validateCopilotApiBaseUrl } from "./github-copilot";
 import { loginCommandCode, refreshCommandCodeToken } from "./command-code";
+import { loginMetaMuse, refreshMetaMuseToken } from "./meta-muse";
 import { ANTIGRAVITY_REQUEST_UA } from "../adapters/google-antigravity-wire";
 import { deriveOAuthDefaultModel, deriveOAuthProviderConfig } from "../providers/derive";
 import { apiKeyPoolEntryId, sanitizeApiKeyValue } from "../providers/api-keys";
@@ -228,6 +229,16 @@ export const OAUTH_PROVIDERS: Record<string, OAuthProviderDef> = {
     providerConfig: oauthConfig("kimi"),
     defaultModel: oauthDefaultModel("kimi"),
   },
+  "meta-muse": {
+    login: ctrl => loginMetaMuse(ctrl),
+    refresh: refreshMetaMuseToken,
+    providerConfig: oauthConfig("meta-muse"),
+    defaultModel: oauthDefaultModel("meta-muse"),
+    // Static API key that Meta scopes to its own CLI. Never generate unattended traffic
+    // on it — same posture as anthropic, for the same reason: the vendor restricts use
+    // outside its own client, so every exchange stays attributable to a user action.
+    defaultRefreshPolicy: "disabled",
+  },
   nous: {
     // Nous Portal device-grant login (RFC 8628) against portal.nousresearch.com.
     // The access token is the per-request inference JWT (scope inference:invoke).

package/src/oauth/meta-muse.ts

@@ -0,0 +1,235 @@
+/**
+ * Meta Muse Code credential import.
+ *
+ * The Muse Code CLI signs in through a browser device-approval flow and stores the
+ * result in two places: `~/.config/muse/auth.json` is a POINTER carrying no secret, and
+ * the secret itself lives in the macOS Keychain under service
+ * `ai.meta.dev.credentials`, account `meta`.
+ *
+ * Two measured facts shape this module (devlog/_plan/260903_muse_spark_plan_oauth/003):
+ *
+ * 1. The Keychain payload holds BOTH an `access_token` and an `api_key`, and only the
+ *    `api_key` authenticates the Model API — the OAuth access token returns 401
+ *    `invalid_api_key`. So this is a static-key credential, not a refreshable one.
+ * 2. Meta scopes that credential to the Muse Code CLI in writing. Reusing it here is an
+ *    UNSUPPORTED path the repository owner opted into deliberately, which is why the
+ *    warning below fires before anything is read and why the provider sits in the GUI's
+ *    HIGH_RISK ToS map.
+ *
+ * This module never spawns the CLI. A login that finds no credential explains what to
+ * run rather than running it: `muse login` is interactive with no machine-readable mode,
+ * so a spawned child could outlive cancellation, and polling for the pointer file would
+ * be satisfied instantly by the one already on disk — reimporting the OLD account on a
+ * force-login.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { sanitizeApiKeyValue } from "../providers/api-keys";
+import type { OAuthController, OAuthCredentials } from "./types";
+
+const MUSE_POINTER_PATH = join(homedir(), ".config", "muse", "auth.json");
+const KEYCHAIN_SERVICE = "ai.meta.dev.credentials";
+const KEYCHAIN_ACCOUNT = "meta";
+const MODELS_URL = "https://api.meta.ai/v1/models";
+const VALIDATE_TIMEOUT_MS = 10_000;
+const KEYCHAIN_TIMEOUT_MS = 5_000;
+
+/**
+ * Shown BEFORE any credential is read.
+ *
+ * `login-cli.ts` passes `onProgress` straight to `console.log` and never reads the
+ * registry note, so this is the CLI's only warning surface. The GUI ignores it because
+ * `OAuthTosWarningModal` has already been acknowledged by then.
+ */
+const CONSENT_WARNING = [
+  "Meta scopes the Muse Code credential to the Muse Code CLI.",
+  "Using it here is UNSUPPORTED: Meta does not authorize subscription coverage outside its own CLI,",
+  "how these calls settle is not observable from the API, and you should treat every call as billable.",
+  "The imported key is copied into OpenCodex's auth store (~/.opencodex/auth.json, 0600).",
+  "Supported alternative: the meta-model provider with your own key (META_MODEL_API_KEY).",
+].join(" ");
+
+/** The Keychain payload. `access_token` is deliberately unused — it 401s (003 §B). */
+interface MuseKeychainSecret {
+  api_key?: unknown;
+  access_token?: unknown;
+}
+
+interface MusePointer {
+  providers?: { meta?: { mechanism?: unknown; storage?: unknown; user_email?: unknown } };
+}
+
+/** Injected so tests never touch the real Keychain, filesystem, platform, or network. */
+export interface MuseImportDeps {
+  platform?: string;
+  readPointer?: () => Promise<string | null>;
+  readKeychain?: (signal?: AbortSignal) => Promise<string | null>;
+  fetchImpl?: typeof fetch;
+}
+
+async function defaultReadPointer(): Promise<string | null> {
+  try {
+    return await Bun.file(MUSE_POINTER_PATH).text();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `security` can block indefinitely — the Keychain may raise an interactive approval
+ * prompt, and on a headless or locked machine nobody answers it. Without a deadline the
+ * login would hang before the validation timeout below is even created, so the bound
+ * lives here rather than only around the fetch.
+ */
+async function defaultReadKeychain(signal?: AbortSignal): Promise<string | null> {
+  const deadline = signal
+    ? AbortSignal.any([signal, AbortSignal.timeout(KEYCHAIN_TIMEOUT_MS)])
+    : AbortSignal.timeout(KEYCHAIN_TIMEOUT_MS);
+  let proc: Bun.Subprocess<"ignore", "pipe", "pipe"> | undefined;
+  try {
+    proc = Bun.spawn(
+      ["security", "find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", KEYCHAIN_ACCOUNT, "-w"],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    const child = proc;
+    const finished = Promise.all([new Response(child.stdout).text(), child.exited]);
+    const timedOut = new Promise<null>((resolve) => {
+      if (deadline.aborted) { resolve(null); return; }
+      deadline.addEventListener("abort", () => resolve(null), { once: true });
+    });
+    const settled = await Promise.race([finished, timedOut]);
+    if (settled === null) return null;
+    const [out, code] = settled;
+    if (code !== 0) return null;
+    const trimmed = out.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  } catch {
+    return null;
+  } finally {
+    // A prompt still on screen keeps the child alive after the race resolves.
+    if (proc && proc.exitCode === null) { try { proc.kill(); } catch { /* already gone */ } }
+  }
+}
+
+const INSTALL_HINT =
+  "Install it from https://dev.meta.ai/install.sh, run `muse login`, then retry.";
+
+function normalizedEmail(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim().toLowerCase();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+/**
+ * Import the credential the Muse Code CLI already holds.
+ *
+ * Every refusal names what the user should do. None of them includes the credential.
+ */
+export async function loginMetaMuse(
+  ctrl: OAuthController = {},
+  deps: MuseImportDeps = {},
+): Promise<OAuthCredentials> {
+  // Before ANY read: the CLI has no other warning surface.
+  ctrl.onProgress?.(CONSENT_WARNING);
+
+  const platform = deps.platform ?? process.platform;
+  if (platform !== "darwin") {
+    throw new Error(
+      "Meta Muse Code login is macOS-only: the CLI stores its credential in the macOS Keychain, "
+        + "and no other platform's storage has been verified. Use the meta-model provider with your own key instead.",
+    );
+  }
+
+  const pointerRaw = await (deps.readPointer ?? defaultReadPointer)();
+  if (pointerRaw === null) {
+    throw new Error(`Muse Code CLI credential not found at ${MUSE_POINTER_PATH}. ${INSTALL_HINT}`);
+  }
+
+  let pointer: MusePointer;
+  try {
+    pointer = JSON.parse(pointerRaw) as MusePointer;
+  } catch {
+    throw new Error(`Muse Code credential file at ${MUSE_POINTER_PATH} is not valid JSON. Run \`muse login\` to rewrite it.`);
+  }
+
+  const meta = pointer.providers?.meta;
+  if (!meta || meta.mechanism !== "oauth") {
+    throw new Error("The Muse Code credential file has no signed-in Meta account. Run `muse login`, then retry.");
+  }
+  // A different storage backend is a shape we have not measured; refuse rather than guess.
+  if (meta.storage !== "keychain") {
+    throw new Error(
+      `Muse Code stored its credential with an unsupported backend (${String(meta.storage)}); only the macOS Keychain is verified.`,
+    );
+  }
+
+  const secretRaw = await (deps.readKeychain ?? defaultReadKeychain)(ctrl.signal);
+  if (secretRaw === null) {
+    throw new Error(
+      "Could not read the Muse Code credential from the macOS Keychain within 5s. Approve the Keychain prompt, or run `muse login` again.",
+    );
+  }
+
+  let secret: MuseKeychainSecret;
+  try {
+    secret = JSON.parse(secretRaw) as MuseKeychainSecret;
+  } catch {
+    throw new Error("The Muse Code Keychain entry is not valid JSON. Run `muse login` to rewrite it.");
+  }
+
+  // access_token is present but 401s against the Model API (003 §B) — never fall back to it.
+  const apiKey = sanitizeApiKeyValue(secret.api_key);
+  if (!apiKey) {
+    throw new Error("The Muse Code Keychain entry carries no usable API key. Run `muse login` again.");
+  }
+  if (!/^LLM\|\d+\|[A-Za-z0-9_-]{10,}$/.test(apiKey)) {
+    throw new Error("The Muse Code credential is not in the expected Meta API key format. Run `muse login` again.");
+  }
+
+  ctrl.onProgress?.("Validating the imported Meta credential…");
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  // ctrl.signal is OPTIONAL and the CLI controller supplies none: AbortSignal.any([undefined])
+  // throws a TypeError, which would fail every CLI login right after the warning printed.
+  const signal = ctrl.signal
+    ? AbortSignal.any([ctrl.signal, AbortSignal.timeout(VALIDATE_TIMEOUT_MS)])
+    : AbortSignal.timeout(VALIDATE_TIMEOUT_MS);
+  let response: Response;
+  try {
+    response = await fetchImpl(MODELS_URL, {
+      headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+      signal,
+    });
+  } catch (error) {
+    if (ctrl.signal?.aborted) throw ctrl.signal.reason ?? new DOMException("Meta Muse login aborted", "AbortError");
+    throw new Error(`Could not reach the Meta Model API to validate the credential: ${(error as Error).message}`);
+  }
+  if (!response.ok) {
+    throw new Error(
+      `The Muse Code credential was rejected by the Meta Model API (HTTP ${response.status}). Run \`muse login\` again.`,
+    );
+  }
+
+  return {
+    access: apiKey,
+    // Static key: there is nothing to exchange, so refresh carries the same value.
+    refresh: apiKey,
+    expires: Number.MAX_SAFE_INTEGER,
+    // `email`, not `accountId`: the account list masks email for display, and store.ts
+    // already falls back to it for slot identity, so multi-account still works.
+    ...(normalizedEmail(meta.user_email) ? { email: normalizedEmail(meta.user_email) } : {}),
+    source: "local-cli",
+  };
+}
+
+/**
+ * Static-key refresh, exactly like Command Code's.
+ *
+ * This deliberately does NOT re-read the Keychain. Generic refresh writes its result into
+ * the slot being refreshed, so if the user ran `muse login` with a DIFFERENT account in
+ * between, a re-import would silently overwrite one stored identity with another. Only an
+ * explicit login may import.
+ */
+export async function refreshMetaMuseToken(apiKey: string): Promise<OAuthCredentials> {
+  if (!apiKey) throw new Error("Meta Muse Code API key missing; run `ocx login meta-muse`");
+  return { access: apiKey, refresh: apiKey, expires: Number.MAX_SAFE_INTEGER, source: "local-cli" };
+}