cursor-opencode-provider 0.8.0 → 0.8.3

package/dist/protocol/apply-patch.js

@@ -1,6 +1,6 @@
 /**
- * Synthesis of OpenCode `apply_patch` envelopes from Cursor's native write/edit
- * exec requests.
+ * Synthesis of OpenCode `apply_patch` (2.0: `patch`) envelopes from Cursor's
+ * native write/edit exec requests.
  *
  * ## Why this exists
  *
@@ -36,10 +36,12 @@
  *   `ctx.session.context(...)` hook exposing a mutable tool roster, and lists
  *   "Select `apply_patch` versus `edit` + `write`" as work to move out of the
  *   registry. Once that lands, a host-side opt-out replaces this shim.
- * - OpenCode 2.0 (`packages/core`) has **no** such gate: `apply_patch`, `edit`
- *   and `write` are all registered unconditionally in `tool/builtins.ts`. This
- *   translation is therefore 1.x-only in practice, but it is keyed off the
- *   advertised set rather than a version check, so it simply never fires on 2.0.
+ * - OpenCode 2.0 (`packages/core`) keeps the gate under a new name. The tool is
+ *   `patch` (still `{ patchText }`, same envelope format), and
+ *   `tool/plugin/patch.ts` applies the same model-id predicate in its session
+ *   `context`/`compaction`/`generate` hooks, deleting `edit` and `write` for GPT models and
+ *   `patch` for everyone else. Both names are recognised here; which one the
+ *   host offers is read from the advertised set rather than a version check.
  *
  * ## Why translation, not advertisement
  *
@@ -59,7 +61,7 @@
  * native requests arrive for every model. Those names are absent from
  * the catalog, so the request is refused before it reaches OpenCode.
  *
- * ## Format notes (verified against `packages/opencode/src/patch/index.ts`)
+ * ## Format notes (verified against `packages/opencode/src/patch/index.ts` and 2.0's `packages/util/src/patch.ts`)
  *
  * - `*** Add File:` **overwrites an existing file** — the tool's `add` case uses
  *   `oldContent = ""` and never stats the target (upstream test: "adds file
@@ -71,37 +73,75 @@
  * - Every payload line is prefixed with `+`, `-`, or a space, and the parser
  *   only breaks on *unprefixed* `***` / `@@`. Content lines that themselves
  *   begin with `***` or `@@` therefore survive a round trip unharmed.
- * - `Add File` content is rejoined with `\n` and normalized to exactly one
- *   trailing newline. A write of content with no trailing newline gains one.
+ * - `Add File` content is rejoined with `\n`; the tool appends a final newline
+ *   only when nonempty content lacks one. Keep the trailing empty payload line
+ *   so blank lines survive. Nonempty unterminated content cannot round-trip.
+ * - OpenCode 2's `patch` parser strips a trailing `\r` from every payload
+ *   line, unlike 1.x `apply_patch`. Refuse that lossy encoding on `patch`.
  * - Update chunks match **whole lines** via `seekSequence`, unlike OpenCode
  *   `edit`, which is substring-based. Substring edits must be expanded to line
  *   boundaries before they can be expressed as a patch — see `planSubstringEdit`.
- * - Renames are rejected by OpenCode 2.0's implementation ("apply_patch moves
- *   are not supported yet"), so `*** Move to:` is never emitted here.
+ * - Cursor's write/edit requests never rename, so `*** Move to:` is never
+ *   emitted here.
  */
+/** OpenCode 1.x name for the patch tool. */
 export const APPLY_PATCH_TOOL = "apply_patch";
+/** OpenCode 2.0 name for the same tool (renamed from `apply_patch`). */
+export const PATCH_TOOL = "patch";
+/** The patch tool this host advertises in place of `edit`/`write`, if any. */
+export function hostPatchTool(advertised) {
+    if (advertised.has(APPLY_PATCH_TOOL))
+        return APPLY_PATCH_TOOL;
+    if (advertised.has(PATCH_TOOL))
+        return PATCH_TOOL;
+    return undefined;
+}
+export function isHostPatchTool(name) {
+    return name === APPLY_PATCH_TOOL || name === PATCH_TOOL;
+}
 const BEGIN = "*** Begin Patch";
 const END = "*** End Patch";
 /**
  * Whole-file write as `*** Add File:`. Valid whether or not the target exists —
  * OpenCode's add case overwrites unconditionally.
  */
-export function buildAddFilePatch(filePath, content) {
-    const lines = splitLines(content);
+export function buildAddFilePatch(filePath, content, tool = APPLY_PATCH_TOOL) {
+    assertPatchPath(filePath);
+    assertPatchText(content, tool);
+    if (content.startsWith("\uFEFF\uFEFF"))
+        throw new Error("the patch tool cannot preserve repeated leading byte-order marks");
+    if (content && !content.endsWith("\n"))
+        throw new Error("the patch tool cannot preserve content without a final newline");
+    const lines = content.split("\n");
     return [BEGIN, `*** Add File: ${filePath}`, ...lines.map((line) => `+${line}`), END].join("\n");
 }
 /** Targeted replacement as `*** Update File:` with one `@@` chunk per change. */
-export function buildUpdateFilePatch(filePath, chunks) {
+export function buildUpdateFilePatch(filePath, chunks, tool = APPLY_PATCH_TOOL) {
+    assertPatchPath(filePath);
     const body = [];
     for (const chunk of chunks) {
         body.push("@@");
-        for (const line of chunk.oldLines)
-            body.push(`-${line}`);
-        for (const line of chunk.newLines)
-            body.push(`+${line}`);
+        for (const [prefix, lines] of [["-", chunk.oldLines], ["+", chunk.newLines]]) {
+            for (const line of lines) {
+                if (line.includes("\n"))
+                    throw new Error("a patch payload line contains a newline");
+                assertPatchText(line, tool);
+                body.push(`${prefix}${line}`);
+            }
+        }
     }
     return [BEGIN, `*** Update File: ${filePath}`, ...body, END].join("\n");
 }
+function assertPatchPath(filePath) {
+    if (!filePath || filePath.trim() !== filePath || /[\0\r\n]/.test(filePath)) {
+        throw new Error("the target path cannot be represented exactly in a patch header");
+    }
+}
+function assertPatchText(text, tool) {
+    if (tool === PATCH_TOOL && /\r(?:\n|$)/.test(text)) {
+        throw new Error("the patch tool strips carriage returns from line endings; this content cannot be preserved");
+    }
+}
 /**
  * Expand a substring replacement to the whole lines it touches, because
  * `apply_patch` matches line sequences rather than substrings.
@@ -124,6 +164,13 @@ export function planSubstringEdit(source, oldString, newString, replaceAll = fal
             reason: `the text to replace appears ${offsets.length} times; it must be unique`,
         };
     }
+    const target = replaceAll ? source.replaceAll(oldString, () => newString) : source.replace(oldString, () => newString);
+    if (target.startsWith("\uFEFF\uFEFF") || (source.startsWith("\uFEFF") && !target.startsWith("\uFEFF"))) {
+        return { ok: false, reason: "the patch tool preserves one leading byte-order mark; this replacement cannot be preserved" };
+    }
+    if (target && !target.endsWith("\n")) {
+        return { ok: false, reason: "the patch tool cannot preserve content without a final newline" };
+    }
     const targets = replaceAll ? offsets : offsets.slice(0, 1);
     const chunks = [];
     let previousEnd = -1;
@@ -138,22 +185,24 @@ export function planSubstringEdit(source, oldString, newString, replaceAll = fal
         previousEnd = end;
         const before = source.slice(start, offset);
         const after = source.slice(offset + oldString.length, end);
-        chunks.push({
-            oldLines: splitLines(source.slice(start, end)),
-            newLines: splitLines(before + newString + after),
-        });
+        const oldLines = source.slice(start, end).split("\n");
+        // The host removes one final source terminator before matching. Interior
+        // empty lines are real context; stripping them deletes blank lines.
+        if (end === source.length && oldLines.at(-1) === "")
+            oldLines.pop();
+        chunks.push({ oldLines, newLines: (before + newString + after).split("\n") });
+    }
+    // The host also removes one terminator before applying updates, then adds it
+    // back only when the last line is nonempty. Restore an untouched blank tail
+    // explicitly; an EOF replacement already carries its complete terminator.
+    if (previousEnd < source.length && (target === "\n" || target.endsWith("\n\n"))) {
+        chunks.push({ oldLines: [], newLines: [""] });
     }
     return { ok: true, chunks };
 }
-/**
- * Split into patch payload lines. A trailing newline is dropped so it is not
- * emitted as a spurious empty line — OpenCode re-adds exactly one on apply.
- */
-function splitLines(text) {
-    const normalized = text.endsWith("\n") ? text.slice(0, -1) : text;
-    return normalized.split("\n");
-}
 function lineStart(source, offset) {
+    if (offset === 0)
+        return 0;
     const at = source.lastIndexOf("\n", offset - 1);
     return at === -1 ? 0 : at + 1;
 }

package/dist/protocol/ask-question.d.ts

@@ -76,6 +76,13 @@ export declare function decodeAskQuestionQuery(queryBytes: Uint8Array): DecodedA
 export declare function isCatchAllOptionLabel(label: string): boolean;
 /** Options as Cursor would display them: trailing catch-all removed. */
 export declare function displayOptions(question: CursorAskQuestionItem): CursorAskQuestionOption[];
+/** OpenCode `Question.Prompt.header`: short label, max 30 chars. */
+export declare function questionHeader(title: string): string;
+/**
+ * Fill required OpenCode `question` fields when a model call omits them.
+ * Live OC1 failure: SchemaError Missing key at ["questions"][0]["header"].
+ */
+export declare function normalizeOpencodeQuestionArgs(args: Record<string, unknown>): Record<string, unknown>;
 export type OpencodeQuestionInput = {
     questions: Array<{
         question: string;
@@ -100,12 +107,16 @@ export declare function asyncResult(): AskQuestionResultMessage;
 /**
  * Pull each question's answer text out of a host `question` tool output.
  *
- * OpenCode returns prose (`metadata.answers` does not cross the AI SDK
+ * OpenCode 1.x returns prose (`metadata.answers` does not cross the AI SDK
  * boundary):
  *
  *   User has answered your questions: "<q1>"="<a, b>", "<q2>"="Unanswered". You
  *   can now continue with the user's answers in mind.
  *
+ * OpenCode 2.0 sends the tool's declared output as JSON
+ * (`{ "answers": [["Yes"], …] }`) and does not put that prose on the AI SDK
+ * tool-result. Answers are positional.
+ *
  * The prose is located by its `"<question>"="` anchor — robust
  * against commas, quotes and `"="` inside question or answer text, and against
  * duplicate questions. Returns undefined for a question whose anchor is

package/dist/protocol/ask-question.js

@@ -183,7 +183,8 @@ export function displayOptions(question) {
         return question.options.slice(0, -1);
     return question.options.slice();
 }
-function header(title) {
+/** OpenCode `Question.Prompt.header`: short label, max 30 chars. */
+export function questionHeader(title) {
     const trimmed = title.trim();
     if (!trimmed)
         return "Question";
@@ -191,6 +192,40 @@ function header(title) {
         ? trimmed.slice(0, HEADER_MAX_LENGTH - 1).trimEnd() + "…"
         : trimmed;
 }
+/**
+ * Fill required OpenCode `question` fields when a model call omits them.
+ * Live OC1 failure: SchemaError Missing key at ["questions"][0]["header"].
+ */
+export function normalizeOpencodeQuestionArgs(args) {
+    if (!Array.isArray(args.questions))
+        return args;
+    return {
+        ...args,
+        questions: args.questions.map((item) => {
+            if (!item || typeof item !== "object" || Array.isArray(item))
+                return item;
+            const q = item;
+            const prompt = typeof q.question === "string" ? q.question : "";
+            const existing = typeof q.header === "string" ? q.header : "";
+            const options = Array.isArray(q.options)
+                ? q.options.map((opt) => {
+                    if (!opt || typeof opt !== "object" || Array.isArray(opt))
+                        return opt;
+                    const o = opt;
+                    return {
+                        ...o,
+                        ...(o.description === undefined ? { description: "" } : {}),
+                    };
+                })
+                : q.options;
+            return {
+                ...q,
+                header: questionHeader(existing.trim() || prompt),
+                options,
+            };
+        }),
+    };
+}
 /**
  * Build the OpenCode `question` tool input. `Question.Prompt` requires
  * `question`, `header`, and `options[{label, description}]`; Cursor options
@@ -200,7 +235,7 @@ export function askQuestionToolInput(args) {
     return {
         questions: args.questions.map((question) => ({
             question: question.prompt,
-            header: header(args.title),
+            header: questionHeader(args.title),
             options: displayOptions(question).map((option) => ({
                 label: option.label,
                 description: "",
@@ -220,18 +255,25 @@ export function asyncResult() {
 /**
  * Pull each question's answer text out of a host `question` tool output.
  *
- * OpenCode returns prose (`metadata.answers` does not cross the AI SDK
+ * OpenCode 1.x returns prose (`metadata.answers` does not cross the AI SDK
  * boundary):
  *
  *   User has answered your questions: "<q1>"="<a, b>", "<q2>"="Unanswered". You
  *   can now continue with the user's answers in mind.
  *
+ * OpenCode 2.0 sends the tool's declared output as JSON
+ * (`{ "answers": [["Yes"], …] }`) and does not put that prose on the AI SDK
+ * tool-result. Answers are positional.
+ *
  * The prose is located by its `"<question>"="` anchor — robust
  * against commas, quotes and `"="` inside question or answer text, and against
  * duplicate questions. Returns undefined for a question whose anchor is
  * absent, which is treated as unanswered rather than guessed at.
  */
 export function parseAnswerSegments(questions, output) {
+    const fromJson = parseJsonAnswerSegments(output, questions.length);
+    if (fromJson)
+        return fromJson;
     const answers = [];
     let cursor = 0;
     for (const question of questions) {
@@ -260,6 +302,38 @@ export function parseAnswerSegments(questions, output) {
     }
     return answers;
 }
+function cellText(cell) {
+    if (typeof cell === "string")
+        return cell;
+    if (typeof cell === "number" || typeof cell === "boolean")
+        return String(cell);
+    if (Array.isArray(cell)) {
+        const parts = cell.map((item) => (typeof item === "string" ? item : "")).filter(Boolean);
+        return parts.length > 0 ? parts.join(", ") : undefined;
+    }
+    return undefined;
+}
+/** OpenCode 2 `question` output `{ answers: string[][] }`, or a JSON array of cells. */
+function parseJsonAnswerSegments(output, count) {
+    const trimmed = output.trim();
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("["))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+    const cells = Array.isArray(parsed)
+        ? parsed
+        : parsed && typeof parsed === "object" && Array.isArray(parsed.answers)
+            ? parsed.answers
+            : undefined;
+    if (!cells)
+        return undefined;
+    return Array.from({ length: count }, (_, index) => cellText(cells[index]));
+}
 /** OpenCode's placeholder for a question the user left blank. */
 const UNANSWERED = "Unanswered";
 /**

package/dist/protocol/blob-store.d.ts

@@ -43,8 +43,12 @@ export declare function snapshotConversationBlobs(conversationId: string): Conve
  * Keep only blobs reachable from the latest checkpoint and snapshot them.
  * Malformed/unknown state or a missing referenced hash falls back to retaining
  * every blob: cache size must never come at the cost of restart correctness.
+ * `keepInMemory`: snapshot only, for a Run still in progress, whose next
+ * checkpoint may reference blobs this one does not.
  */
-export declare function compactConversationBlobs(conversationId: string, checkpoint: Uint8Array | undefined): ConversationBlobCompaction;
+export declare function compactConversationBlobs(conversationId: string, checkpoint: Uint8Array | undefined, options?: {
+    keepInMemory?: boolean;
+}): ConversationBlobCompaction;
 /** Replace the in-memory blob bucket when restoring a persisted conversation. */
 export declare function restoreConversationBlobs(conversationId: string, blobs: readonly ConversationBlobSnapshot[]): void;
 /** Drop all blobs for a conversation (compaction conversation reset). */

package/dist/protocol/blob-store.js

@@ -91,8 +91,10 @@ export function snapshotConversationBlobs(conversationId) {
  * Keep only blobs reachable from the latest checkpoint and snapshot them.
  * Malformed/unknown state or a missing referenced hash falls back to retaining
  * every blob: cache size must never come at the cost of restart correctness.
+ * `keepInMemory`: snapshot only, for a Run still in progress, whose next
+ * checkpoint may reference blobs this one does not.
  */
-export function compactConversationBlobs(conversationId, checkpoint) {
+export function compactConversationBlobs(conversationId, checkpoint, options) {
     const current = byConversation.get(conversationId) ?? new Map();
     const before = retainedBlobStats(current);
     const beforeCount = before.count;
@@ -117,13 +119,15 @@ export function compactConversationBlobs(conversationId, checkpoint) {
             return isBlobIdHash(id) ? undefined : id;
         });
         const retained = new Map([...current].filter(([id]) => reachable.has(id)));
-        if (retained.size > 0)
-            byConversation.set(conversationId, retained);
-        else
-            byConversation.delete(conversationId);
+        if (!options?.keepInMemory) {
+            if (retained.size > 0)
+                byConversation.set(conversationId, retained);
+            else
+                byConversation.delete(conversationId);
+        }
         const afterBytes = [...retained.values()].reduce((total, data) => total + data.length, 0);
         return {
-            blobs: snapshotConversationBlobs(conversationId),
+            blobs: [...retained].map(([id, data]) => ({ id, data: Uint8Array.from(data) })),
             beforeCount,
             beforeBytes,
             afterCount: retained.size,

package/dist/protocol/client-version.js

@@ -3,17 +3,19 @@ import path from "node:path";
 import { FALLBACK_CLIENT_VERSION, MODEL_CACHE_TTL_MS, VERSION_CACHE_FILE, } from "../shared.js";
 import { opencodeGlobalCacheDir } from "../context/paths.js";
 import { withAbortDeadline } from "../deadline.js";
+import { processShared } from "../process-shared.js";
 const INSTALL_URL = "https://cursor.com/install";
 const REMOTE_TIMEOUT_MS = 5_000;
 const BUILD_RE = /^\d{4}\.\d{2}\.\d{2}-[0-9A-Za-z][0-9A-Za-z.-]*$/;
 const CLIENT_VERSION_RE = /^cli-[0-9A-Za-z][0-9A-Za-z._-]*$/;
-let cachedResolution;
+// Once per process, not per copy of this package the host loads.
+const cache = processShared("client-version.v1", () => ({}));
 export function resetClientVersionCache() {
-    cachedResolution = undefined;
+    cache.resolution = undefined;
 }
 export function resolveClientVersion() {
-    cachedResolution ??= resolve();
-    return cachedResolution;
+    cache.resolution ??= resolve();
+    return cache.resolution;
 }
 async function resolve() {
     const env = process.env.CURSOR_CLIENT_VERSION?.trim();

package/dist/protocol/conversation-cache-header.d.ts

@@ -0,0 +1,23 @@
+import type { FileHandle } from "node:fs/promises";
+export declare const MAX_CACHE_HEADER_BYTES: number;
+export declare const MAX_CACHE_HEADER_INPUT_BYTES: number;
+export type ConversationCacheHeader = {
+    schemaVersion: number;
+    sessionKey: string;
+    conversationId: string;
+    updatedAt: number;
+};
+export type CacheHeaderResult = {
+    status: "metadata";
+    value: ConversationCacheHeader;
+} | {
+    status: "invalid" | "indeterminate";
+};
+/** A prefix is a retention hint, never evidence of payload/checksum validity. */
+export declare function parseConversationCacheHeader(bytes: Uint8Array): CacheHeaderResult | undefined;
+/**
+ * Inspect an opened generation without reading its checkpoint/blobs/context.
+ * Positional reads leave the handle's offset at zero for subsequent full loading.
+ * Stop BOTH streams on success; merely breaking consumption leaves inflation live.
+ */
+export declare function readConversationCacheHeader(handle: FileHandle, signal?: AbortSignal): Promise<CacheHeaderResult>;

package/dist/protocol/conversation-cache-header.js

@@ -0,0 +1,149 @@
+import { Readable } from "node:stream";
+import { createGunzip } from "node:zlib";
+import { CONVERSATION_CACHE_SCHEMA_VERSION } from "../shared.js";
+export const MAX_CACHE_HEADER_BYTES = 8 * 1024;
+export const MAX_CACHE_HEADER_INPUT_BYTES = 128 * 1024;
+/**
+ * Schema 3 wrote the same canonical fields 1-4 prefix as the current schema, so
+ * its persisted age is trustworthy even though its body is no longer loadable.
+ */
+const OLDEST_CANONICAL_PREFIX_SCHEMA_VERSION = 3;
+/** A prefix is a retention hint, never evidence of payload/checksum validity. */
+export function parseConversationCacheHeader(bytes) {
+    let position = 0;
+    const incomplete = Symbol("incomplete header");
+    const indeterminate = Symbol("noncanonical header");
+    const varint = () => {
+        let value = 0n;
+        for (let index = 0; index < 10; index++) {
+            if (position === bytes.length)
+                throw incomplete;
+            const byte = bytes[position++];
+            if (index === 9 && byte > 1)
+                throw new Error("invalid cache header varint");
+            value |= BigInt(byte & 127) << BigInt(index * 7);
+            if (!(byte & 128))
+                return value;
+        }
+        throw new Error("invalid cache header varint");
+    };
+    const string = () => {
+        const length = varint();
+        if (length > BigInt(MAX_CACHE_HEADER_BYTES))
+            throw indeterminate;
+        const end = position + Number(length);
+        if (end > bytes.length)
+            throw incomplete;
+        const value = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(position, end));
+        position = end;
+        return value;
+    };
+    try {
+        // Only our writer's canonical prefix is eligible for metadata-only pruning.
+        // Other protobuf orders remain loadable through the full decoder.
+        if (varint() !== 8n)
+            return { status: "indeterminate" };
+        // A newer schema may lay out its prefix differently; never age it here.
+        const schemaVersion = varint();
+        if (schemaVersion < BigInt(OLDEST_CANONICAL_PREFIX_SCHEMA_VERSION) ||
+            schemaVersion > BigInt(CONVERSATION_CACHE_SCHEMA_VERSION))
+            return { status: "indeterminate" };
+        if (varint() !== 18n)
+            return { status: "indeterminate" };
+        const sessionKey = string();
+        if (varint() !== 26n)
+            return { status: "indeterminate" };
+        const conversationId = string();
+        if (varint() !== 32n)
+            return { status: "indeterminate" };
+        const updatedAt = Number(varint());
+        if (!sessionKey || !conversationId || !Number.isSafeInteger(updatedAt) || updatedAt < 0) {
+            return { status: "invalid" };
+        }
+        return {
+            status: "metadata",
+            value: { schemaVersion: Number(schemaVersion), sessionKey, conversationId, updatedAt },
+        };
+    }
+    catch (error) {
+        // A fragmented varint/string is normal streaming input, not corrupt data.
+        if (error === incomplete)
+            return undefined;
+        if (error === indeterminate)
+            return { status: "indeterminate" };
+        return { status: "invalid" };
+    }
+}
+/**
+ * Inspect an opened generation without reading its checkpoint/blobs/context.
+ * Positional reads leave the handle's offset at zero for subsequent full loading.
+ * Stop BOTH streams on success; merely breaking consumption leaves inflation live.
+ */
+export function readConversationCacheHeader(handle, signal) {
+    signal?.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const prefix = Buffer.alloc(MAX_CACHE_HEADER_BYTES);
+        let length = 0;
+        let inputBytes = 0;
+        let settled = false;
+        let pendingRead;
+        // Own the positional reads ourselves. Destroying a ReadStream can close an
+        // externally supplied fd on some runtimes, even with autoClose:false.
+        const input = Readable.from((async function* () {
+            let position = 0;
+            while (!settled && position < MAX_CACHE_HEADER_INPUT_BYTES) {
+                const chunk = Buffer.alloc(Math.min(4096, MAX_CACHE_HEADER_INPUT_BYTES - position));
+                const read = handle.read(chunk, 0, chunk.length, position);
+                pendingRead = read;
+                const { bytesRead } = await read;
+                pendingRead = undefined;
+                if (!bytesRead || settled)
+                    return;
+                position += bytesRead;
+                inputBytes += bytesRead;
+                yield chunk.subarray(0, bytesRead);
+            }
+        })(), { objectMode: false, highWaterMark: 4096 });
+        const unzip = createGunzip({ chunkSize: 1024 });
+        const finish = (value, error) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener("abort", abort);
+            input.unpipe(unzip);
+            input.destroy();
+            unzip.destroy();
+            // A read-ahead operation must settle before the caller reuses/closes the
+            // pinned handle. The async generator cannot start another after settled.
+            void Promise.resolve(pendingRead).then(() => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(value);
+            }, reject);
+        };
+        const abort = () => finish(undefined, signal?.reason ?? new Error("cache inspection aborted"));
+        input.on("error", (error) => finish(undefined, error));
+        unzip.on("error", () => finish({
+            status: inputBytes >= MAX_CACHE_HEADER_INPUT_BYTES ? "indeterminate" : "invalid",
+        }));
+        unzip.on("end", () => finish({
+            status: inputBytes >= MAX_CACHE_HEADER_INPUT_BYTES ? "indeterminate" : "invalid",
+        }));
+        unzip.on("data", (chunk) => {
+            const available = Math.min(chunk.length, prefix.length - length);
+            prefix.set(chunk.subarray(0, available), length);
+            length += available;
+            const result = parseConversationCacheHeader(prefix.subarray(0, length));
+            if (result)
+                finish(result);
+            else if (length === prefix.length)
+                finish({ status: "indeterminate" });
+        });
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        else
+            input.pipe(unzip);
+    });
+}

package/dist/protocol/conversation-persistence.d.ts

@@ -13,19 +13,39 @@ export type PersistedConversation = {
     systemPromptHash?: string;
     /** JSON-encoded TurnProvenance (what this provider emitted last). */
     turnProvenance?: string;
+    /**
+     * Host note bodies the last turn ended without delivering (ordered; encoded
+     * via encodePersistedHostNotes). The Cursor checkpoint does not hold them.
+     */
+    hostNote?: string;
+    /** Bounded early-steer delivery receipts for the saved checkpoint. */
+    earlySteers?: string;
+    /** JSON lost-request record: user text sent on a checkpoint Cursor never advanced. */
+    lostRequest?: string;
+    /** Content hashes of the history images `sentImagesCheckpoint` holds. */
+    sentImageHashes?: string[];
+    /** SHA-256 hex of the checkpoint `sentImageHashes` belongs to; without it no image counts as held. */
+    sentImagesCheckpoint?: string;
 };
 export type ConversationLoadStatus = "restored" | "missing" | "invalid" | "expired";
 export type PersistedConversationLoad = {
     status: ConversationLoadStatus;
     value?: PersistedConversation;
 };
+type PersistenceTestPhase = "maintenance-start" | "before-quarantine" | "after-quarantine" | "full-decode" | "directory-opened" | "before-write";
+declare let testHook: ((phase: PersistenceTestPhase, filePath: string) => Promise<void> | void) | undefined;
 export declare function conversationCacheDirectoryPath(cacheDir: string): string;
 export declare function conversationCacheFilePath(cacheDir: string, sessionKey: string): string;
-/** Create the per-session cache directory and prune records older than 24 hours once per process. */
+/** Readiness includes directory permissions only; maintenance never gates hydration. */
 export declare function initializeConversationPersistence(cacheDir: string, now?: number): Promise<void>;
 export declare function getPersistedConversation(cacheDir: string, sessionKey: string, now?: number): Promise<PersistedConversation | undefined>;
 /** Read a snapshot together with the reason restart hydration did not restore it. */
 export declare function loadPersistedConversation(cacheDir: string, sessionKey: string, now?: number): Promise<PersistedConversationLoad>;
+/** Turn provenance of the current snapshot, without decoding its payload. */
+export declare function getPersistedTurnProvenance(cacheDir: string, sessionKey: string, now?: number): Promise<{
+    conversationId: string;
+    turnProvenance: string;
+} | undefined>;
 /** Replace one session's durable snapshot and refresh its 24-hour lease. */
 export declare function persistConversation(cacheDir: string, value: Omit<PersistedConversation, "updatedAt" | "postCompactionRebase" | "toolCatalog"> & {
     postCompactionRebase?: boolean;
@@ -33,4 +53,10 @@ export declare function persistConversation(cacheDir: string, value: Omit<Persis
 }, now?: number): Promise<void>;
 /** Delete only the expected binding so an overlapping newer turn cannot be removed. */
 export declare function deletePersistedConversation(cacheDir: string, sessionKey: string, expectedConversationId?: string): Promise<void>;
+/** Full snapshots still held in memory; the store should keep heads only. */
+export declare function retainedConversationSnapshotsForTests(): Promise<number>;
 export declare function resetConversationPersistenceForTests(): void;
+/** Deterministic maintenance barriers/race injection; not a request-path API. */
+export declare function setConversationPersistenceHookForTests(hook?: typeof testHook): void;
+export declare function waitForConversationMaintenanceForTests(cacheDir: string, now?: number): Promise<void>;
+export {};