cursor-opencode-provider 0.7.6 → 0.8.1

package/dist/protocol/turn-provenance.js

@@ -0,0 +1,174 @@
+// A sticky Cursor conversation only knows what Cursor itself produced. When the
+// host answers a turn with another model (another provider or a local model)
+// and then comes back, resuming the old checkpoint hides that work from Cursor.
+// A direct switch between two Cursor models is not foreign history: like the
+// Cursor CLI, the next Run resumes the same conversation with the new model.
+// Remember what this provider emitted in its most recent step per OpenCode
+// session so the next fresh Run can tell whether the host's latest assistant
+// turn is ours.
+/** Mirrors MAX_TURN_STATE_SESSIONS; evicted sessions re-hydrate from disk. */
+export const MAX_PROVENANCE_SESSIONS = 256;
+// Per-session footprint stays small: a step is identified by its first tool
+// call ids and the first 4 KiB of its text (and of its reasoning plus text),
+// which is enough to tell turns apart.
+const MAX_TOOL_CALL_IDS = 64;
+const MAX_TEXT_CHARS = 4 * 1024;
+const provenanceBySession = new Map();
+function normalizeText(text) {
+    return text.replace(/\s+/g, "");
+}
+function touch(sessionKey, entry) {
+    provenanceBySession.delete(sessionKey);
+    provenanceBySession.set(sessionKey, entry);
+    while (provenanceBySession.size > MAX_PROVENANCE_SESSIONS) {
+        const oldest = provenanceBySession.keys().next().value;
+        if (!oldest)
+            break;
+        provenanceBySession.delete(oldest);
+    }
+    return entry;
+}
+function entryFor(sessionKey, conversationId) {
+    const existing = provenanceBySession.get(sessionKey);
+    if (existing && existing.conversationId === conversationId)
+        return touch(sessionKey, existing);
+    return touch(sessionKey, { conversationId, toolCallIds: [], text: "", textWithReasoning: "", stepPending: false });
+}
+function appendCapped(value, delta) {
+    return value.length < MAX_TEXT_CHARS ? (value + delta).slice(0, MAX_TEXT_CHARS) : value;
+}
+function contentEntry(sessionKey, conversationId) {
+    const entry = entryFor(sessionKey, conversationId);
+    if (entry.stepPending) {
+        entry.stepPending = false;
+        entry.toolCallIds = [];
+        entry.text = "";
+        entry.textWithReasoning = "";
+    }
+    return entry;
+}
+/**
+ * Mark the start of one host step (one doStream). The previous step stays
+ * recorded until this one emits content, because hosts drop empty assistant
+ * turns from history.
+ */
+export function beginEmittedStep(sessionKey, conversationId) {
+    entryFor(sessionKey, conversationId).stepPending = true;
+}
+/** Record one stream part this provider handed to the host. */
+export function recordEmittedPart(sessionKey, conversationId, part) {
+    if ((part.type === "text-delta" || part.type === "reasoning-delta") && typeof part.delta === "string") {
+        const delta = normalizeText(part.delta);
+        if (!delta)
+            return;
+        const entry = contentEntry(sessionKey, conversationId);
+        entry.textWithReasoning = appendCapped(entry.textWithReasoning, delta);
+        if (part.type === "text-delta")
+            entry.text = appendCapped(entry.text, delta);
+        return;
+    }
+    if (part.type === "tool-call" && typeof part.toolCallId === "string" && part.toolCallId) {
+        const entry = contentEntry(sessionKey, conversationId);
+        if (entry.toolCallIds.length < MAX_TOOL_CALL_IDS)
+            entry.toolCallIds.push(part.toolCallId);
+    }
+}
+/**
+ * Bind provenance to the conversation a Run was opened on. A reminted
+ * conversation starts with an empty record, so it never inherits the previous
+ * conversation's steps.
+ */
+export function trackTurnProvenance(sessionKey, conversationId) {
+    entryFor(sessionKey, conversationId);
+}
+export function getTurnProvenance(sessionKey) {
+    const entry = provenanceBySession.get(sessionKey);
+    if (!entry)
+        return undefined;
+    return {
+        conversationId: entry.conversationId,
+        toolCallIds: [...entry.toolCallIds],
+        text: entry.text,
+        textWithReasoning: entry.textWithReasoning,
+    };
+}
+export function restoreTurnProvenance(sessionKey, value) {
+    touch(sessionKey, { ...value, toolCallIds: [...value.toolCallIds], stepPending: false });
+}
+export function resetTurnProvenanceForTests() {
+    provenanceBySession.clear();
+}
+export function serializeTurnProvenance(value) {
+    return JSON.stringify(value);
+}
+export function parseTurnProvenance(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (typeof value.conversationId !== "string" || !value.conversationId)
+            return undefined;
+        return {
+            conversationId: value.conversationId,
+            toolCallIds: Array.isArray(value.toolCallIds)
+                ? value.toolCallIds.filter((id) => typeof id === "string").slice(0, MAX_TOOL_CALL_IDS)
+                : [],
+            text: typeof value.text === "string" ? value.text.slice(0, MAX_TEXT_CHARS) : "",
+            textWithReasoning: typeof value.textWithReasoning === "string"
+                ? value.textWithReasoning.slice(0, MAX_TEXT_CHARS)
+                : "",
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Decide whether the host history moved past this Cursor conversation.
+ * Returns undefined when there is no evidence either way (no record for this
+ * conversation, or no assistant turn yet), so unknown state never forces a
+ * rebase.
+ */
+export function detectForeignHistory(input) {
+    if (!input.sessionKey)
+        return undefined;
+    const entry = provenanceBySession.get(input.sessionKey);
+    if (!entry || entry.conversationId !== input.conversationId)
+        return undefined;
+    let lastAssistant;
+    for (let i = input.prompt.length - 1; i >= 0; i--) {
+        if (input.prompt[i].role === "assistant") {
+            lastAssistant = input.prompt[i];
+            break;
+        }
+    }
+    if (!lastAssistant || !Array.isArray(lastAssistant.content))
+        return undefined;
+    const toolCallIds = [];
+    let text = "";
+    let textWithReasoning = "";
+    for (const part of lastAssistant.content) {
+        if (part.type === "tool-call" && typeof part.toolCallId === "string")
+            toolCallIds.push(part.toolCallId);
+        if ((part.type === "text" || part.type === "reasoning") && typeof part.text === "string") {
+            const normalized = normalizeText(part.text);
+            textWithReasoning += normalized;
+            if (part.type === "text")
+                text += normalized;
+        }
+    }
+    // A turn carrying only typed reasoning gives no evidence either way.
+    if (toolCallIds.length === 0 && !text)
+        return undefined;
+    if (toolCallIds.some((id) => entry.toolCallIds.includes(id)))
+        return undefined;
+    // Compare against the latest step only: a foreign "Done." must not match an
+    // older Cursor turn that happened to contain the same words. Same model: the
+    // host keeps our reasoning typed, so its text parts match our text. After a
+    // model switch OpenCode 1.x replays that reasoning as text parts in place,
+    // so the turn matches our reasoning and text in emission order instead.
+    if (entry.text && text.slice(0, MAX_TEXT_CHARS) === entry.text)
+        return undefined;
+    if (entry.textWithReasoning && textWithReasoning.slice(0, MAX_TEXT_CHARS) === entry.textWithReasoning) {
+        return undefined;
+    }
+    return "foreign-assistant";
+}

package/dist/replay-safety.d.ts

@@ -19,5 +19,11 @@ export type ReplayFrameAnalysis = {
     semanticProgress: boolean;
     barrier?: ReplayBarrierReason;
 };
+/**
+ * Field numbers and wire types of a frame, nested three levels, without any
+ * payload bytes: `1:2{16:2{1:0}}`. Compare it with `agent.proto` when a frame
+ * is classified unknown.
+ */
+export declare function describeFrameLayout(payload: Uint8Array, depth?: number): string;
 /** Classify one decoded server frame without performing any protocol side effects. */
 export declare function analyzeReplayFrame(payload: Uint8Array, decoded: DecodedReplayFrame): ReplayFrameAnalysis;

package/dist/replay-safety.js

@@ -20,9 +20,25 @@ export class AttemptReplaySafety {
         return failure;
     }
 }
-const INTERACTION_UPDATE_FIELDS = new Set([1, 2, 3, 4, 7, 13, 14, 16, 17]);
+// Field numbers follow Cursor CLI 2026.09.28 `agent.v1`; the extracted
+// agent.proto lags the live server.
+// `InteractionUpdate` oneof members this client recognizes. Besides the
+// declared ones: `thinking_completed` #5 (duration), `token_delta` #8 (count),
+// `tool_call_delta` #15 (argument stream, like `partial_tool_call` #7),
+// `routed_model` #24 (display name) and `tool_requests_listed` #27 (count)
+// carry no output and no state. Other members stay barriers.
+const INTERACTION_UPDATE_FIELDS = new Set([1, 2, 3, 4, 5, 7, 8, 13, 14, 15, 16, 17, 24, 27]);
+/** `InteractionUpdate.message_started_at_ms` #25: a timestamp beside the oneof member. */
+const INTERACTION_UPDATE_STARTED_AT = 25;
 const INTERACTION_QUERY_FIELDS = new Set([2, 3, 4, 7, 8, 9, 10, 11, 12, 13, 14]);
 const TOP_LEVEL_FIELDS = new Set([1, 2, 3, 4, 5, 7]);
+/** `AgentServerMessage.ttft_breakdown` #8: timing metrics beside the oneof member. */
+const SERVER_MESSAGE_TTFT = 8;
+/** At most one occurrence of an optional field, with the expected wire type. */
+function optionalField(fields, fn, wt) {
+    const matches = fields.filter((field) => field.fn === fn);
+    return matches.length <= 1 && matches.every((field) => field.wt === wt);
+}
 function nestedFields(topLevel, field) {
     if (topLevel?.fn !== field || topLevel.wt !== 2 || !topLevel.bytes)
         return [];
@@ -37,8 +53,14 @@ function analyzeExecWire(topLevel) {
         exactMcpState: exactVariant(36),
     };
 }
+// `KvServerMessage` = id #1, oneof get #2 / set #3, `span_context` #4 (tracing);
+// Cursor sends the span on live KV requests.
 function validKvWire(topLevel) {
-    const variants = nestedFields(topLevel, 4).filter((field) => field.fn !== 1);
+    const fields = nestedFields(topLevel, 4);
+    const spans = fields.filter((field) => field.fn === 4);
+    if (spans.length > 1 || spans.some((field) => field.wt !== 2))
+        return false;
+    const variants = fields.filter((field) => field.fn !== 1 && field.fn !== 4);
     const variant = variants.length === 1 ? variants[0] : undefined;
     const args = variant?.wt === 2 && variant.bytes
         ? (readAllFieldsStrict(variant.bytes) ?? [])
@@ -53,14 +75,23 @@ function validKvWire(topLevel) {
 function validInteractionUpdateWire(topLevel, decoded) {
     if (!decoded)
         return true;
-    const fields = nestedFields(topLevel, 1);
+    const all = nestedFields(topLevel, 1);
+    if (!optionalField(all, INTERACTION_UPDATE_STARTED_AT, 0))
+        return false;
+    const fields = all.filter((field) => field.fn !== INTERACTION_UPDATE_STARTED_AT);
     const update = fields.length === 1 ? fields[0] : undefined;
     if (!update || update.wt !== 2 || !INTERACTION_UPDATE_FIELDS.has(update.fn))
         return false;
     if (![1, 4].includes(update.fn))
         return true;
     const delta = update.bytes ? (readAllFieldsStrict(update.bytes) ?? []) : [];
-    return delta.length === 1 && delta[0].fn === 1 && delta[0].wt === 2;
+    const text = delta.filter((field) => field.fn === 1);
+    // #2 is `TextDeltaUpdate.is_server_notice` (bool) or
+    // `ThinkingDeltaUpdate.thinking_style` (enum); both varints.
+    const flag = delta.filter((field) => field.fn === 2);
+    return text.length === 1 && text[0].wt === 2
+        && optionalField(delta, 2, 0)
+        && delta.length === text.length + flag.length;
 }
 function validInteractionQueryWire(topLevel, decoded) {
     if (!decoded)
@@ -96,10 +127,29 @@ function hasSemanticProgress(decoded) {
         || !!decoded.interactionQuery
         || !!decoded.checkpointBytes?.length;
 }
+/**
+ * Field numbers and wire types of a frame, nested three levels, without any
+ * payload bytes: `1:2{16:2{1:0}}`. Compare it with `agent.proto` when a frame
+ * is classified unknown.
+ */
+export function describeFrameLayout(payload, depth = 3) {
+    const fields = readAllFieldsStrict(payload);
+    if (!fields)
+        return "?";
+    return fields.map((field) => {
+        const nested = depth > 1 && field.wt === 2 && field.bytes && field.bytes.length > 0
+            ? readAllFieldsStrict(field.bytes)
+            : undefined;
+        const inner = nested && nested.length > 0 ? `{${describeFrameLayout(field.bytes, depth - 1)}}` : "";
+        return `${field.fn}:${field.wt}${inner}`;
+    }).join(",");
+}
 /** Classify one decoded server frame without performing any protocol side effects. */
 export function analyzeReplayFrame(payload, decoded) {
-    const topLevelFields = readAllFieldsStrict(payload) ?? [];
-    const topLevel = topLevelFields.length === 1 ? topLevelFields[0] : undefined;
+    const allTopLevel = readAllFieldsStrict(payload) ?? [];
+    const ttftValid = optionalField(allTopLevel, SERVER_MESSAGE_TTFT, 2);
+    const topLevelFields = allTopLevel.filter((field) => field.fn !== SERVER_MESSAGE_TTFT);
+    const topLevel = ttftValid && topLevelFields.length === 1 ? topLevelFields[0] : undefined;
     const exec = analyzeExecWire(topLevel);
     const validKv = validKvWire(topLevel);
     const malformed = !topLevel

package/dist/session.d.ts

@@ -3,6 +3,7 @@ import { type CursorProviderError } from "./errors.js";
 import { type SessionActivitySource } from "./activity.js";
 import type { HostSubagentCatalog, HostToolDialect, OpencodeToolDef, ToolAliasRegistry } from "./protocol/tools.js";
 import type { CursorConversationTokenDetails } from "./protocol/token-details.js";
+import type { ParallelStepState } from "./parallel-step.js";
 export type Frame = {
     flags: number;
     payload: Uint8Array;
@@ -95,6 +96,8 @@ export type CursorSession = {
      * (Cursor resets them per stream) can't cross-deliver results.
      */
     sessionId: string;
+    /** AgentRunRequest.run_id, for context injections bound to this Run. */
+    runId?: string;
     /**
      * Cursor conversation_id for this Run — used to store/echo
      * conversation_checkpoint_update (CLI parity).
@@ -140,12 +143,36 @@ export type CursorSession = {
     hostAgent?: string;
     /** Stable host-system + provider-guidance identity for restart validation. */
     stableSystemPromptHash?: string;
+    /** Fresh turn resumed from a stored checkpoint; a blob miss may reseed it. */
+    checkpointRebaseEligible?: boolean;
     /** Completed compaction must rebase once before resuming a normal agent. */
     postCompactionRebase?: boolean;
-    /** Last real host catalog, retained only as a lifecycle-turn fallback. */
+    /**
+     * Epoch-held host catalog for this OpenCode session. Refreshed on every
+     * `doStream` (including held-Run continuation) so exec #36 and permission
+     * can see tools that connected after Run open. Also the lifecycle-turn fallback.
+     */
     toolCatalog?: OpencodeToolDef[];
+    /** Configured MCP server ids used to split flattened host tool names. */
+    knownMcpServers?: string[];
+    /** The Run's model accepts images, so held-Run exec results may carry them. */
+    supportsImages?: boolean;
     stream: BidiStream;
     frames: AsyncIterator<Frame>;
+    /** An iterator read retained across an idle-guard timeout. */
+    pendingFrameRead?: Promise<IteratorResult<Frame>>;
+    /**
+     * One-slot pushback for a terminal update that must start the next pump pass
+     * after the host settles emitted tools. Timed-out reads use pendingFrameRead.
+     */
+    pushbackFrame?: Frame;
+    /**
+     * In-progress parallel tool-call step (field 27 hold). Cleared when the step
+     * finishes; added to priorParallelStepCallIds for late-completion filtering.
+     */
+    parallelStep?: ParallelStepState;
+    /** Resolved call ids from prior steps of this Run — ignore late completions. */
+    priorParallelStepCallIds?: Set<string>;
     pending: Map<number, PendingExec>;
     /**
      * Cursor display tool calls (tool_call_started) awaiting either an exec or a
@@ -159,6 +186,11 @@ export type CursorSession = {
      * completed list so host todos still receive a replace-all snapshot.
      */
     mirroredTodos?: Array<Record<string, unknown>>;
+    /**
+     * CreatePlan display calls whose plan was deferred to the host plan agent.
+     * Their completed display carries no recorded plan, so it is not mirrored.
+     */
+    deferredCreatePlanCalls?: Set<string>;
     /**
      * Legacy edit calls whose authoritative exec path is still in progress.
      * Cursor implements these as read -> whole-file write; retaining the path
@@ -294,7 +326,7 @@ export declare class SessionManager {
      * Callers must cancel the session heartbeat and wait for the old stream's
      * write chain before this, so an in-flight heartbeat cannot close the session.
      */
-    replaceStream(session: CursorSession, next: BidiStream): void;
+    replaceStream(session: CursorSession, next: BidiStream, runId?: string): void;
     private subscribeTerminal;
     private key;
     close(session: CursorSession, reason?: SessionCloseReason, error?: CursorProviderError): void;
@@ -317,5 +349,15 @@ export declare class SessionManager {
     private putTombstone;
     private isTerminalReason;
 }
+/**
+ * Read one frame, retaining ownership of the iterator read when a timeout
+ * wins. Every reader uses this function so a continuation cannot overtake a
+ * late frame (or discard its EOF/error).
+ */
+export declare function readSessionFrame(session: CursorSession): Promise<IteratorResult<Frame>>;
+export declare function readSessionFrame(session: CursorSession, timeoutMs: number): Promise<IteratorResult<Frame> | {
+    done: true;
+    timedOut: true;
+}>;
 export declare const sessionManager: SessionManager;
 export {};

package/dist/session.js

@@ -386,7 +386,7 @@ export class SessionManager {
      * Callers must cancel the session heartbeat and wait for the old stream's
      * write chain before this, so an in-flight heartbeat cannot close the session.
      */
-    replaceStream(session, next) {
+    replaceStream(session, next, runId) {
         if (session.closed)
             throw new CursorProtocolError("Cannot replace stream on a closed Cursor session");
         session.heartbeatCancel?.();
@@ -395,7 +395,13 @@ export class SessionManager {
         session.deferredTerminalReason = null;
         const old = session.stream;
         session.stream = next;
+        if (runId !== undefined)
+            session.runId = runId;
         session.frames = next.frames()[Symbol.asyncIterator]();
+        session.pendingFrameRead = undefined;
+        session.pushbackFrame = undefined;
+        session.parallelStep = undefined;
+        session.priorParallelStepCallIds = undefined;
         this.subscribeTerminal(session);
         try {
             old.destroy();
@@ -444,6 +450,10 @@ export class SessionManager {
                 this.putTombstone(key, reason);
         }
         session.pending.clear();
+        session.pendingFrameRead = undefined;
+        session.pushbackFrame = undefined;
+        session.parallelStep = undefined;
+        session.priorParallelStepCallIds = undefined;
         session.pumpOwner = null;
         session.pumpActive = false;
         session.displayToolCalls?.clear();
@@ -570,6 +580,40 @@ export class SessionManager {
         return !["ordinary-cleanup", "turn-ended", "initial-write-failed"].includes(reason);
     }
 }
+export async function readSessionFrame(session, timeoutMs) {
+    if (session.pushbackFrame) {
+        const value = session.pushbackFrame;
+        session.pushbackFrame = undefined;
+        return { done: false, value };
+    }
+    const pending = session.pendingFrameRead ??= session.frames.next();
+    // A timed-out read can reject while no pump is consuming it. Preserve the
+    // rejection for the next reader without an unhandled detached promise.
+    void pending.catch(() => { });
+    let timer;
+    try {
+        const result = timeoutMs === undefined ? await pending : await Promise.race([
+            pending,
+            new Promise(resolve => {
+                timer = setTimeout(() => resolve({ done: true, timedOut: true }), timeoutMs);
+                timer.unref?.();
+            }),
+        ]);
+        if (!("timedOut" in result) && session.pendingFrameRead === pending) {
+            session.pendingFrameRead = undefined;
+        }
+        return result;
+    }
+    catch (error) {
+        if (session.pendingFrameRead === pending)
+            session.pendingFrameRead = undefined;
+        throw error;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 export const sessionManager = new SessionManager();
 function installProcessCleanup() {
     const dispose = () => {

package/dist/shared.d.ts

@@ -1,5 +1,12 @@
 export declare const CURSOR_API_HOST = "api2.cursor.sh";
 export declare const CURSOR_WEBSITE_HOST = "cursor.com";
+/**
+ * Production OAuth client id Cursor's IDE sends on `POST /oauth/token`
+ * (Cursor 3.17.19 `workbench.desktop.main.js`, `cursorCreds.authClientId` for
+ * `backendUrl` `https://api2.cursor.sh`). The IDE's non-production id is not
+ * used: a custom `CURSOR_API_BASE_URL` keeps this one.
+ */
+export declare const CURSOR_OAUTH_CLIENT_ID = "KbZUR41cY7W6zRSdpSUJ7I7mLYBKOCmB";
 export declare const FALLBACK_CLIENT_VERSION = "cli-2026.07.09-a3815c0";
 export declare const CURSOR_PROVIDER_ID = "cursor";
 /** Private provider option injected by the OpenCode plugin for summary turns. */

package/dist/shared.js

@@ -1,5 +1,12 @@
 export const CURSOR_API_HOST = "api2.cursor.sh";
 export const CURSOR_WEBSITE_HOST = "cursor.com";
+/**
+ * Production OAuth client id Cursor's IDE sends on `POST /oauth/token`
+ * (Cursor 3.17.19 `workbench.desktop.main.js`, `cursorCreds.authClientId` for
+ * `backendUrl` `https://api2.cursor.sh`). The IDE's non-production id is not
+ * used: a custom `CURSOR_API_BASE_URL` keeps this one.
+ */
+export const CURSOR_OAUTH_CLIENT_ID = "KbZUR41cY7W6zRSdpSUJ7I7mLYBKOCmB";
 export const FALLBACK_CLIENT_VERSION = "cli-2026.07.09-a3815c0";
 export const CURSOR_PROVIDER_ID = "cursor";
 /** Private provider option injected by the OpenCode plugin for summary turns. */

package/dist/todo-store.d.ts

@@ -22,6 +22,8 @@ export type SessionTodo = {
 /** Normalize one host/Cursor todo item. Drops entries with empty content. */
 export declare function normalizeSessionTodo(value: unknown, index: number): SessionTodo | undefined;
 export declare function normalizeSessionTodos(value: unknown): SessionTodo[];
+/** Fill omitted defaults before validation without dropping malformed entries. */
+export declare function normalizeOpencodeTodoArgs(args: Record<string, unknown>): Record<string, unknown>;
 export declare function getSessionTodos(sessionID: string): SessionTodo[];
 export declare function setSessionTodos(sessionID: string, todos: unknown): SessionTodo[];
 export declare function clearSessionTodos(sessionID: string): void;

package/dist/todo-store.js

@@ -54,6 +54,25 @@ export function normalizeSessionTodos(value) {
     }
     return out;
 }
+/** Fill omitted defaults before validation without dropping malformed entries. */
+export function normalizeOpencodeTodoArgs(args) {
+    if (!Array.isArray(args.todos))
+        return args;
+    return {
+        ...args,
+        todos: args.todos.map((item, index) => {
+            if (!item || typeof item !== "object" || Array.isArray(item))
+                return item;
+            const todo = item;
+            return {
+                ...todo,
+                ...(todo.id === undefined ? { id: String(index + 1) } : {}),
+                ...(todo.status === undefined ? { status: "pending" } : {}),
+                ...(todo.priority === undefined ? { priority: "medium" } : {}),
+            };
+        }),
+    };
+}
 export function getSessionTodos(sessionID) {
     return lists.get(sessionID)?.map((todo) => ({ ...todo })) ?? [];
 }

package/dist/transport/connect.d.ts

@@ -73,6 +73,8 @@ export declare function resolveAgentOrigin(baseURL: string): string;
 export declare function closeCachedHttp2SessionsForTests(): void;
 /** Node-runtime regression hook; production callers use getSession(). */
 export declare function installSessionInvalidationForTests(origin: string, session: http2.ClientHttp2Session): void;
+/** Node-runtime regression hook: cache a connected local session for `origin`. */
+export declare function cacheHttp2SessionForTests(origin: string, session: http2.ClientHttp2Session): void;
 export declare function getSession(baseURL: string, options?: {
     pingTimeoutMs?: number;
 }): Promise<http2.ClientHttp2Session>;

package/dist/transport/connect.js

@@ -259,6 +259,19 @@ function dropSession(origin, session) {
     if (_http2Sessions.get(origin) === session)
         _http2Sessions.delete(origin);
 }
+/**
+ * Stop offering `session` for new Runs and close it so in-flight streams can
+ * drain. Used by age rotation and a failed reuse ping — never
+ * `destroy()`, which would abort every sibling Run multiplexed on the session
+ * mid-output (those Runs cannot be replayed after visible activity).
+ */
+function retireCachedSession(origin, session) {
+    dropSession(origin, session);
+    try {
+        session.close();
+    }
+    catch { /* already closed */ }
+}
 /** Test cleanup for local HTTP/2 fixtures; production sessions stay process-cached. */
 export function closeCachedHttp2SessionsForTests() {
     for (const session of _http2Sessions.values()) {
@@ -354,6 +367,12 @@ function installSessionInvalidation(origin, session) {
 export function installSessionInvalidationForTests(origin, session) {
     installSessionInvalidation(origin, session);
 }
+/** Node-runtime regression hook: cache a connected local session for `origin`. */
+export function cacheHttp2SessionForTests(origin, session) {
+    installSessionInvalidation(origin, session);
+    _http2SessionCreatedAt.set(session, Date.now());
+    _http2Sessions.set(origin, session);
+}
 function invalidateSession(origin, session) {
     dropSession(origin, session);
     _http2SessionListenerCleanup.get(session)?.();
@@ -535,11 +554,7 @@ export function getSession(baseURL, options = {}) {
             const createdAt = _http2SessionCreatedAt.get(existing) ?? 0;
             if (!shouldReuseHttp2Session(existing, createdAt)) {
                 trace(`h2 session rotate: origin=${origin} ageMs=${Math.max(0, Date.now() - createdAt)}`);
-                dropSession(origin, existing);
-                try {
-                    existing.close();
-                }
-                catch { /* already closed */ }
+                retireCachedSession(origin, existing);
             }
             else {
                 try {
@@ -550,8 +565,10 @@ export function getSession(baseURL, options = {}) {
                     }
                 }
                 catch (error) {
+                    // Sibling Runs may still be streaming on this session; destroy() would
+                    // abort them mid-output, where they cannot be replayed.
                     trace(`h2 cached session ping failed: origin=${origin} err=${error.message}`);
-                    invalidateSession(origin, existing);
+                    retireCachedSession(origin, existing);
                 }
             }
         }

package/dist/usage.js

@@ -1,3 +1,4 @@
+import { currentCursorTokenBreakdown } from "./protocol/token-details.js";
 /** Non-negative integer counter from a Cursor `turn_ended` field. */
 export function turnEndedCounter(te, key) {
     const value = te[key];
@@ -75,7 +76,7 @@ function usageRatio(part, total) {
     return total > 0 ? `${(part / total * 100).toFixed(1)}%` : "n/a";
 }
 function categoryTokens(details) {
-    return new Map(details?.breakdown?.categories.map((category) => [
+    return new Map(currentCursorTokenBreakdown(details)?.categories.map((category) => [
         category.id || category.label || "(unnamed)",
         category.estimatedTokens,
     ]) ?? []);
@@ -97,7 +98,7 @@ export function formatCursorCacheDiagnostics(counters, current, prior, stats) {
     const rawUncached = Math.max(0, rawInput - rawRead - rawWrite);
     const priorCategories = categoryTokens(prior);
     const currentCategories = categoryTokens(current);
-    const categoriesComparable = !!prior?.breakdown && !!current?.breakdown;
+    const categoriesComparable = !!currentCursorTokenBreakdown(prior) && !!currentCursorTokenBreakdown(current);
     const categoryDelta = {};
     let sameSizedCategoryTokens = 0;
     if (categoriesComparable) {
@@ -132,6 +133,13 @@ export function formatCursorCacheDiagnostics(counters, current, prior, stats) {
             && toolsDelta !== 0
             ? "client-overlay-changed"
             : "none";
+    // Occupancy measures context size, not cache reuse. A zero counter on an
+    // interaction turn cannot distinguish omitted accounting from a cache miss.
+    const interactionZeroRead = stats.startedWithCheckpoint
+        && rawRead === 0
+        && typeof prior?.usedTokens === "number"
+        && prior.usedTokens > 0
+        && (stats.createPlanInTurn === true || stats.switchModeInTurn === true);
     return [
         "cache diagnosis:",
         `sessionKey=${stats.sessionKey ?? "-"}`,
@@ -164,6 +172,12 @@ export function formatCursorCacheDiagnostics(counters, current, prior, stats) {
         `execRequests=${stats.execRequests}`,
         `createPlanInTurn=${stats.createPlanInTurn === true}`,
         `switchModeInTurn=${stats.switchModeInTurn === true}`,
+        ...(interactionZeroRead
+            ? [
+                "turnEndedCacheRead=zero-interaction",
+                "cacheReuseEvidence=unavailable",
+            ]
+            : []),
         "perModelCallCache=unavailable",
     ].join(" ");
 }
@@ -189,8 +203,9 @@ export function formatTurnUsageValidation(counters, usage, tokenDetails, context
     const breakdown = tokenDetails?.breakdown;
     const categorySum = breakdown?.categories.reduce((sum, category) => sum + category.estimatedTokens, 0);
     const breakdownMatch = breakdown && categorySum !== undefined
-        ? breakdown.totalUsedTokens === tokenDetails.usedTokens &&
-            categorySum === breakdown.totalUsedTokens
+        ? categorySum !== breakdown.totalUsedTokens
+            ? false
+            : currentCursorTokenBreakdown(tokenDetails) ? true : "stale"
         : undefined;
     const rawCached = counters.cacheRead + counters.cacheWrite;
     const sentCached = cacheRead + cacheWrite;
@@ -208,7 +223,7 @@ export function formatTurnUsageValidation(counters, usage, tokenDetails, context
         projectedOpenCodeTotal === sentTotal &&
         (cacheRatioMatch ?? true) &&
         (!tokenDetails || sentTotal === tokenDetails.usedTokens) &&
-        (breakdownMatch ?? true)
+        breakdownMatch !== false
         ? "ok"
         : "mismatch";
     return [
@@ -267,7 +282,9 @@ export function occupancyValidationCounters(details, prior) {
     return {
         inputTokens: used,
         outputTokens: used > 0 ? 1 : 0,
-        cacheRead: Math.max(0, Math.trunc(prior?.usedTokens ?? 0)),
+        // Cursor can shrink the context between checkpoints; the prior prefix
+        // cannot be larger than what is in context now.
+        cacheRead: Math.min(used, Math.max(0, Math.trunc(prior?.usedTokens ?? 0))),
         cacheWrite: 0,
         reasoningTokens: 0,
     };