agent-dealer 1.2.1 → 1.2.3

package/bundle/shared/dist/runtime-capacity.js

@@ -34,6 +34,16 @@ export const CapacityUnavailableReason = z.enum([
     "unparsable",
     "stale",
 ]);
+/**
+ * Which account-wide critical window this is, set once by the adapter that
+ * knows the provider's own identity for it (e.g. Codex's `rateLimits`
+ * aggregate, or whichever detailed limit pair it collapsed into) — never
+ * re-derived downstream from a window key, label, or duration, none of
+ * which can disambiguate multiple same-duration buckets a provider reports.
+ * Null means "not the account-wide pair" (a non-critical extra bucket, or a
+ * provider/window this contract has no opinion on).
+ */
+export const CapacityCriticalRole = z.enum(["five_hour", "weekly"]);
 export const CapacityWindowSnapshot = z.object({
     /** Stable per-runtime key for this window (e.g. `weekly_all_models`). */
     windowKey: z.string().min(1),
@@ -58,6 +68,7 @@ export const CapacityWindowSnapshot = z.object({
     expiresAt: z.string().nullable(),
     source: CapacitySource,
     unavailableReason: CapacityUnavailableReason.nullable(),
+    criticalRole: CapacityCriticalRole.nullable(),
 });
 export const RuntimeCapacityEntry = z.object({
     runtime: Runtime,
@@ -189,6 +200,55 @@ export function isTeamBillingKnown(b, nowMs = Date.now()) {
     }
     return true;
 }
+/**
+ * NOT-250: monthly/billing-cycle capacity for Cursor Individual accounts via
+ * an opt-in *experimental* dashboard adapter. Cursor documents monthly
+ * individual usage (Spending dashboard) but exposes no supported usage API,
+ * so this surface reads authenticated dashboard endpoints using the existing
+ * local Cursor login. Those endpoints and credential formats are not a
+ * supported public contract and may change without notice — hence disabled
+ * by default, `experimental_api` source, and N/A degradation on any drift.
+ * Billing-cycle values only (label/start/end, reported usage, remaining
+ * percent): no 5H/1W-style windows are invented, and money is never rendered
+ * as a token percentage. N/A reasons reuse CapacityUnavailableReason.
+ */
+export const CursorIndividualBilling = z.object({
+    /** True only with explicit opt-in (`AGENT_DEALER_CURSOR_INDIVIDUAL_CAPACITY=experimental`). */
+    enabled: z.boolean(),
+    /** True only when opted in AND a usable local credential was found. */
+    configured: z.boolean(),
+    /** Billing-cycle label exactly as reported (e.g. `September 2026`), never guessed. */
+    cycleLabel: z.string().nullable(),
+    /** Billing-cycle start as reported (ISO-8601, nullable). */
+    cycleStart: z.string().nullable(),
+    /** Billing-cycle reset/end as reported (ISO-8601, nullable). */
+    cycleEnd: z.string().nullable(),
+    /** Reported usage value/unit as reported (never normalized away). */
+    usageValue: z.number().nullable(),
+    usageUnit: z.string().nullable(),
+    /** Normalized remaining percent 0–100 when derivable; null renders N/A. */
+    remainingPercent: z.number().min(0).max(100).nullable(),
+    source: CapacitySource,
+    unavailableReason: CapacityUnavailableReason.nullable(),
+    /** When the backing dashboard read was observed (ISO-8601, nullable). */
+    observedAt: z.string().nullable(),
+    generatedAt: z.string(),
+});
+/** True when the individual billing snapshot carries current, renderable values. */
+export function isIndividualBillingKnown(b, nowMs = Date.now()) {
+    if (!b.enabled || !b.configured)
+        return false;
+    if (b.source === "unavailable" || b.unavailableReason !== null)
+        return false;
+    if (b.usageValue === null && b.remainingPercent === null)
+        return false;
+    if (b.observedAt) {
+        const obsMs = Date.parse(b.observedAt);
+        if (!Number.isFinite(obsMs) || obsMs > nowMs + 60_000)
+            return false;
+    }
+    return true;
+}
 /** True when the window carries a current, renderable remaining value. */
 export function isWindowKnown(w, nowMs = Date.now()) {
     if (w.remainingPercent === null)

package/bundle/shared/dist/runtime-capacity.test.js

@@ -17,6 +17,7 @@ function window(over = {}) {
         expiresAt: new Date(Date.now() + 3600_000).toISOString(),
         source: "supported_protocol",
         unavailableReason: null,
+        criticalRole: null,
         ...over,
     };
 }

package/bundle/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dealer/shared",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/dist/doctor.d.ts

@@ -1 +1,58 @@
 export declare function runDoctor(): Promise<number>;
+/** Which local login the Individual adapter would use, if any. */
+export type CursorIndividualLoginKind = "desktop" | "agent" | "none";
+export interface CursorIndividualLoginReport {
+    kind: CursorIndividualLoginKind;
+    /** Static operator-facing line — no paths, tokens, or user ids, ever. */
+    line: string;
+}
+export declare const CURSOR_INDIVIDUAL_LOGIN_LINES: Record<CursorIndividualLoginKind, string>;
+/**
+ * Map a diagnostics-safe credential status to the doctor line. Pure (no
+ * I/O): unit tests pin all three states plus the degraded inputs here.
+ */
+export declare function describeCursorIndividualLogin(status: {
+    present: boolean;
+    source: "desktop" | "agent" | null;
+} | null | undefined): CursorIndividualLoginReport;
+/**
+ * Probe the local Cursor logins the way the adapter would (desktop first,
+ * Agent auth as the fallback) and report the kind. Never throws, never
+ * prints secret material — the line is one of three static strings.
+ */
+export declare function checkCursorIndividualLogin(): Promise<CursorIndividualLoginReport>;
+/** Env override for the Claude cache file (tests/smoke). */
+export declare const CLAUDE_CAPACITY_CACHE_FILE_ENV = "AGENT_DEALER_CLAUDE_CACHE_FILE";
+/** Paid-fallback opt-in env and its only enabling value. */
+export declare const CLAUDE_CAPACITY_REFRESH_ENV = "AGENT_DEALER_CLAUDE_CAPACITY_REFRESH";
+export declare const CLAUDE_CAPACITY_REFRESH_PAID_VALUE = "paid-after-1h";
+/** Which local 5H/1W cache state the capacity ladder would read. */
+export type ClaudeCapacitySourceKind = "fresh" | "stale" | "missing";
+export interface ClaudeCapacitySourceReport {
+    kind: ClaudeCapacitySourceKind;
+    /** Static operator-facing line — age labels only, never values or ids. */
+    line: string;
+}
+/**
+ * Map a cache-file presence/age probe to the doctor line. Pure (no I/O):
+ * unit tests pin all three states here.
+ */
+export declare function describeClaudeCapacitySource(status: {
+    present: boolean;
+    ageMs: number | null;
+} | null | undefined): ClaudeCapacitySourceReport;
+/**
+ * Map the paid-fallback setting to an opt-in warning line, or null when the
+ * probe is disabled (the quiet default — no spend possible, nothing to say).
+ * Pure (no I/O): unit tests pin both states here.
+ */
+export declare function describeClaudeProbeOptIn(setting: string | undefined): string | null;
+/**
+ * Read the `cachedUsageUtilization.fetchedAtMs` timestamp out of Claude
+ * Code's config file (override first, then `~/.claude.json`) — the same key
+ * the server adapter normalizes, so doctor and the server always agree on
+ * freshness. File mtime is meaningless here: unrelated config writes touch
+ * it. Only the timestamp is read (never utilization values, ids, or
+ * siblings) and only an age label is reported. Never throws.
+ */
+export declare function checkClaudeCapacitySource(nowMs?: number): Promise<ClaudeCapacitySourceReport>;

package/dist/doctor.js

@@ -1,6 +1,8 @@
 import net from "node:net";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { cursorAuthIssueFromOutput } from "@agent-dealer/shared";
 import { claudeAvailable, cursorAvailable } from "./cli-check.js";
 import { loadProdEnvFile, prodEnvFilePath, prodHomeDir, resolveBundledListenPort, shortenHome, } from "./env.js";
@@ -105,6 +107,39 @@ export async function runDoctor() {
         else {
             console.warn("⚠ LINEAR_API_KEY not set — Linear inbox disabled");
         }
+        // NOT-268: Claude account capacity source status (informational only —
+        // never fails doctor). Reports whether Claude Code's own local 5H/1W
+        // cache exists and how old it is, plus whether the paid fallback probe
+        // is armed. Age labels only: never utilization values, prompts, tokens,
+        // or account ids.
+        try {
+            console.log((await checkClaudeCapacitySource()).line);
+            const probe = describeClaudeProbeOptIn(process.env.AGENT_DEALER_CLAUDE_CAPACITY_REFRESH);
+            if (probe)
+                console.warn(probe);
+        }
+        catch {
+            // Informational only: a broken probe must never fail doctor.
+        }
+        // NOT-250: experimental Cursor Individual dashboard adapter status
+        // (informational only — never fails doctor). NOT-267: when enabled,
+        // also report which local login the adapter would use — desktop first,
+        // Agent auth as the fallback. The probe only runs under the explicit
+        // opt-in, and prints kind labels only: never paths, tokens, or user ids.
+        if (process.env.AGENT_DEALER_CURSOR_INDIVIDUAL_CAPACITY === "experimental") {
+            console.warn("⚠ Cursor Individual capacity: EXPERIMENTAL dashboard adapter enabled " +
+                "(undocumented API, no support guarantee — unset AGENT_DEALER_CURSOR_INDIVIDUAL_CAPACITY to disable)");
+            try {
+                const login = await checkCursorIndividualLogin();
+                if (login.kind === "none")
+                    console.warn(login.line);
+                else
+                    console.log(login.line);
+            }
+            catch {
+                // Informational only: a broken probe must never fail doctor.
+            }
+        }
     }
     else {
         console.warn(`⚠ no config — run: agent-dealer setup`);
@@ -145,6 +180,182 @@ export async function runDoctor() {
     }
     return failed ? 1 : 0;
 }
+export const CURSOR_INDIVIDUAL_LOGIN_LINES = {
+    desktop: "✓ Cursor Individual capacity: desktop login found (experimental dashboard adapter can use it)",
+    agent: "✓ Cursor Individual capacity: Agent login found (fallback)",
+    none: "⚠ Cursor Individual capacity: no usable local login — log in to Cursor desktop or the Cursor Agent CLI",
+};
+/**
+ * Map a diagnostics-safe credential status to the doctor line. Pure (no
+ * I/O): unit tests pin all three states plus the degraded inputs here.
+ */
+export function describeCursorIndividualLogin(status) {
+    if (status?.present === true && status.source === "desktop") {
+        return { kind: "desktop", line: CURSOR_INDIVIDUAL_LOGIN_LINES.desktop };
+    }
+    if (status?.present === true && status.source === "agent") {
+        return { kind: "agent", line: CURSOR_INDIVIDUAL_LOGIN_LINES.agent };
+    }
+    return { kind: "none", line: CURSOR_INDIVIDUAL_LOGIN_LINES.none };
+}
+/**
+ * Load the server's credential-status reader without depending on the
+ * server's daemon entrypoint (which has side effects on import). The
+ * checkout layout (TypeScript source, run under tsx) is tried first, then
+ * the installed layout (built dist) — whichever answers wins. Returns null
+ * when neither is loadable; the caller then reports "no usable local
+ * login", never a crash. The loaded reader itself returns presence/source
+ * only — secret material never crosses this boundary by construction.
+ */
+async function loadCredentialStatusReader() {
+    const roots = [];
+    try {
+        const { resolveServerRoot } = await import("./paths.js");
+        roots.push(resolveServerRoot());
+    }
+    catch {
+        // The installed package entry (dist) may not be built in a checkout —
+        // the workspace fallback below still locates the source.
+    }
+    // Workspace-checkout fallback: packages/cli/src → packages/server.
+    // Absent in installed layouts (no src shipped), where existsSync skips it.
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    roots.push(path.resolve(here, "..", "..", "server"));
+    const candidates = roots.flatMap((serverRoot) => [
+        path.join(serverRoot, "src", "capacity", "cursor-individual-credentials.ts"),
+        path.join(serverRoot, "dist", "capacity", "cursor-individual-credentials.js"),
+    ]);
+    for (const file of candidates) {
+        try {
+            if (!fs.existsSync(file))
+                continue;
+            const mod = (await import(pathToFileURL(file).href));
+            if (typeof mod.cursorIndividualCredentialStatus === "function") {
+                return mod;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Probe the local Cursor logins the way the adapter would (desktop first,
+ * Agent auth as the fallback) and report the kind. Never throws, never
+ * prints secret material — the line is one of three static strings.
+ */
+export async function checkCursorIndividualLogin() {
+    try {
+        const reader = await loadCredentialStatusReader();
+        if (!reader)
+            return describeCursorIndividualLogin(null);
+        return describeCursorIndividualLogin(reader.cursorIndividualCredentialStatus());
+    }
+    catch {
+        return describeCursorIndividualLogin(null);
+    }
+}
+// ---------------------------------------------------------------------------
+// NOT-268: Claude capacity source reporting for doctor.
+// ---------------------------------------------------------------------------
+/** Env override for the Claude cache file (tests/smoke). */
+export const CLAUDE_CAPACITY_CACHE_FILE_ENV = "AGENT_DEALER_CLAUDE_CACHE_FILE";
+/** Paid-fallback opt-in env and its only enabling value. */
+export const CLAUDE_CAPACITY_REFRESH_ENV = "AGENT_DEALER_CLAUDE_CAPACITY_REFRESH";
+export const CLAUDE_CAPACITY_REFRESH_PAID_VALUE = "paid-after-1h";
+/**
+ * Map a cache-file presence/age probe to the doctor line. Pure (no I/O):
+ * unit tests pin all three states here.
+ */
+export function describeClaudeCapacitySource(status) {
+    if (status?.present === true && typeof status.ageMs === "number" && status.ageMs >= 0) {
+        if (status.ageMs < 60 * 60 * 1000) {
+            return {
+                kind: "fresh",
+                line: `✓ Claude capacity: local 5H/1W cache fresh (${formatCacheAge(status.ageMs)} old)`,
+            };
+        }
+        return {
+            kind: "stale",
+            line: `⚠ Claude capacity: local 5H/1W cache stale (${formatCacheAge(status.ageMs)} old — refreshes on the next Claude run)`,
+        };
+    }
+    return {
+        kind: "missing",
+        line: "⚠ Claude capacity: no local 5H/1W cache yet — run Claude Code once to populate it",
+    };
+}
+function formatCacheAge(ageMs) {
+    const minutes = Math.floor(ageMs / 60_000);
+    if (minutes < 1)
+        return "under a minute";
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
+/**
+ * Map the paid-fallback setting to an opt-in warning line, or null when the
+ * probe is disabled (the quiet default — no spend possible, nothing to say).
+ * Pure (no I/O): unit tests pin both states here.
+ */
+export function describeClaudeProbeOptIn(setting) {
+    if (setting === CLAUDE_CAPACITY_REFRESH_PAID_VALUE) {
+        return ("⚠ Claude capacity paid fallback: armed (one ≤$0.01 Haiku probe after 1h stale — " +
+            `unset ${CLAUDE_CAPACITY_REFRESH_ENV} to disable)`);
+    }
+    return null;
+}
+/**
+ * Read the `cachedUsageUtilization.fetchedAtMs` timestamp out of Claude
+ * Code's config file (override first, then `~/.claude.json`) — the same key
+ * the server adapter normalizes, so doctor and the server always agree on
+ * freshness. File mtime is meaningless here: unrelated config writes touch
+ * it. Only the timestamp is read (never utilization values, ids, or
+ * siblings) and only an age label is reported. Never throws.
+ */
+export async function checkClaudeCapacitySource(nowMs = Date.now()) {
+    try {
+        const override = process.env[CLAUDE_CAPACITY_CACHE_FILE_ENV]?.trim();
+        const file = override || path.join(process.env.HOME ?? os.homedir(), ".claude.json");
+        let text;
+        try {
+            text = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            return describeClaudeCapacitySource(null);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return describeClaudeCapacitySource(null);
+        }
+        const root = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+        // A bare cache object (no config envelope — the shape override fixtures
+        // use) is accepted as-is; otherwise only the subtree counts.
+        const subtreeRaw = root?.cachedUsageUtilization;
+        const subtree = subtreeRaw && typeof subtreeRaw === "object" && !Array.isArray(subtreeRaw)
+            ? subtreeRaw
+            : root;
+        const fetchedAtMs = subtree && typeof subtree.fetchedAtMs === "number" && Number.isFinite(subtree.fetchedAtMs)
+            ? subtree.fetchedAtMs
+            : null;
+        if (fetchedAtMs === null || fetchedAtMs <= 0 || fetchedAtMs > nowMs) {
+            return describeClaudeCapacitySource(null);
+        }
+        return describeClaudeCapacitySource({ present: true, ageMs: nowMs - fetchedAtMs });
+    }
+    catch {
+        return describeClaudeCapacitySource(null);
+    }
+}
 function isPortFree(port) {
     return new Promise((resolve) => {
         const server = net.createServer();

package/dist/doctor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/doctor.test.js

@@ -0,0 +1,246 @@
+// packages/cli/src/doctor.test.ts
+//
+// NOT-267: doctor reports which local login the experimental Cursor
+// Individual adapter would use — desktop, Agent fallback, or none — using
+// static lines only. Tests never touch the real local login: every case
+// points the resolution at temporary fixtures.
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import Database from "better-sqlite3";
+// Local mirror of the server module's env/key contract
+// (packages/server/src/capacity/cursor-individual-credentials.ts). A static
+// import is impossible — CLI `rootDir` cannot include server sources — so
+// the mirror is pinned against the live server module by the contract test
+// below: a rename there fails that test loudly instead of letting these
+// fixtures silently stop applying (and probe the real local login).
+const CURSOR_DESKTOP_ACCESS_TOKEN_KEY = "cursorAuth/accessToken";
+const CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV = "CURSOR_INDIVIDUAL_CREDENTIAL_FILE";
+const CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV = "CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE";
+const CURSOR_INDIVIDUAL_HOME_ENV = "CURSOR_INDIVIDUAL_HOME";
+test("fixture env/key names match the server module's live contract", async () => {
+    const { pathToFileURL, fileURLToPath } = await import("node:url");
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        path.resolve(here, "..", "..", "server", "src", "capacity", "cursor-individual-credentials.ts"),
+        path.resolve(here, "..", "..", "server", "dist", "capacity", "cursor-individual-credentials.js"),
+    ];
+    let mod = null;
+    for (const file of candidates) {
+        try {
+            if (!fs.existsSync(file))
+                continue;
+            mod = (await import(pathToFileURL(file).href));
+            break;
+        }
+        catch {
+            continue;
+        }
+    }
+    assert.ok(mod, "the server credentials module must be loadable for the contract pin");
+    assert.equal(mod.CURSOR_DESKTOP_ACCESS_TOKEN_KEY, CURSOR_DESKTOP_ACCESS_TOKEN_KEY);
+    assert.equal(mod.CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV, CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV);
+    assert.equal(mod.CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV, CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV);
+    assert.equal(mod.CURSOR_INDIVIDUAL_HOME_ENV, CURSOR_INDIVIDUAL_HOME_ENV);
+});
+import { CLAUDE_CAPACITY_CACHE_FILE_ENV, CLAUDE_CAPACITY_REFRESH_ENV, CLAUDE_CAPACITY_REFRESH_PAID_VALUE, CURSOR_INDIVIDUAL_LOGIN_LINES, checkClaudeCapacitySource, checkCursorIndividualLogin, describeClaudeCapacitySource, describeClaudeProbeOptIn, describeCursorIndividualLogin, } from "./doctor.js";
+const SECRET = "doctor-fixture-secret-must-never-print";
+const USER_ID = "user_doctor_fixture";
+function fixtureJwt(sub) {
+    const b64url = (obj) => Buffer.from(JSON.stringify(obj)).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    return `${b64url({ alg: "none" })}.${b64url({ sub })}.sig`;
+}
+let dir;
+const saved = {};
+beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-doctor-indiv-"));
+    for (const key of [
+        CURSOR_INDIVIDUAL_CREDENTIAL_FILE_ENV,
+        CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV,
+        CURSOR_INDIVIDUAL_HOME_ENV,
+        CLAUDE_CAPACITY_CACHE_FILE_ENV,
+    ]) {
+        saved[key] = process.env[key];
+        delete process.env[key];
+    }
+});
+afterEach(() => {
+    for (const [key, value] of Object.entries(saved)) {
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+});
+test("describe maps each credential state to its static line", () => {
+    assert.deepEqual(describeCursorIndividualLogin({ present: true, source: "desktop" }), {
+        kind: "desktop",
+        line: CURSOR_INDIVIDUAL_LOGIN_LINES.desktop,
+    });
+    assert.deepEqual(describeCursorIndividualLogin({ present: true, source: "agent" }), {
+        kind: "agent",
+        line: CURSOR_INDIVIDUAL_LOGIN_LINES.agent,
+    });
+    const degraded = [
+        { present: false, source: null },
+        { present: false, source: "desktop" },
+        { present: true, source: null },
+        null,
+        undefined,
+    ];
+    for (const state of degraded) {
+        assert.deepEqual(describeCursorIndividualLogin(state), {
+            kind: "none",
+            line: CURSOR_INDIVIDUAL_LOGIN_LINES.none,
+        });
+    }
+});
+test("the three lines name the three states and carry no paths or secrets", () => {
+    assert.match(CURSOR_INDIVIDUAL_LOGIN_LINES.desktop, /desktop login found/);
+    assert.match(CURSOR_INDIVIDUAL_LOGIN_LINES.agent, /Agent login found/);
+    assert.match(CURSOR_INDIVIDUAL_LOGIN_LINES.none, /no usable local login/);
+    for (const line of Object.values(CURSOR_INDIVIDUAL_LOGIN_LINES)) {
+        assert.ok(!line.includes("/"), "no filesystem paths in doctor output");
+        assert.ok(!line.includes(SECRET));
+    }
+});
+function fixtureDesktopDb(token) {
+    const file = path.join(dir, "state.vscdb");
+    const db = new Database(file);
+    try {
+        db.exec("CREATE TABLE ItemTable (key TEXT PRIMARY KEY, value TEXT)");
+        db.prepare("INSERT INTO ItemTable (key, value) VALUES (?, ?)").run(CURSOR_DESKTOP_ACCESS_TOKEN_KEY, token);
+    }
+    finally {
+        db.close();
+    }
+    process.env[CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV] = file;
+    return file;
+}
+test("check reports desktop login found for a fixture state.vscdb", async () => {
+    process.env[CURSOR_INDIVIDUAL_HOME_ENV] = dir;
+    const jwt = fixtureJwt(USER_ID);
+    const dbFile = fixtureDesktopDb(jwt);
+    const report = await checkCursorIndividualLogin();
+    assert.equal(report.kind, "desktop");
+    assert.equal(report.line, CURSOR_INDIVIDUAL_LOGIN_LINES.desktop);
+    assert.ok(!report.line.includes(jwt), "token material must not print");
+    assert.ok(!report.line.includes(dbFile), "database paths must not print");
+});
+test("check reports Agent login found when only the Agent auth file answers", async () => {
+    process.env[CURSOR_INDIVIDUAL_HOME_ENV] = dir;
+    process.env[CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV] = path.join(dir, "missing.vscdb");
+    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 report = await checkCursorIndividualLogin();
+    assert.equal(report.kind, "agent");
+    assert.equal(report.line, CURSOR_INDIVIDUAL_LOGIN_LINES.agent);
+    assert.ok(!report.line.includes(SECRET), "token material must not print");
+    assert.ok(!report.line.includes(agentFile), "credential paths must not print");
+});
+test("check reports no usable local login when neither source answers", async () => {
+    process.env[CURSOR_INDIVIDUAL_HOME_ENV] = dir;
+    process.env[CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV] = path.join(dir, "missing.vscdb");
+    const report = await checkCursorIndividualLogin();
+    assert.equal(report.kind, "none");
+    assert.equal(report.line, CURSOR_INDIVIDUAL_LOGIN_LINES.none);
+});
+// ---------------------------------------------------------------------------
+// NOT-268: Claude capacity source reporting. Tests never touch the real
+// ~/.claude.json: every case points the override at a temporary fixture.
+// ---------------------------------------------------------------------------
+test("fixture cache-file env name matches the server module's live contract", async () => {
+    const { fileURLToPath } = await import("node:url");
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        path.resolve(here, "..", "..", "server", "src", "capacity", "claude-local-cache.ts"),
+        path.resolve(here, "..", "..", "server", "dist", "capacity", "claude-local-cache.js"),
+    ];
+    const src = candidates.find((file) => fs.existsSync(file));
+    assert.ok(src, "the server cache module must exist for the contract pin");
+    const text = fs.readFileSync(src, "utf8");
+    assert.ok(text.includes(`"${CLAUDE_CAPACITY_CACHE_FILE_ENV}"`));
+    assert.ok(text.includes(`"${CLAUDE_CAPACITY_REFRESH_ENV}"`));
+    assert.ok(text.includes(`"${CLAUDE_CAPACITY_REFRESH_PAID_VALUE}"`));
+});
+test("describe maps each cache state to its static line", () => {
+    const fresh = describeClaudeCapacitySource({ present: true, ageMs: 5 * 60_000 });
+    assert.equal(fresh.kind, "fresh");
+    assert.match(fresh.line, /fresh/);
+    const stale = describeClaudeCapacitySource({ present: true, ageMs: 61 * 60_000 });
+    assert.equal(stale.kind, "stale");
+    assert.match(stale.line, /stale/);
+    const degraded = [
+        { present: false, ageMs: null },
+        { present: false, ageMs: 0 },
+        { present: true, ageMs: null },
+        { present: true, ageMs: -1 },
+        null,
+        undefined,
+    ];
+    for (const state of degraded) {
+        const report = describeClaudeCapacitySource(state);
+        assert.equal(report.kind, "missing");
+        assert.match(report.line, /no local 5H\/1W cache/);
+    }
+});
+test("probe opt-in line appears only under the exact paid value", () => {
+    assert.equal(describeClaudeProbeOptIn(undefined), null);
+    assert.equal(describeClaudeProbeOptIn(""), null);
+    assert.equal(describeClaudeProbeOptIn("off"), null);
+    assert.equal(describeClaudeProbeOptIn("auto"), null);
+    const armed = describeClaudeProbeOptIn(CLAUDE_CAPACITY_REFRESH_PAID_VALUE);
+    assert.ok(armed);
+    assert.match(armed, /armed/);
+    assert.match(armed, /≤\$0\.01/);
+});
+test("check reads fetchedAtMs from the config key, never mtime or the real home", async () => {
+    const now = Date.now();
+    // Full config envelope with sensitive siblings: freshness comes from the
+    // subtree timestamp even though mtime is two days old (mtime must be
+    // ignored — unrelated config writes touch it). The line must not leak
+    // the sibling values.
+    const freshFile = path.join(dir, "cached-fresh.json");
+    fs.writeFileSync(freshFile, JSON.stringify({
+        userID: "user-secret-must-never-print",
+        email: "someone@example.com",
+        cachedUsageUtilization: { fetchedAtMs: now - 5 * 60_000, accountUuid: "acct-secret" },
+    }));
+    const ancient = new Date(now - 2 * 24 * 3600_000);
+    fs.utimesSync(freshFile, ancient, ancient);
+    process.env[CLAUDE_CAPACITY_CACHE_FILE_ENV] = freshFile;
+    const fresh = await checkClaudeCapacitySource(now);
+    assert.equal(fresh.kind, "fresh");
+    assert.ok(!fresh.line.includes("user-secret-must-never-print"));
+    assert.ok(!fresh.line.includes("acct-secret"));
+    // Bare cache object (no envelope) still works; a brand-new mtime cannot
+    // rescue a stale timestamp.
+    const staleFile = path.join(dir, "cached-stale.json");
+    fs.writeFileSync(staleFile, JSON.stringify({ fetchedAtMs: 1 }));
+    const justNow = new Date(now);
+    fs.utimesSync(staleFile, justNow, justNow);
+    process.env[CLAUDE_CAPACITY_CACHE_FILE_ENV] = staleFile;
+    const stale = await checkClaudeCapacitySource(now);
+    assert.equal(stale.kind, "stale");
+    // Missing file, garbage JSON, future timestamp, and a config without the
+    // key all report missing.
+    process.env[CLAUDE_CAPACITY_CACHE_FILE_ENV] = path.join(dir, "missing.json");
+    assert.equal((await checkClaudeCapacitySource(now)).kind, "missing");
+    const garbageFile = path.join(dir, "cached-garbage.json");
+    fs.writeFileSync(garbageFile, "{not json");
+    process.env[CLAUDE_CAPACITY_CACHE_FILE_ENV] = garbageFile;
+    assert.equal((await checkClaudeCapacitySource(now)).kind, "missing");
+    const futureFile = path.join(dir, "cached-future.json");
+    fs.writeFileSync(futureFile, JSON.stringify({ cachedUsageUtilization: { fetchedAtMs: now + 60_000 } }));
+    process.env[CLAUDE_CAPACITY_CACHE_FILE_ENV] = futureFile;
+    assert.equal((await checkClaudeCapacitySource(now)).kind, "missing");
+    const keylessFile = path.join(dir, "cached-keyless.json");
+    fs.writeFileSync(keylessFile, JSON.stringify({ userID: "x", projects: {} }));
+    process.env[CLAUDE_CAPACITY_CACHE_FILE_ENV] = keylessFile;
+    assert.equal((await checkClaudeCapacitySource(now)).kind, "missing");
+    delete process.env[CLAUDE_CAPACITY_CACHE_FILE_ENV];
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-dealer",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Human control plane for agent execution — queue, plan approval, audit",
   "license": "MIT",
   "type": "module",