agent-dealer 1.2.2 → 1.2.4

package/bundle/server/dist/capacity/cursor-individual-credentials.js

@@ -1,18 +1,21 @@
 // packages/server/src/capacity/cursor-individual-credentials.ts
 //
 // NOT-250: isolated credential lookup for the experimental Cursor Individual
-// dashboard adapter.
+// dashboard adapter. NOT-267: the desktop Cursor login is the primary
+// source, the Cursor Agent auth file the fallback.
 //
 // The dashboard endpoints this feature calls are undocumented: the only
-// credential available is the existing local Cursor login, whose file
-// location and JSON shape are themselves not a supported contract and may
+// credential available is the existing local Cursor login, whose storage
+// locations and shapes are themselves not a supported contract and may
 // change without notice. All of that risk lives in this one module:
 //
-// - Candidate files are tried in order; the first readable file wins.
+// - Resolution order: Cursor desktop `state.vscdb` first (read-only,
+//   single allowlisted key), then the Cursor Agent `auth.json` allowlisted
+//   token shapes. The first usable source wins; Agent auth unchanged.
 // - Accepted JSON shapes are an explicit allowlist below — anything else
 //   reads `unparsable` (changed format), never a guess.
 // - `cursorIndividualCredentialStatus()` (the diagnostics surface) returns
-//   presence/path/format ONLY — never secret material.
+//   presence/source/path/format ONLY — never secret material.
 // - `loadCursorIndividualCredential()` additionally returns an in-memory
 //   `authHeader` for the dashboard HTTP call. The header value must never be
 //   persisted, returned to the browser, or logged — the adapter, repository,
@@ -22,6 +25,9 @@
 // *finds* credentials; whether they may be *used* is decided by the
 // explicit `AGENT_DEALER_CURSOR_INDIVIDUAL_CAPACITY=experimental` opt-in in
 // cursor-individual.ts, which short-circuits before touching this module.
+// Nothing here writes Cursor's database, refreshes tokens, or touches the
+// Keychain or auth files — all reads are read-only.
+import Database from "better-sqlite3";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -29,6 +35,8 @@ import path from "node:path";
 export const CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV = "CURSOR_INDIVIDUAL_CREDENTIAL_FILE";
 /** Home-directory override for tests (mirrors how OS home resolution works). */
 export const CURSOR_INDIVIDUAL_HOME_ENV = "CURSOR_INDIVIDUAL_HOME";
+/** Explicit desktop-state database override (tests point this at tmp fixtures). */
+export const CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV = "CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE";
 /**
  * Community-observed local Cursor login file. The location is undocumented
  * and may move — when it does, reads degrade to `absent`/`unparsable`, never
@@ -83,6 +91,118 @@ export function cursorIndividualCredentialCandidates() {
         return [override];
     return [path.join(homeDir(), CURSOR_INDIVIDUAL_DEFAULT_RELATIVE_PATH)];
 }
+// ---------------------------------------------------------------------------
+// Cursor desktop login (NOT-267, primary source).
+//
+// Cursor desktop keeps its login in the standard VS Code global-storage
+// SQLite database (`state.vscdb`), under the key
+// `cursorAuth/accessToken`. Community tools (ai-usagebar and ports) read
+// that same key first and fall back to a Cursor Agent `auth.json` — this
+// module follows the same order.
+// ---------------------------------------------------------------------------
+/** The ONLY desktop-state key this module ever reads — never anything else. */
+export const CURSOR_DESKTOP_ACCESS_TOKEN_KEY = "cursorAuth/accessToken";
+/** Format label for a credential answered by the desktop state database. */
+export const CURSOR_DESKTOP_FORMAT = "desktop:cursorAuth/accessToken";
+/**
+ * Ordered desktop-state database candidates: exactly one default path per
+ * OS (plus the explicit file override when set). The module never hunts
+ * beyond these — an absent database degrades to the Agent auth fallback,
+ * never to a scan of unrelated files.
+ *
+ * - macOS: `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb`
+ * - Windows: `%APPDATA%/Cursor/User/globalStorage/state.vscdb`
+ * - Linux (and anything else): `~/.config/Cursor/User/globalStorage/state.vscdb`
+ */
+export function cursorIndividualDesktopStateCandidates(opts = {}) {
+    const override = process.env[CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV]?.trim();
+    if (override)
+        return [override];
+    const platform = opts.platform ?? process.platform;
+    const home = opts.home ?? homeDir();
+    if (platform === "win32") {
+        // An explicit `appData` opt always wins (even an explicit empty string,
+        // which reads as no candidate). A present-but-blank APPDATA is the same
+        // as unset — fall back to the roaming default instead of resolving to [].
+        const envAppData = process.env.APPDATA?.trim();
+        const appData = opts.appData ?? (envAppData ? envAppData : path.join(home, "AppData", "Roaming"));
+        if (!appData)
+            return [];
+        return [path.join(appData, "Cursor", "User", "globalStorage", "state.vscdb")];
+    }
+    if (platform === "darwin") {
+        return [
+            path.join(home, "Library", "Application Support", "Cursor", "User", "globalStorage", "state.vscdb"),
+        ];
+    }
+    return [path.join(home, ".config", "Cursor", "User", "globalStorage", "state.vscdb")];
+}
+/**
+ * Normalize one raw desktop-state value to a token. Cursor stores the
+ * access token as a plain-text JWT; a JSON-quoted wrapping is tolerated
+ * (same bytes, quoted), anything else is unusable — never a guess.
+ */
+export function normalizeDesktopTokenValue(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.startsWith('"')) {
+        try {
+            const inner = JSON.parse(trimmed);
+            return typeof inner === "string" && inner.trim() ? inner.trim() : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return trimmed;
+}
+/**
+ * Open the desktop state database READ-ONLY and read ONLY the allowlisted
+ * access-token key. Never throws: a missing/locked database, a missing key,
+ * or an unusable value all read null. The database is never copied, never
+ * written, and no unrelated key is ever selected.
+ */
+export function defaultReadDesktopAccessToken(dbPath) {
+    let db = null;
+    try {
+        db = new Database(dbPath, { readonly: true, fileMustExist: true });
+        const row = db
+            .prepare("SELECT value FROM ItemTable WHERE key = ?")
+            .get(CURSOR_DESKTOP_ACCESS_TOKEN_KEY);
+        if (!row)
+            return null;
+        return normalizeDesktopTokenValue(row.value);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch {
+            // Read-only handle cleanup is best-effort; the read verdict stands.
+        }
+    }
+}
+/**
+ * Build a dashboard auth header from a desktop access token. The desktop
+ * store carries no separate user-id field, so the id is derived from the
+ * token's own JWT `sub` claim through the existing normalization — a token
+ * with no derivable id is unusable (null), never a Bearer-only guess.
+ */
+export function desktopTokenToAuthHeader(token) {
+    const rawUserId = decodeJwtSubject(token);
+    if (!rawUserId)
+        return null;
+    const userId = normalizeWorkosUserId(rawUserId);
+    if (!userId)
+        return null;
+    return cursorIndividualAuthHeader(userId, token);
+}
 function pickByKeys(obj, keys) {
     for (const key of keys) {
         const value = obj[key];
@@ -177,12 +297,31 @@ function defaultReadFile(filePath) {
     }
 }
 /**
- * Find a usable local Cursor credential. Never throws: unreadable files,
- * invalid JSON, and unknown shapes all map to `absent`/`unparsable`.
+ * Find a usable local Cursor credential, desktop first, Agent auth as the
+ * fallback. Never throws: unreadable files, invalid JSON, unknown shapes,
+ * and unusable desktop tokens all map to `absent`/`unparsable`.
  * The raw token leaves this module only inside `authHeader`, held in memory
  * for the single dashboard call the adapter makes with it.
+ *
+ * When `CURSOR_INDIVIDUAL_CREDENTIAL_FILE` pins an explicit file, ONLY that
+ * file is consulted (legacy single-source behavior for fixtures); otherwise
+ * the desktop state database is tried first and the Agent auth file second.
  */
-export function loadCursorIndividualCredential(readFile = defaultReadFile) {
+export function loadCursorIndividualCredential(readFile = defaultReadFile, readDesktopToken = defaultReadDesktopAccessToken) {
+    const explicitFile = process.env[CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV]?.trim();
+    // A present-but-unusable desktop login is remembered (not returned yet):
+    // the Agent fallback still gets its chance — any usable credential wins
+    // over a precise-but-unusable verdict. When nothing is usable, the
+    // desktop verdict is the most precise diagnostic, so it wins over the
+    // Agent one.
+    let desktopUnparsable = null;
+    if (!explicitFile) {
+        const desktop = loadDesktopCredential(readDesktopToken);
+        if (desktop?.found)
+            return desktop.found;
+        desktopUnparsable = desktop?.unparsable ?? null;
+    }
+    const agentUnparsable = (candidate, format) => desktopUnparsable ?? { status: "unparsable", source: null, path: candidate, format };
     for (const candidate of cursorIndividualCredentialCandidates()) {
         const raw = readFile(candidate);
         if (raw === null)
@@ -192,14 +331,14 @@ export function loadCursorIndividualCredential(readFile = defaultReadFile) {
             parsed = JSON.parse(raw);
         }
         catch {
-            return { status: "unparsable", path: candidate, format: null };
+            return agentUnparsable(candidate, null);
         }
         if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-            return { status: "unparsable", path: candidate, format: null };
+            return agentUnparsable(candidate, null);
         }
         const picked = pickToken(parsed);
         if (!picked)
-            return { status: "unparsable", path: candidate, format: null };
+            return agentUnparsable(candidate, null);
         // The cookie needs a user id too — an explicit field wins; otherwise
         // derive it from the token's own JWT `sub` claim. Neither present means
         // this credential cannot build a usable session, same as any other
@@ -207,31 +346,79 @@ export function loadCursorIndividualCredential(readFile = defaultReadFile) {
         // (`google-oauth2|user_abc`) — normalize both the same way.
         const rawUserId = pickUserId(parsed) ?? decodeJwtSubject(picked.token);
         if (!rawUserId)
-            return { status: "unparsable", path: candidate, format: picked.key };
+            return agentUnparsable(candidate, picked.key);
         // Re-check AFTER normalization: an id ending in `|` (e.g. a bare
         // `"google-oauth2|"` with nothing after it) is non-empty here but
         // normalizes to "" — that must degrade too, not build a cookie with an
         // empty user id.
         const userId = normalizeWorkosUserId(rawUserId);
         if (!userId)
-            return { status: "unparsable", path: candidate, format: picked.key };
+            return agentUnparsable(candidate, picked.key);
         return {
             status: "found",
+            source: "agent",
             path: candidate,
             format: picked.key,
             authHeader: cursorIndividualAuthHeader(userId, picked.token),
         };
     }
-    return { status: "absent", path: null, format: null };
+    return desktopUnparsable ?? { status: "absent", source: null, path: null, format: null };
+}
+/**
+ * Try the desktop state database. Returns null when no desktop database
+ * was readable at all (fall through to Agent auth); otherwise the desktop
+ * verdict — `found` when the access token yields a usable session, or an
+ * `unparsable` diagnostic when the database answered but the token cannot
+ * (missing key, empty value, no derivable user id). A present-but-unusable
+ * desktop login is format drift, not absence — but the Agent fallback still
+ * gets its chance via the caller, which prefers any usable credential.
+ */
+function loadDesktopCredential(readDesktopToken) {
+    let sawDatabase = false;
+    let unparsable = null;
+    for (const dbPath of cursorIndividualDesktopStateCandidates()) {
+        let token;
+        try {
+            token = readDesktopToken(dbPath);
+        }
+        catch {
+            continue;
+        }
+        if (token === null)
+            continue;
+        sawDatabase = true;
+        const authHeader = desktopTokenToAuthHeader(token);
+        if (authHeader) {
+            return {
+                found: {
+                    status: "found",
+                    source: "desktop",
+                    path: dbPath,
+                    format: CURSOR_DESKTOP_FORMAT,
+                    authHeader,
+                },
+                unparsable: null,
+            };
+        }
+        // Token present but no derivable user id — same verdict as an Agent
+        // token with no id: changed format, never a Bearer-only guess.
+        if (!unparsable) {
+            unparsable = { status: "unparsable", source: null, path: dbPath, format: CURSOR_DESKTOP_FORMAT };
+        }
+    }
+    if (!sawDatabase && !unparsable)
+        return null;
+    return { found: null, unparsable };
 }
 /**
  * Diagnostics-safe credential presence: delegates to the loader, then
  * strips the in-memory secret. Safe to expose via logs and API responses.
  */
-export function cursorIndividualCredentialStatus(readFile = defaultReadFile) {
-    const credential = loadCursorIndividualCredential(readFile);
+export function cursorIndividualCredentialStatus(readFile = defaultReadFile, readDesktopToken = defaultReadDesktopAccessToken) {
+    const credential = loadCursorIndividualCredential(readFile, readDesktopToken);
     return {
         present: credential.status === "found",
+        source: credential.source,
         path: credential.path,
         format: credential.format,
     };

package/bundle/server/dist/capacity/cursor-individual-credentials.test.js

@@ -9,7 +9,8 @@ import assert from "node:assert/strict";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV, CURSOR_INDIVIDUAL_HOME_ENV, cursorIndividualAuthHeader, cursorIndividualCredentialCandidates, cursorIndividualCredentialStatus, decodeJwtSubject, loadCursorIndividualCredential, normalizeWorkosUserId, } from "./cursor-individual-credentials.js";
+import Database from "better-sqlite3";
+import { CURSOR_DESKTOP_ACCESS_TOKEN_KEY, CURSOR_DESKTOP_FORMAT, CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV, CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV, CURSOR_INDIVIDUAL_HOME_ENV, cursorIndividualAuthHeader, cursorIndividualCredentialCandidates, cursorIndividualCredentialStatus, cursorIndividualDesktopStateCandidates, decodeJwtSubject, defaultReadDesktopAccessToken, desktopTokenToAuthHeader, loadCursorIndividualCredential, normalizeDesktopTokenValue, normalizeWorkosUserId, } from "./cursor-individual-credentials.js";
 const SECRET = "fixture-secret-token-abc123";
 const USER_ID = "user_fixture_abc123";
 /** header.payload.signature with { sub: USER_ID } — no signature verification, so any value works. */
@@ -20,10 +21,14 @@ function fixtureJwt(sub) {
 let dir;
 let savedFileEnv;
 let savedHomeEnv;
+let savedDesktopEnv;
+let savedAppData;
 beforeEach(() => {
     dir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-cursor-indiv-creds-"));
     savedFileEnv = process.env[CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV];
     savedHomeEnv = process.env[CURSOR_INDIVIDUAL_HOME_ENV];
+    savedDesktopEnv = process.env[CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV];
+    savedAppData = process.env.APPDATA;
 });
 afterEach(() => {
     if (savedFileEnv === undefined)
@@ -34,6 +39,14 @@ afterEach(() => {
         delete process.env[CURSOR_INDIVIDUAL_HOME_ENV];
     else
         process.env[CURSOR_INDIVIDUAL_HOME_ENV] = savedHomeEnv;
+    if (savedDesktopEnv === undefined)
+        delete process.env[CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV];
+    else
+        process.env[CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV] = savedDesktopEnv;
+    if (savedAppData === undefined)
+        delete process.env.APPDATA;
+    else
+        process.env.APPDATA = savedAppData;
     fs.rmSync(dir, { recursive: true, force: true });
 });
 function fixture(name, content) {
@@ -50,7 +63,7 @@ test("absent credential file reads absent with no path", () => {
     assert.equal(credential.format, null);
     assert.equal(credential.authHeader, undefined);
     const status = cursorIndividualCredentialStatus();
-    assert.deepEqual(status, { present: false, path: null, format: null });
+    assert.deepEqual(status, { present: false, source: null, path: null, format: null });
 });
 test("empty home directory reads absent (no real login touched)", () => {
     delete process.env[CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV];
@@ -74,6 +87,7 @@ test("accepted token shapes load with an in-memory auth header", () => {
         const file = fixture("auth.json", JSON.stringify(body));
         const credential = loadCursorIndividualCredential();
         assert.equal(credential.status, "found");
+        assert.equal(credential.source, "agent");
         assert.equal(credential.path, file);
         assert.equal(credential.format, format);
         assert.equal(credential.authHeader, cursorIndividualAuthHeader(USER_ID, SECRET));
@@ -183,3 +197,173 @@ test("unreadable files degrade to absent without throwing", () => {
     const dirAsFile = loadCursorIndividualCredential((_p) => null);
     assert.equal(dirAsFile.status, "absent");
 });
+// ---------------------------------------------------------------------------
+// NOT-267: desktop state.vscdb as the primary credential source.
+// ---------------------------------------------------------------------------
+/** Build a fixture desktop-state database with exactly the given keys. */
+function fixtureStateDb(entries, name = "state.vscdb") {
+    const file = path.join(dir, name);
+    const db = new Database(file);
+    try {
+        db.exec("CREATE TABLE ItemTable (key TEXT PRIMARY KEY, value TEXT)");
+        const stmt = db.prepare("INSERT INTO ItemTable (key, value) VALUES (?, ?)");
+        for (const [key, value] of Object.entries(entries))
+            stmt.run(key, value);
+    }
+    finally {
+        db.close();
+    }
+    process.env[CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV] = file;
+    return file;
+}
+/** Desktop tests use the real resolution order: no pinned credential file. */
+function useDefaultSources() {
+    delete process.env[CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV];
+    process.env[CURSOR_INDIVIDUAL_HOME_ENV] = dir;
+}
+test("desktop state paths resolve per OS without touching the real login", () => {
+    const home = path.join(dir, "fake-home");
+    assert.deepEqual(cursorIndividualDesktopStateCandidates({ platform: "darwin", home }), [
+        path.join(home, "Library", "Application Support", "Cursor", "User", "globalStorage", "state.vscdb"),
+    ]);
+    assert.deepEqual(cursorIndividualDesktopStateCandidates({ platform: "linux", home }), [
+        path.join(home, ".config", "Cursor", "User", "globalStorage", "state.vscdb"),
+    ]);
+    const appData = path.join(dir, "fake-appdata");
+    assert.deepEqual(cursorIndividualDesktopStateCandidates({ platform: "win32", home, appData }), [path.join(appData, "Cursor", "User", "globalStorage", "state.vscdb")]);
+    // A present-but-blank APPDATA is the same as unset: the roaming default
+    // applies instead of an empty candidate list.
+    process.env.APPDATA = "   ";
+    assert.deepEqual(cursorIndividualDesktopStateCandidates({ platform: "win32", home }), [
+        path.join(home, "AppData", "Roaming", "Cursor", "User", "globalStorage", "state.vscdb"),
+    ]);
+    delete process.env.APPDATA;
+    // Unknown platforms fall back to the Linux-style layout, never to nothing.
+    assert.deepEqual(cursorIndividualDesktopStateCandidates({ platform: "freebsd", home }), [
+        path.join(home, ".config", "Cursor", "User", "globalStorage", "state.vscdb"),
+    ]);
+    // The explicit override wins on every platform.
+    process.env[CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV] = path.join(dir, "custom.vscdb");
+    assert.deepEqual(cursorIndividualDesktopStateCandidates({ platform: "darwin", home }), [
+        path.join(dir, "custom.vscdb"),
+    ]);
+});
+test("a fixture state.vscdb access token resolves to a desktop credential", () => {
+    useDefaultSources();
+    const jwt = fixtureJwt(USER_ID);
+    // Unrelated state travels alongside the token — including secret-looking
+    // values the loader must never select, return, or report.
+    const dbFile = fixtureStateDb({
+        [CURSOR_DESKTOP_ACCESS_TOKEN_KEY]: jwt,
+        "cursorAuth/refreshToken": "fixture-refresh-must-never-leak",
+        "cursorAuth/cachedEmail": "someone@example.com",
+        "someOtherFeature/state": JSON.stringify({ token: "not-a-cursor-token" }),
+    });
+    const credential = loadCursorIndividualCredential();
+    assert.equal(credential.status, "found");
+    assert.equal(credential.source, "desktop");
+    assert.equal(credential.path, dbFile);
+    assert.equal(credential.format, CURSOR_DESKTOP_FORMAT);
+    assert.equal(credential.authHeader, cursorIndividualAuthHeader(USER_ID, jwt));
+    const status = cursorIndividualCredentialStatus();
+    assert.deepEqual(status, {
+        present: true,
+        source: "desktop",
+        path: dbFile,
+        format: CURSOR_DESKTOP_FORMAT,
+    });
+    const serialized = JSON.stringify({ credential: { ...credential, authHeader: undefined }, status });
+    assert.ok(!serialized.includes(jwt), "raw token must not appear outside the in-memory header");
+    assert.ok(!serialized.includes("fixture-refresh-must-never-leak"), "unrelated desktop keys must never be read");
+});
+test("desktop SQLite wins over Agent auth.json; Agent auth remains the fallback", () => {
+    useDefaultSources();
+    const desktopJwt = fixtureJwt("desktop-user-wins");
+    const agentJwt = fixtureJwt("agent-user-fallback");
+    fixtureStateDb({ [CURSOR_DESKTOP_ACCESS_TOKEN_KEY]: desktopJwt });
+    const agentFile = path.join(dir, ".cursor", "auth.json");
+    fs.mkdirSync(path.dirname(agentFile), { recursive: true });
+    fs.writeFileSync(agentFile, JSON.stringify({ token: agentJwt }));
+    // Both sources usable: the desktop login wins.
+    let credential = loadCursorIndividualCredential();
+    assert.equal(credential.status, "found");
+    assert.equal(credential.source, "desktop");
+    assert.equal(credential.authHeader, cursorIndividualAuthHeader("desktop-user-wins", desktopJwt));
+    // Desktop database gone: the same Agent file now answers as the fallback.
+    fs.rmSync(path.join(dir, "state.vscdb"));
+    delete process.env[CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV];
+    process.env[CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV] = path.join(dir, "missing.vscdb");
+    credential = loadCursorIndividualCredential();
+    assert.equal(credential.status, "found");
+    assert.equal(credential.source, "agent");
+    assert.equal(credential.authHeader, cursorIndividualAuthHeader("agent-user-fallback", agentJwt));
+});
+test("a usable Agent credential still wins over a present-but-unusable desktop token", () => {
+    useDefaultSources();
+    // Desktop token with no derivable user id (not a JWT): unusable on its
+    // own, but it must not sink a working Agent fallback.
+    fixtureStateDb({ [CURSOR_DESKTOP_ACCESS_TOKEN_KEY]: "not-a-jwt" });
+    const agentFile = path.join(dir, ".cursor", "auth.json");
+    fs.mkdirSync(path.dirname(agentFile), { recursive: true });
+    fs.writeFileSync(agentFile, JSON.stringify({ token: SECRET, userId: USER_ID }));
+    const credential = loadCursorIndividualCredential();
+    assert.equal(credential.status, "found");
+    assert.equal(credential.source, "agent");
+});
+test("no usable source in either login reads absent (desktop missing, Agent missing)", () => {
+    useDefaultSources();
+    process.env[CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV] = path.join(dir, "missing.vscdb");
+    const credential = loadCursorIndividualCredential();
+    assert.equal(credential.status, "absent");
+    assert.equal(credential.source, null);
+    assert.equal(credential.authHeader, undefined);
+});
+test("a present-but-unusable desktop login reads unparsable when Agent auth cannot help", () => {
+    useDefaultSources();
+    const dbFile = fixtureStateDb({ [CURSOR_DESKTOP_ACCESS_TOKEN_KEY]: "not-a-jwt" });
+    const credential = loadCursorIndividualCredential();
+    assert.equal(credential.status, "unparsable");
+    assert.equal(credential.path, dbFile);
+    assert.equal(credential.format, CURSOR_DESKTOP_FORMAT);
+    assert.equal(credential.authHeader, undefined);
+});
+test("the desktop reader opens read-only, reads one key, and never throws", () => {
+    const jwt = fixtureJwt(USER_ID);
+    const dbFile = fixtureStateDb({ [CURSOR_DESKTOP_ACCESS_TOKEN_KEY]: jwt });
+    assert.equal(defaultReadDesktopAccessToken(dbFile), jwt);
+    // Missing database, directory path, and missing key all read null.
+    assert.equal(defaultReadDesktopAccessToken(path.join(dir, "missing.vscdb")), null);
+    assert.equal(defaultReadDesktopAccessToken(dir), null);
+    const noKey = fixtureStateDb({ "something/else": "x" }, "nokey.vscdb");
+    assert.equal(defaultReadDesktopAccessToken(noKey), null);
+    // The fixture database is untouched and unlocked after the read.
+    const db = new Database(noKey);
+    try {
+        assert.equal(db.prepare("SELECT COUNT(*) AS n FROM ItemTable").get().n, 1);
+    }
+    finally {
+        db.close();
+    }
+});
+test("normalizeDesktopTokenValue unwraps a JSON-quoted token; empties and non-strings read null", () => {
+    const jwt = fixtureJwt(USER_ID);
+    assert.equal(normalizeDesktopTokenValue(jwt), jwt);
+    assert.equal(normalizeDesktopTokenValue(`  ${jwt}  `), jwt);
+    assert.equal(normalizeDesktopTokenValue(JSON.stringify(jwt)), jwt);
+    assert.equal(normalizeDesktopTokenValue(""), null);
+    assert.equal(normalizeDesktopTokenValue("   "), null);
+    assert.equal(normalizeDesktopTokenValue(42), null);
+    assert.equal(normalizeDesktopTokenValue(null), null);
+    assert.equal(normalizeDesktopTokenValue('"not-closed'), null);
+    // A non-empty unquoted value passes through here — usability (JWT `sub`)
+    // is decided downstream by desktopTokenToAuthHeader, never by guessing.
+    assert.equal(normalizeDesktopTokenValue("null"), "null");
+    assert.equal(desktopTokenToAuthHeader("null"), null);
+});
+test("desktopTokenToAuthHeader derives the WorkOS id from the JWT sub", () => {
+    const jwt = fixtureJwt(USER_ID);
+    assert.equal(desktopTokenToAuthHeader(jwt), cursorIndividualAuthHeader(USER_ID, jwt));
+    assert.equal(desktopTokenToAuthHeader(fixtureJwt("google-oauth2|user_fixture")), cursorIndividualAuthHeader("user_fixture", fixtureJwt("google-oauth2|user_fixture")));
+    assert.equal(desktopTokenToAuthHeader("not-a-jwt"), null);
+    assert.equal(desktopTokenToAuthHeader(""), null);
+});

package/bundle/server/dist/capacity/cursor-individual.js

@@ -108,9 +108,16 @@ export function cursorIndividualTimeoutMs() {
     }
     return 10_000;
 }
-/** Operator-safe failure log: the static kind only, never tokens or payloads. */
+/**
+ * Operator-safe failure log: the static kind only, never tokens or payloads.
+ * A rejected login (401/403) means the local Cursor session the adapter
+ * borrowed is expired or revoked — the operator must refresh the Cursor
+ * login itself (desktop app or `cursor agent login`); Dealer never mutates
+ * Cursor auth, so the hint is static text, not a credential action.
+ */
 function logFailure(kind) {
-    console.error(`[cursor-individual-capacity] dashboard read failed: ${kind}`);
+    const hint = kind === "forbidden" ? " (refresh the Cursor login and retry — Dealer never touches Cursor auth)" : "";
+    console.error(`[cursor-individual-capacity] dashboard read failed: ${kind}${hint}`);
 }
 /** Default reader: no supported surface exists yet — always null. */
 export function defaultSupportedUsageReader() {
@@ -210,6 +217,12 @@ const USED_PERCENT_KEYS = [
     "totalPercentUsed",
     "total_percent_used",
 ];
+// NOTE (NOT-267): `apiPercentUsed` is deliberately NOT listed anywhere here.
+// The live payload reports per-pool scales (e.g. an API-model pool) next to
+// the account-total `individualUsage.plan.totalPercentUsed` — substituting a
+// pool scale for the account total would misreport personal capacity, so a
+// payload carrying ONLY a pool scale reads as no usable scale (unparsable),
+// never as the account total.
 const USED_FRACTION_KEYS = ["usedFraction", "used_fraction", "usageFraction", "usage_fraction"];
 const REMAINING_PERCENT_KEYS = [
     "remainingPercent",
@@ -218,6 +231,34 @@ const REMAINING_PERCENT_KEYS = [
     "percent_remaining",
 ];
 const REMAINING_FRACTION_KEYS = ["remainingFraction", "remaining_fraction"];
+/**
+ * Last-resort scale: the plan's explicit used-vs-limit pair (e.g. spend vs
+ * budget), read ONLY when no percent/fraction/remaining scale is present.
+ * Money-vs-money and count-vs-count both reduce to the same share — but
+ * this never mixes with the percent scales above, and never with a pool
+ * scale: only the `individualUsage.plan` pair counts, never merged
+ * top-level fields.
+ */
+const USED_AMOUNT_KEYS = [
+    "used",
+    "usage",
+    "usedCredits",
+    "used_credits",
+    "consumed",
+    "consumedCredits",
+    "consumed_credits",
+];
+const LIMIT_AMOUNT_KEYS = [
+    "limit",
+    "quota",
+    "allowance",
+    "totalLimit",
+    "total_limit",
+    "limitValue",
+    "limit_value",
+    "monthlyLimit",
+    "monthly_limit",
+];
 function clampPercent(n) {
     return Math.min(100, Math.max(0, n));
 }
@@ -266,6 +307,19 @@ export function cursorIndividualPayloadToReadings(payload) {
     else if (remainingFraction !== null) {
         remainingPercent = clampPercent(remainingFraction * 100);
     }
+    else {
+        // Last resort: the plan's explicit used/limit pair, read from the plan
+        // object ONLY — never from the merged top level, where an unrelated
+        // numeric field (e.g. a top-level `usage` value next to a `limit`) could
+        // otherwise be misread as the plan's scale. A non-positive limit (or a
+        // negative used amount) is not a scale — it reads as no usable value,
+        // never a division artifact.
+        const usedAmount = plan ? pickNumber(plan, USED_AMOUNT_KEYS) : null;
+        const limitAmount = plan ? pickNumber(plan, LIMIT_AMOUNT_KEYS) : null;
+        if (usedAmount !== null && limitAmount !== null && limitAmount > 0 && usedAmount >= 0) {
+            remainingPercent = clampPercent(100 - (usedAmount / limitAmount) * 100);
+        }
+    }
     const hasCycle = cycleLabel !== null || cycleStart !== null || cycleEnd !== null;
     const hasUsage = usageValue !== null || remainingPercent !== null;
     if (!hasCycle && !hasUsage)
@@ -543,9 +597,20 @@ export async function readCursorIndividualBilling(opts = {}) {
     const authHeader = credential.authHeader;
     let fatal = null;
     let readings = null;
+    // A 200 response this module cannot parse as JSON (`malformed`) is kept
+    // distinct from a genuine auth/rate-limit/transport/redirect failure: an
+    // undocumented path can serve an HTML SPA shell with a 200 status instead
+    // of a 404 for an account it doesn't apply to, so `malformed` is treated
+    // like `absent` and the next candidate still gets a try. The first such
+    // verdict is remembered as the diagnostic in case no candidate parses.
+    let malformedFallback = null;
     for (const candidatePath of CURSOR_INDIVIDUAL_USAGE_PATHS) {
         const outcome = await fetchJson(fetchImpl, `${baseUrl}${candidatePath}`, authHeader, timeoutMs);
         if ("failure" in outcome) {
+            if (outcome.failure === "malformed") {
+                malformedFallback = malformedFallback ?? outcome.failure;
+                continue;
+            }
             // Auth, rate-limit, transport, redirect, and oversize failures dominate
             // over remaining candidates: retrying another undocumented path cannot
             // fix a rejected credential or an unsafe redirect.
@@ -562,6 +627,8 @@ export async function readCursorIndividualBilling(opts = {}) {
         readings = parsed;
         break;
     }
+    if (!fatal && !readings)
+        fatal = malformedFallback;
     if (fatal) {
         logFailure(fatal);
         const reason = fatal === "malformed" ? "unparsable" : "missing";