pi-cursor-sdk 0.4.0 → 0.5.2

package/dist/cursor-state.js

@@ -3,25 +3,23 @@ import { runCursorSessionAgentCleanupCommand } from "./cursor-session-agent-clea
 import { CURSOR_HTTP1_ENTRY_TYPE, getStoredCursorHttp1Enabled, isCursorHttp1EntryData, setCursorHttp1GlobalPreferenceAuthoritative, setStoredCursorHttp1Enabled, } from "./cursor-http1.js";
 import { buildCursorPiToolBridgeSnapshot, CURSOR_PI_TOOL_BRIDGE_ENV, resolveCursorPiToolBridgeEnabled, } from "./cursor-pi-tool-bridge-snapshot.js";
 import { CURSOR_SETTING_SOURCES_ENV, DEFAULT_CURSOR_SETTING_SOURCES, resolveCursorSettingSources, } from "./cursor-setting-sources.js";
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
 import { isCursorModel } from "./cursor-model.js";
 import { registerCursorModelLifecycle } from "./cursor-model-lifecycle.js";
 import { asRecord } from "./cursor-record-utils.js";
-import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import { getCursorSessionScopeSnapshot, getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import { cursorSettingsScopeForContext, getCursorSessionSettings, registerCursorSessionSettings, resetCursorSessionSettingsForTests } from "./cursor-session-settings.js";
 import { refreshSessionCursorAgentConfig } from "./cursor-session-agent.js";
 import { getCursorModelMetadata } from "./model-discovery.js";
-import { cursorFastDefaultsFromConfig, getCursorSdkUserConfigPath, loadCursorSdkUserConfig, mergeCursorSdkConfigForUpdate, resolveCursorFastDefault, updateCursorSdkConfig, } from "./cursor-config.js";
+import { cursorFastDefaultsFromConfig, getCursorSdkUserConfigPath, loadCursorSdkUserConfig, mergeCursorSdkConfigForUpdate, resolveCursorFastDefault, resolveCursorLocalStoreRoot, updateCursorSdkConfig, } from "./cursor-config.js";
 import { CURSOR_RUNTIME_ENTRY_TYPE, formatCursorStatus, registerCursorCloudRuntimeControls, resetCursorRuntimeStateForTests, resolveCursorStatusRuntime, restoreCursorCliState, restoreSessionCursorRuntimeState, } from "./cursor-runtime-state.js";
 export { consumeCursorLocalForceOverride, getCursorCliConfig, getCursorSessionConfig, } from "./cursor-runtime-state.js";
+export const CURSOR_FOOTER_ENV = "PI_CURSOR_FOOTER";
 const FAST_ENTRY_TYPE = "cursor-fast-state";
 const MODE_ENTRY_TYPE = "cursor-mode-state";
 const DEFAULT_CURSOR_AGENT_MODE = "agent";
-const sessionFastPreferences = new Map();
 const authoritativeGlobalFastPreferenceIds = new Set();
 let globalFastPreferences = new Map();
-let cliForceFast = false;
-let cliForceNoFast = false;
-let sessionCursorAgentMode;
-let cliCursorModeState = { kind: "unset" };
 const invalidCursorModeNotifiedSessionScopeKeys = new Set();
 export function isCursorAgentMode(value) {
     return value === "agent" || value === "plan";
@@ -64,7 +62,8 @@ function saveGlobalCursorHttp1Enabled(enabled) {
         local: { useHttp1ForAgent: enabled },
     }), { newFileMode: 0o600 });
 }
-function restoreSessionFastPreferences(branch) {
+function restoreSessionFastPreferences(branch, scopeKey) {
+    const sessionFastPreferences = getCursorSessionSettings(scopeKey).fast;
     sessionFastPreferences.clear();
     for (const entry of branch) {
         if (entry.type !== "custom" || entry.customType !== FAST_ENTRY_TYPE)
@@ -76,30 +75,32 @@ function restoreSessionFastPreferences(branch) {
         }
     }
 }
-function restoreSessionCursorMode(branch) {
-    sessionCursorAgentMode = undefined;
+function restoreSessionCursorMode(branch, scopeKey) {
+    const state = getCursorSessionSettings(scopeKey);
+    state.mode = undefined;
     for (const entry of branch) {
         if (entry.type !== "custom" || entry.customType !== MODE_ENTRY_TYPE)
             continue;
         if (isCursorModeEntryData(entry.data)) {
-            sessionCursorAgentMode = entry.data.mode;
+            state.mode = entry.data.mode;
         }
     }
 }
 function restoreSessionCursorPreferences(ctx) {
     const branch = ctx.sessionManager.getBranch();
-    restoreSessionCursorRuntimeState(branch);
-    restoreSessionFastPreferences(branch);
-    restoreSessionCursorMode(branch);
-    restoreSessionCursorHttp1(branch);
-}
-function restoreSessionCursorHttp1(branch) {
-    setStoredCursorHttp1Enabled(undefined);
+    const scopeKey = cursorSettingsScopeForContext(ctx);
+    restoreSessionCursorRuntimeState(branch, scopeKey);
+    restoreSessionFastPreferences(branch, scopeKey);
+    restoreSessionCursorMode(branch, scopeKey);
+    restoreSessionCursorHttp1(branch, scopeKey);
+}
+function restoreSessionCursorHttp1(branch, scopeKey) {
+    setStoredCursorHttp1Enabled(undefined, scopeKey);
     for (const entry of branch) {
         if (entry.type !== "custom" || entry.customType !== CURSOR_HTTP1_ENTRY_TYPE)
             continue;
         if (isCursorHttp1EntryData(entry.data)) {
-            setStoredCursorHttp1Enabled(entry.data.enabled);
+            setStoredCursorHttp1Enabled(entry.data.enabled, scopeKey);
         }
     }
 }
@@ -113,7 +114,8 @@ function getMapFastPreference(map, metadata) {
     const preferenceModelId = getFastPreferenceModelId(metadata);
     return map.get(preferenceModelId) ?? (preferenceModelId !== metadata.baseModelId ? map.get(metadata.baseModelId) : undefined);
 }
-function getEffectiveFast(modelId) {
+function getEffectiveFast(modelId, scopeKey) {
+    const { forceNoFast: cliForceNoFast, forceFast: cliForceFast } = getCursorSessionSettings(scopeKey).cli;
     const metadata = getCursorModelMetadata(modelId);
     if (!metadata?.supportsFast)
         return undefined;
@@ -123,7 +125,7 @@ function getEffectiveFast(modelId) {
         aliasOverride: metadata.fastOverride,
         sessionValue: authoritativeGlobalFastPreferenceIds.has(getFastPreferenceModelId(metadata))
             ? undefined
-            : getMapFastPreference(sessionFastPreferences, metadata),
+            : getMapFastPreference(getCursorSessionSettings(scopeKey).fast, metadata),
         userValue: getMapFastPreference(globalFastPreferences, metadata),
         modelDefault: metadata.defaultFast,
     }).value;
@@ -131,40 +133,41 @@ function getEffectiveFast(modelId) {
 function formatInvalidCursorMode(raw) {
     return `Invalid --cursor-mode "${raw}". Use "agent" or "plan".`;
 }
-export function getStoredCursorAgentMode() {
-    return sessionCursorAgentMode ?? DEFAULT_CURSOR_AGENT_MODE;
+export function getStoredCursorAgentMode(scopeKey) {
+    return getCursorSessionSettings(scopeKey).mode ?? DEFAULT_CURSOR_AGENT_MODE;
 }
-export function resolveCursorAgentMode() {
+export function resolveCursorAgentMode(scopeKey) {
+    const cliCursorModeState = getCursorSessionSettings(scopeKey).cli.mode;
     switch (cliCursorModeState.kind) {
         case "valid":
             return { kind: "valid", mode: cliCursorModeState.mode };
         case "invalid":
             return { kind: "invalid", raw: cliCursorModeState.raw, message: cliCursorModeState.message };
         case "unset":
-            return { kind: "valid", mode: getStoredCursorAgentMode() };
+            return { kind: "valid", mode: getStoredCursorAgentMode(scopeKey) };
     }
 }
-export function getCursorProviderAgentModeOrThrow() {
-    const resolution = resolveCursorAgentMode();
+export function getCursorProviderAgentModeOrThrow(scopeKey) {
+    const resolution = resolveCursorAgentMode(scopeKey);
     if (resolution.kind === "invalid")
         throw new Error(resolution.message);
     return resolution.mode;
 }
 function updateCursorStatus(ctx, model = ctx.model) {
-    if (!model || !isCursorModel(model)) {
+    if (!model || !isCursorModel(model) || !parseEnvBoolean(process.env[CURSOR_FOOTER_ENV], true)) {
         ctx.ui.setStatus("cursor", undefined);
         return;
     }
     const metadata = getCursorModelMetadata(model.id);
     const resolution = resolveCursorStatusRuntime(ctx);
-    const modeResolution = resolveCursorAgentMode();
+    const modeResolution = resolveCursorAgentMode(cursorSettingsScopeForContext(ctx));
     const mode = modeResolution.kind === "invalid" ? "invalid" : modeResolution.mode;
     if (resolution.kind === "invalid") {
         ctx.ui.setStatus("cursor", formatCursorStatus("invalid", undefined, mode));
         return;
     }
     const runtime = resolution.runtime.value;
-    const fast = runtime === "cloud" ? undefined : metadata?.supportsFast ? getEffectiveFast(model.id) : undefined;
+    const fast = runtime === "cloud" ? undefined : metadata?.supportsFast ? getEffectiveFast(model.id, cursorSettingsScopeForContext(ctx)) : undefined;
     ctx.ui.setStatus("cursor", formatCursorStatus(runtime, fast, mode, resolution.useHttp1ForAgent.value));
 }
 function getCurrentCursorMetadata(ctx) {
@@ -181,7 +184,8 @@ function restoreMapValue(map, key, previous) {
         map.set(key, previous);
     }
 }
-function persistFastPreference(pi, modelId, fast) {
+function persistFastPreference(pi, modelId, fast, scopeKey) {
+    const sessionFastPreferences = getCursorSessionSettings(scopeKey).fast;
     const previousSession = sessionFastPreferences.get(modelId);
     const previousGlobal = globalFastPreferences.get(modelId);
     sessionFastPreferences.set(modelId, fast);
@@ -204,25 +208,26 @@ function persistFastPreference(pi, modelId, fast) {
         return error;
     }
 }
-function persistCursorModePreference(pi, mode) {
-    const previousMode = sessionCursorAgentMode;
-    sessionCursorAgentMode = mode;
+function persistCursorModePreference(pi, mode, scopeKey) {
+    const state = getCursorSessionSettings(scopeKey);
+    const previousMode = state.mode;
+    state.mode = mode;
     try {
         pi.appendEntry(MODE_ENTRY_TYPE, { mode });
     }
     catch (error) {
-        sessionCursorAgentMode = previousMode;
+        state.mode = previousMode;
         throw error;
     }
 }
-function persistCursorHttp1Preference(pi, enabled) {
-    const previousSession = getStoredCursorHttp1Enabled();
-    setStoredCursorHttp1Enabled(enabled);
+function persistCursorHttp1Preference(pi, enabled, scopeKey) {
+    const previousSession = getStoredCursorHttp1Enabled(scopeKey);
+    setStoredCursorHttp1Enabled(enabled, scopeKey);
     try {
         saveGlobalCursorHttp1Enabled(enabled);
     }
     catch (error) {
-        setStoredCursorHttp1Enabled(previousSession);
+        setStoredCursorHttp1Enabled(previousSession, scopeKey);
         throw error;
     }
     try {
@@ -235,24 +240,25 @@ function persistCursorHttp1Preference(pi, enabled) {
         return error;
     }
 }
-function restoreCliCursorMode(raw) {
-    cliCursorModeState = { kind: "unset" };
+function restoreCliCursorMode(raw, scopeKey) {
+    const cli = getCursorSessionSettings(scopeKey).cli;
+    cli.mode = { kind: "unset" };
     if (raw === undefined || raw === "" || raw === false)
         return;
     const parsed = parseCursorAgentMode(raw);
     if (parsed) {
-        cliCursorModeState = { kind: "valid", mode: parsed };
+        cli.mode = { kind: "valid", mode: parsed };
         return;
     }
     const rawText = String(raw);
     const message = formatInvalidCursorMode(rawText);
-    cliCursorModeState = { kind: "invalid", raw: rawText, message };
+    cli.mode = { kind: "invalid", raw: rawText, message };
 }
 function notifyInvalidCursorModeIfCursorActive(ctx) {
-    const modeResolution = resolveCursorAgentMode();
+    const modeResolution = resolveCursorAgentMode(cursorSettingsScopeForContext(ctx));
     if (modeResolution.kind !== "invalid" || !ctx.hasUI || ctx.mode !== "tui")
         return;
-    const scopeKey = getCursorSessionScopeKey();
+    const scopeKey = cursorSettingsScopeForContext(ctx) ?? getCursorSessionScopeKey();
     if (invalidCursorModeNotifiedSessionScopeKeys.has(scopeKey))
         return;
     invalidCursorModeNotifiedSessionScopeKeys.add(scopeKey);
@@ -293,10 +299,11 @@ function emitCursorToolsDebugReport(pi, ctx) {
     }
     console.log(report);
 }
-export function getEffectiveFastForModelId(modelId) {
-    return getEffectiveFast(modelId);
+export function getEffectiveFastForModelId(modelId, scopeKey) {
+    return getEffectiveFast(modelId, scopeKey);
 }
 export function registerCursorRuntimeControls(pi) {
+    registerCursorSessionSettings(pi);
     registerCursorCloudRuntimeControls(pi, { refreshStatus: updateCursorStatus });
     pi.registerFlag("cursor-fast", {
         description: "Force Cursor fast mode for this run when the selected Cursor model supports it",
@@ -322,6 +329,7 @@ export function registerCursorRuntimeControls(pi) {
                 ctx.ui.notify(`Fast mode not supported by ${modelName}`, "info");
                 return;
             }
+            const { forceNoFast: cliForceNoFast, forceFast: cliForceFast } = getCursorSessionSettings(cursorSettingsScopeForContext(ctx)).cli;
             if (cliForceNoFast) {
                 ctx.ui.notify("Cursor fast is forced off by --cursor-no-fast", "info");
                 return;
@@ -336,11 +344,11 @@ export function registerCursorRuntimeControls(pi) {
                 return;
             }
             const preferenceModelId = getFastPreferenceModelId(metadata);
-            const current = getEffectiveFast(metadata.piModelId) ?? false;
+            const current = getEffectiveFast(metadata.piModelId, cursorSettingsScopeForContext(ctx)) ?? false;
             const next = !current;
             let appendError;
             try {
-                appendError = persistFastPreference(pi, preferenceModelId, next);
+                appendError = persistFastPreference(pi, preferenceModelId, next, cursorSettingsScopeForContext(ctx));
             }
             catch (error) {
                 updateCursorStatus(ctx);
@@ -389,7 +397,7 @@ export function registerCursorRuntimeControls(pi) {
             }
             let appendError;
             try {
-                appendError = persistCursorHttp1Preference(pi, next);
+                appendError = persistCursorHttp1Preference(pi, next, cursorSettingsScopeForContext(ctx));
             }
             catch (error) {
                 updateCursorStatus(ctx);
@@ -407,7 +415,8 @@ export function registerCursorRuntimeControls(pi) {
     pi.registerCommand("cursor-local-resume-cleanup", {
         description: "Dry-run or delete recorded superseded local Cursor SDK agents",
         handler: async (args, ctx) => {
-            await runCursorSessionAgentCleanupCommand(pi, args, ctx);
+            const storeRoot = resolveCursorLocalStoreRoot({ user: loadCursorSdkUserConfig() }).value;
+            await runCursorSessionAgentCleanupCommand(pi, args, ctx, storeRoot);
         },
     });
     pi.registerCommand("cursor-refresh-config", {
@@ -418,7 +427,7 @@ export function registerCursorRuntimeControls(pi) {
                 return;
             }
             try {
-                const result = await refreshSessionCursorAgentConfig();
+                const result = await refreshSessionCursorAgentConfig(getCursorSessionScopeSnapshot(pi).scopeKey);
                 const messages = {
                     reloaded: "Cursor SDK agent config refreshed.",
                     "no-agent": "No Cursor SDK agent exists yet; config will load on the next Cursor run.",
@@ -438,7 +447,7 @@ export function registerCursorRuntimeControls(pi) {
             const usage = "Usage: /cursor-mode agent|plan";
             const mode = parseCursorAgentMode(args);
             if (!args.trim()) {
-                const modeResolution = resolveCursorAgentMode();
+                const modeResolution = resolveCursorAgentMode(cursorSettingsScopeForContext(ctx));
                 if (modeResolution.kind === "invalid") {
                     ctx.ui.notify(`${modeResolution.message} ${usage}`, "error");
                 }
@@ -451,15 +460,17 @@ export function registerCursorRuntimeControls(pi) {
                 ctx.ui.notify(`Invalid Cursor mode "${args.trim()}". ${usage}`, "error");
                 return;
             }
+            const cli = getCursorSessionSettings(cursorSettingsScopeForContext(ctx)).cli;
+            const cliCursorModeState = cli.mode;
             if (cliCursorModeState.kind === "valid") {
                 ctx.ui.notify(`Cursor mode is forced to ${cliCursorModeState.mode} by --cursor-mode`, "info");
                 return;
             }
             const clearedInvalidCliMode = cliCursorModeState.kind === "invalid";
             try {
-                persistCursorModePreference(pi, mode);
+                persistCursorModePreference(pi, mode, cursorSettingsScopeForContext(ctx));
                 if (clearedInvalidCliMode)
-                    cliCursorModeState = { kind: "unset" };
+                    cli.mode = { kind: "unset" };
             }
             catch (error) {
                 updateCursorStatus(ctx);
@@ -481,11 +492,13 @@ export function registerCursorRuntimeControls(pi) {
             authoritativeGlobalFastPreferenceIds.clear();
             setCursorHttp1GlobalPreferenceAuthoritative(false);
             globalFastPreferences = loadGlobalFastPreferences();
-            cliForceFast = pi.getFlag("cursor-fast") === true;
-            cliForceNoFast = pi.getFlag("cursor-no-fast") === true;
-            restoreCursorCliState(pi);
+            const scopeKey = cursorSettingsScopeForContext(ctx);
+            const cli = getCursorSessionSettings(scopeKey).cli;
+            cli.forceFast = pi.getFlag("cursor-fast") === true;
+            cli.forceNoFast = pi.getFlag("cursor-no-fast") === true;
+            restoreCursorCliState(pi, scopeKey);
             restoreSessionCursorPreferences(ctx);
-            restoreCliCursorMode(pi.getFlag("cursor-mode"));
+            restoreCliCursorMode(pi.getFlag("cursor-mode"), scopeKey);
         },
         sync: (ctx) => {
             if (isCursorModel(ctx.model))
@@ -495,10 +508,10 @@ export function registerCursorRuntimeControls(pi) {
     });
 }
 function resetCursorModeStateForTests() {
-    sessionCursorAgentMode = undefined;
+    resetCursorSessionSettingsForTests();
     setCursorHttp1GlobalPreferenceAuthoritative(false);
     setStoredCursorHttp1Enabled(undefined);
-    cliCursorModeState = { kind: "unset" };
+    getCursorSessionSettings().cli.mode = { kind: "unset" };
     resetCursorRuntimeStateForTests();
     invalidCursorModeNotifiedSessionScopeKeys.clear();
     authoritativeGlobalFastPreferenceIds.clear();
@@ -511,9 +524,9 @@ export const __testUtils = {
     DEFAULT_CURSOR_AGENT_MODE,
     getConfigPath,
     loadGlobalFastPreferences,
-    sessionFastPreferences,
-    getSessionCursorAgentMode: () => sessionCursorAgentMode,
-    getCliCursorAgentMode: () => (cliCursorModeState.kind === "valid" ? cliCursorModeState.mode : undefined),
-    getCliCursorModeState: () => cliCursorModeState,
+    get sessionFastPreferences() { return getCursorSessionSettings().fast; },
+    getSessionCursorAgentMode: () => getCursorSessionSettings().mode,
+    getCliCursorAgentMode: () => { const mode = getCursorSessionSettings().cli.mode; return mode.kind === "valid" ? mode.mode : undefined; },
+    getCliCursorModeState: () => getCursorSessionSettings().cli.mode,
     resetCursorModeStateForTests,
 };

package/dist/cursor-tool-manifest.js

@@ -1,7 +1,7 @@
 import { parseEnvBoolean } from "./cursor-env-boolean.js";
 export const CURSOR_TOOL_MANIFEST_ENV = "PI_CURSOR_TOOL_MANIFEST";
 /**
- * Representative @cursor/sdk@1.0.32 local-agent ToolType values; actual exposure can vary by run.
+ * Representative Cursor SDK local-agent ToolType values; actual exposure can vary by run.
  * See docs/cursor-native-tool-replay.md#sdk-tooltype-replay-matrix.
  */
 export const CURSOR_HOST_TOOL_MANIFEST_SUMMARY = "read/shell/search/edit/write and other host tools when Cursor exposes them";

package/dist/cursor-usage-accounting.js

@@ -1,3 +1,4 @@
+import { calculateCost } from "@earendil-works/pi-ai";
 import { CURSOR_APPROX_CHARS_PER_TOKEN, CURSOR_IMAGE_TOKEN_ESTIMATE, estimateCursorContextTokens, estimateCursorTextTokens, } from "./context.js";
 import { asRecord, getNumber } from "./cursor-record-utils.js";
 function getPromptInputTokenBudget(model) {
@@ -81,86 +82,28 @@ export function applyCursorSdkUsage(partial, turnUsage) {
     partial.usage.output = turnUsage.outputTokens;
     partial.usage.cacheRead = turnUsage.cacheReadTokens;
     partial.usage.cacheWrite = turnUsage.cacheWriteTokens;
-    // totalTokens is context occupancy (full prompt + output), not the sum of spend components alone.
+    // Full prompt + output equals the sum of Pi's disjoint components.
     partial.usage.totalTokens = turnUsage.inputTokens + turnUsage.outputTokens;
 }
-function isCompatibleCursorAssistantMeasurement(assistant, model) {
-    return assistant.api === model.api && assistant.provider === model.provider && assistant.model === model.id;
-}
-function getLatestCompactionBoundary(context) {
-    for (let index = context.messages.length - 1; index >= 0; index -= 1) {
-        const message = context.messages[index];
-        if (message.role !== "compactionSummary")
-            continue;
-        const tokensBefore = message.tokensBefore;
-        return {
-            index,
-            tokensBefore: Number.isFinite(tokensBefore) && tokensBefore !== undefined && tokensBefore > 0 ? Math.floor(tokensBefore) : undefined,
-        };
-    }
-    return undefined;
-}
-function getLastAcceptedContextOccupancy(context, model) {
-    const boundary = getLatestCompactionBoundary(context);
-    for (let index = context.messages.length - 1; index >= 0; index -= 1) {
-        if (boundary && index < boundary.index)
-            break;
-        const message = context.messages[index];
-        if (message.role !== "assistant" || !("usage" in message))
-            continue;
-        const assistant = message;
-        if (assistant.stopReason === "aborted" || assistant.stopReason === "error" || !assistant.usage)
-            continue;
-        if (!isCompatibleCursorAssistantMeasurement(assistant, model))
-            continue;
-        const { usage } = assistant;
-        const total = usage.totalTokens || usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
-        if (!Number.isFinite(total) || total <= 0 || total > model.contextWindow)
-            continue;
-        if (boundary?.tokensBefore !== undefined && total >= boundary.tokensBefore)
-            continue;
-        return total;
-    }
-    return 0;
-}
-export function applyCursorApproximateUsage(partial, model, context, sessionInputTokens) {
+export function applyCursorApproximateUsage(partial, model, context, sessionInputTokens, occupancyFloor) {
     const outputTokens = estimateCursorAssistantSessionOutputTokens(partial);
-    partial.usage.input = Math.max(0, sessionInputTokens);
+    const floor = occupancyFloor !== undefined && Number.isFinite(occupancyFloor) && occupancyFloor > 0 && occupancyFloor <= model.contextWindow ? occupancyFloor : 0;
+    const totalTokens = Math.max(Math.max(0, sessionInputTokens) + outputTokens, estimateCursorContextTotalTokens(partial, model, context), floor);
+    // Estimated prompt components describe the same occupancy as totalTokens.
+    partial.usage.input = totalTokens - outputTokens;
     partial.usage.output = outputTokens;
     partial.usage.cacheRead = 0;
     partial.usage.cacheWrite = 0;
-    // Never report less occupancy than the last compatible same-model in-window assistant measurement.
-    partial.usage.totalTokens = Math.max(partial.usage.input + partial.usage.output, estimateCursorContextTotalTokens(partial, model, context), getLastAcceptedContextOccupancy(context, model));
-}
-function applyCursorOccupancyEstimate(partial, model, context) {
-    partial.usage.totalTokens = Math.max(estimateCursorContextTotalTokens(partial, model, context), getLastAcceptedContextOccupancy(context, model));
-}
-function isCurrentLocalOccupancy(turn, model, context) {
-    if (!isCursorSdkUsageSafeForPiMessage(turn, model))
-        return false;
-    const tokensBefore = getLatestCompactionBoundary(context)?.tokensBefore;
-    return tokensBefore === undefined || turn.inputTokens + turn.outputTokens < tokensBefore;
-}
-function applyResolvedCursorOccupancy(partial, model, context, localTurn) {
-    if (localTurn && isCurrentLocalOccupancy(localTurn, model, context)) {
-        partial.usage.totalTokens = localTurn.inputTokens + localTurn.outputTokens;
-        return;
-    }
-    applyCursorOccupancyEstimate(partial, model, context);
+    partial.usage.totalTokens = totalTokens;
 }
 export function applyCursorUsage(partial, model, context, sessionInputTokens, sdkUsage) {
-    const billed = sdkUsage?.billed;
     const localTurn = sdkUsage?.runtime === "local" ? sdkUsage.turn : undefined;
-    if (billed && isCursorSdkUsagePartitionSafe(billed, model)) {
-        applyCursorSdkUsage(partial, billed);
-        applyResolvedCursorOccupancy(partial, model, context, localTurn);
-        return;
-    }
-    // Only local raw turn-ended usage has a captured full-prompt/cache-partition occupancy contract.
     if (localTurn && isCursorSdkUsageSafeForPiMessage(localTurn, model)) {
+        // Fresh LOCAL occupancy supersedes any previous request-provenance floor.
         applyCursorSdkUsage(partial, localTurn);
-        applyResolvedCursorOccupancy(partial, model, context, localTurn);
-        return;
     }
-    applyCursorApproximateUsage(partial, model, context, sessionInputTokens);
+    else {
+        applyCursorApproximateUsage(partial, model, context, sessionInputTokens, sdkUsage?.occupancyFloor);
+    }
+    calculateCost(model, partial.usage);
 }

package/dist/cursor-usage-command.js

@@ -0,0 +1,89 @@
+import { closeSync, constants, fsyncSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createRegularFileExclusive } from "./cursor-durable-fs.js";
+import { fetchCursorSdkAgentUsage } from "./cursor-sdk-billed-usage.js";
+import { resolveCursorApiKey } from "./cursor-api-key.js";
+import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { readCursorUsageView, refreshCursorUsageView } from "./cursor-usage-ledger.js";
+const HELP = [
+    "/cursor-usage — current branch telemetry (native footer unchanged)",
+    "/cursor-usage refresh — public getUsage only; up to 32 agents, 5 seconds each; no model sends or automatic polling",
+    "/cursor-usage export <new-file.json> — exclusive private JSON export; never overwrites a file",
+    "/cursor-usage help — this help",
+    "Storage ceiling: 16MiB per origin session. At the ceiling or after an incomplete trailing frame, new sends fail before spend. A torn tail is retained unchanged; view/export preserve validated prior frames and mark accounting incomplete. Malformed complete frames remain fail-closed.",
+    "Recovery: export readable facts and retain the original journal/session unchanged. Use Pi's native fork to preserve the conversation under a new session origin, or start a new native session. Never delete, truncate, or rewrite journals or native sessions to continue the old origin.",
+    "Other-branch facts have valid native claims elsewhere in this session; unclaimed facts have no surviving claim here and are not branch usage. Inherited records without a claim in this session retain unknown ownership; no sibling sessions are scanned. Fileless sessions are ephemeral.",
+].join("\n");
+export function renderCursorUsageView(view) {
+    return [
+        `Cursor usage — ${view.durability}; persistence ${view.persistenceStatus}; current branch telemetry`,
+        view.nativeConfiguredEstimates,
+        `Recorded corrected LOCAL raw tokens: ${view.correctedRawTotal.totalTokens} (input ${view.correctedRawTotal.inputTokens}, cache read ${view.correctedRawTotal.cacheReadTokens}, cache write ${view.correctedRawTotal.cacheWriteTokens}, output ${view.correctedRawTotal.outputTokens}).`,
+        `Original telemetry: ${view.records.filter(record => record.kind === "raw").length} raw turns; normalization unavailable/invalid: ${view.records.filter(record => record.kind === "raw" && !record.corrected).length}; ${view.records.filter(record => record.kind === "terminal").length} terminal facts (not added to raw).`,
+        `Other-branch journal records: ${view.otherBranchRecords.length}; unclaimed records: ${view.unclaimedRecords.length}; inherited records with unknown claim ownership: ${view.inheritedUnclaimedRecords.length}; inherited journal gaps: ${view.lineageGaps.length}; incomplete trailing frames: ${view.incompleteJournals.length}. Export retains these facts without billing them to this branch.`,
+        ...view.lineageGaps,
+        ...view.agents.slice(0, 32).map(agent => {
+            const missing = agent.billingStatus === "ambiguous-shared-lineage" ? "ambiguous" : agent.billingStatus === "unavailable" ? "unavailable" : agent.billingStatus === "pending" ? "pending" : "unknown";
+            const remainder = agent.billingStatus === "ambiguous-shared-lineage" ? "ambiguous" : agent.observationsByOrigin.some(observation => observation.incompleteHistory) ? "unknown (incomplete run history)" : agent.aggregateOnly?.totalTokens ?? missing;
+            return [
+                `${agent.agentId}: ${agent.billingStatus}${agent.unknownHistory ? "; unknown historical baseline" : ""}`,
+                agent.sharedAcrossBranches ? "; shared lineage, not attributable to this branch" : "; whole-agent facts, no client-run billing join",
+                `. Latest known billed tokens: ${agent.latestAggregate?.usage.totalTokens ?? missing}; SDK charged cents: ${agent.latestAggregate ? agent.latestAggregate.cost?.chargedCents ?? "not reported" : missing}; aggregate-only tokens: ${remainder}.`,
+                ...agent.observationsByOrigin.map(observation => {
+                    const absent = observation.lastAttempt.status === "unavailable" ? "unavailable" : "unknown";
+                    return ` Origin ${observation.origin.sessionId}: ${observation.lastAttempt.status}${observation.incompleteHistory ? "; incomplete run history" : ""}; latest known billed tokens ${observation.latestAggregate?.usage.totalTokens ?? absent}; charged cents ${observation.latestAggregate ? observation.latestAggregate.cost?.chargedCents ?? "not reported" : absent}.`;
+                }),
+            ].join("");
+        }),
+        ...(view.agents.length > 32 ? [`${view.agents.length - 32} further agents retained in export.`] : []),
+        "Snapshots are observations, not final invoices. Multiple origin journals have no qualified global revision ordering. Cloud raw normalization is unqualified.",
+        `Journal ceiling: ${view.journalLimit}. See /cursor-usage help for recovery. Export contains no prompts or tool content.`,
+    ].join("\n");
+}
+export function registerCursorUsageCommand(pi) {
+    pi.registerCommand("cursor-usage", {
+        description: "View Cursor telemetry; refresh public billing or export to a new JSON file",
+        handler: async (args, ctx) => {
+            const show = (message, error = false) => {
+                if (ctx.hasUI)
+                    ctx.ui.notify(message, error ? "error" : "info");
+                else
+                    process.stderr.write(`${message}\n`); // Keep non-UI stdout/RPC framing untouched.
+            };
+            try {
+                const argument = args.trim();
+                if (["help", "-h", "--help"].includes(argument)) {
+                    show(HELP);
+                    return;
+                }
+                if (argument && argument !== "refresh" && !argument.startsWith("export ")) {
+                    show(HELP, true);
+                    return;
+                }
+                let view = readCursorUsageView(pi, ctx);
+                if (argument === "refresh") {
+                    const { Agent } = await loadCursorSdk();
+                    const apiKey = resolveCursorApiKey(await ctx.modelRegistry.getApiKeyForProvider("cursor"));
+                    view = await refreshCursorUsageView(pi, ctx, agentId => fetchCursorSdkAgentUsage({ getUsage: () => Agent.getUsage(agentId, { apiKey }) }));
+                }
+                else if (argument.startsWith("export ")) {
+                    const path = resolve(ctx.cwd, argument.slice(7).trim());
+                    const fd = createRegularFileExclusive(path, constants.O_WRONLY, 0o600);
+                    try {
+                        writeFileSync(fd, `${JSON.stringify(view, null, 2)}\n`);
+                        fsyncSync(fd);
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                    show(`Cursor usage exported to ${path}.`);
+                    return;
+                }
+                show(renderCursorUsageView(view));
+            }
+            catch {
+                show("Cursor usage could not be read, persisted, refreshed, or exported. Existing files were not replaced; accounting may be incomplete. See /cursor-usage help for storage limits and recovery.", true);
+            }
+        },
+    });
+}