From 12ac431d95d5fb61512ef9cb4bd39a727b3712e1 Mon Sep 17 00:00:00 2001 From: yuwk <1729065730@qq.com> Date: Sat, 31 Oct 2026 12:37:00 +0800 Subject: [PATCH 1/3] fix(cursor-cli): ignore background task notification records in turn identity cursor-agent 2026.10.22 appends its own user records to the ACP session store when a background shell task finishes. Those records carry a task notification payload in field 15 and a body, and they can land inside the same prompt as the Host turn. The terminal check required exactly one new native user record whose text matched the prompt, so any turn during which a background task finished was rewritten from succeeded to failed with "Cursor terminal has no unique, verified native turn identity", without a nativeTurnRef or fork checkpoint. Mark field-15 records as notifications when reading native history and verify the turn identity against the non-notification records only, while still requiring an unchanged prefix and exactly one matching prompt record. Signed-off-by: Vincent <1729065730@qq.com> --- packages/adapters/cursor-cli/src/adapter.ts | 15 +++-- .../adapters/cursor-cli/src/native-history.ts | 4 ++ .../adapters/cursor-cli/test/cursor.test.ts | 64 ++++++++++++++++++- .../cursor-cli/test/native-history.test.ts | 31 ++++++++- 4 files changed, 105 insertions(+), 9 deletions(-) diff --git a/packages/adapters/cursor-cli/src/adapter.ts b/packages/adapters/cursor-cli/src/adapter.ts index 01deb6edb..d42c62039 100644 --- a/packages/adapters/cursor-cli/src/adapter.ts +++ b/packages/adapters/cursor-cli/src/adapter.ts @@ -814,24 +814,29 @@ export class CursorSession implements HarnessSession { if (administrative && JSON.stringify(before) === JSON.stringify(after)) { // This native command returns a local message without persisting a user Turn. } else { + // Cursor appends its own user records when a background task finishes; those are not + // the echo of this prompt and must not make the prompt's identity ambiguous. + const prompted = added.filter((turn) => !turn.notification); + const own = prompted[0]; if ( - added.length !== 1 || - after.length !== before.length + 1 || + !own || + prompted.length !== 1 || + after.length !== before.length + added.length || before.some((turn, index) => after[index]?.id !== turn.id) || - added[0]?.text !== command.input.map((part) => part.text).join("\n") + own.text !== command.input.map((part) => part.text).join("\n") ) throw new Error("Cursor terminal has no unique, verified native turn identity"); nativeTurnRef = nativeTurnRefSchema.parse({ harnessId: "cursor-cli", nativeSessionId: this.transport.sessionId, - nativeTurnKey: added[0].id, + nativeTurnKey: own.id, formatVersion: 1, }); this.#fresh = false; if (outcome.status === "succeeded" && cursorForkAvailable()) outcome = { ...outcome, - checkpoint: cursorCheckpoint(this.transport.sessionId, added[0].id), + checkpoint: cursorCheckpoint(this.transport.sessionId, own.id), }; } } catch (error) { diff --git a/packages/adapters/cursor-cli/src/native-history.ts b/packages/adapters/cursor-cli/src/native-history.ts index 757a4555d..272ba278e 100644 --- a/packages/adapters/cursor-cli/src/native-history.ts +++ b/packages/adapters/cursor-cli/src/native-history.ts @@ -8,6 +8,9 @@ export interface CursorNativeTurn { text: string; /** Native conversation root immediately before this user turn, when available. */ rewindRoot?: string; + /** Cursor wrote this user record itself to report a finished background task (field 15), + * not as the echo of a prompt the Host submitted. */ + notification?: true; } export function cursorConfigDirectory(environment: NodeJS.ProcessEnv): string { @@ -140,6 +143,7 @@ export function readCursorNativeHistory( id, text: one(user, 1).toString("utf8"), ...(rewindRoot ? { rewindRoot } : {}), + ...(user.get(15)?.length ? { notification: true as const } : {}), }); } } diff --git a/packages/adapters/cursor-cli/test/cursor.test.ts b/packages/adapters/cursor-cli/test/cursor.test.ts index 333e72b11..570395604 100644 --- a/packages/adapters/cursor-cli/test/cursor.test.ts +++ b/packages/adapters/cursor-cli/test/cursor.test.ts @@ -14,7 +14,9 @@ import { cursorModelRef, cursorCatalog, cursorNativeModel } from "../src/models. import { CursorInteractions } from "../src/interactions.js"; import { cursorSnapshot } from "../src/projection.js"; -const native = vi.hoisted(() => ({ turns: [] as Array<{ id: string; text: string }> })); +const native = vi.hoisted(() => ({ + turns: [] as Array<{ id: string; text: string; notification?: true }>, +})); vi.mock("../src/native-history.js", () => ({ readCursorNativeTurns: () => structuredClone(native.turns), readCursorNativeHistory: () => ({ @@ -287,6 +289,66 @@ describe("Cursor turn lifecycle", () => { }), ); }); + it("keeps the prompt identity when Cursor appends background task notifications", async () => { + const f = session(); + const notification = (id: string) => + native.turns.push({ + id: randomUUID(), + text: `\n\ntask_id: ${id}\n\n`, + notification: true, + }); + notification("before"); + f.transport.action = async (text, callbacks) => { + callbacks.update({ + sessionId: info.sessionId, + update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "ok" } }, + }); + native.turns.push({ id: randomUUID(), text }); + notification("one"); + notification("two"); + return { stopReason: "end_turn" }; + }; + await f.session.execute(start); + await vi.waitFor(() => + expect(f.output.some((x) => x.kind === "event" && x.event.type === "turn.completed")).toBe( + true, + ), + ); + await f.session.close(); + await f.done; + const terminal = f.output.filter( + (x) => x.kind === "event" && x.event.type === "turn.completed", + ); + expect(terminal[0]).toMatchObject({ + event: { + outcome: { status: "succeeded" }, + nativeTurnRef: { nativeTurnKey: native.turns[1]?.id }, + }, + }); + }); + it("still fails when only background task notifications were added", async () => { + const f = session(); + f.transport.action = async () => { + native.turns.push({ id: randomUUID(), text: "", notification: true }); + return { stopReason: "end_turn" }; + }; + await f.session.execute(start); + await vi.waitFor(() => + expect(f.output.some((x) => x.kind === "event" && x.event.type === "turn.completed")).toBe( + true, + ), + ); + await f.session.close(); + await f.done; + expect(f.output).toContainEqual( + expect.objectContaining({ + event: expect.objectContaining({ + type: "turn.completed", + outcome: expect.objectContaining({ status: "failed" }), + }), + }), + ); + }); it("rejects a concurrent turn and closes pending approval on cancel", async () => { const f = session(); f.transport.action = async (text, callbacks) => { diff --git a/packages/adapters/cursor-cli/test/native-history.test.ts b/packages/adapters/cursor-cli/test/native-history.test.ts index a5aa2a4e2..54cd1733a 100644 --- a/packages/adapters/cursor-cli/test/native-history.test.ts +++ b/packages/adapters/cursor-cli/test/native-history.test.ts @@ -22,7 +22,7 @@ function field(id: number, value: Buffer | string) { const data = Buffer.isBuffer(value) ? value : Buffer.from(value); return Buffer.concat([varint(id * 8 + 2), varint(data.length), data]); } -function fixture(texts = ["first", "second"]) { +function fixture(texts = ["first", "second"], notifications: number[] = []) { const home = mkdtempSync(path.join(os.tmpdir(), "codexhost-cursor-history-")); temporary.push(home); const sessionId = randomUUID(); @@ -38,13 +38,31 @@ function fixture(texts = ["first", "second"]) { db.prepare("INSERT OR IGNORE INTO blobs VALUES(?,?)").run(id.toString("hex"), data); return id; }; - const turns = texts.map((text) => ({ id: randomUUID(), text })); + const turns = texts.map((text, index) => ({ + id: randomUUID(), + text, + ...(notifications.includes(index) ? { notification: true as const } : {}), + })); const root = put( Buffer.concat( turns.map((turn) => field( 8, - put(field(1, field(1, put(Buffer.concat([field(1, turn.text), field(2, turn.id)]))))), + put( + field( + 1, + field( + 1, + put( + Buffer.concat([ + field(1, turn.text), + field(2, turn.id), + ...(turn.notification ? [field(15, field(1, "background task"))] : []), + ]), + ), + ), + ), + ), ), ), ), @@ -81,6 +99,13 @@ describe("Cursor read-only native identity", () => { ); expect(readCursorNativeTurns(f.sessionId, requested, { HOME: f.home })).toEqual(f.turns); }); + it("marks user records Cursor wrote for finished background tasks", () => { + const f = fixture(["prompt", "task finished"], [1]); + const turns = readCursorNativeTurns(f.sessionId, f.home, { HOME: f.home }); + expect(turns).toEqual(f.turns); + expect(turns[0]).not.toHaveProperty("notification"); + expect(turns[1]).toMatchObject({ notification: true }); + }); it("allows a new empty history without inventing IDs", () => { const f = fixture([]); expect(readCursorNativeTurns(f.sessionId, f.home, { HOME: f.home })).toEqual([]); From 760fee2e3758067393f2454c5a25c7a234b7bec2 Mon Sep 17 00:00:00 2001 From: "chongwen.zhang" Date: Sat, 31 Oct 2026 21:14:59 +0800 Subject: [PATCH 2/3] test(cursor-cli): verify notification-safe checkpoint identity --- docs/harnesses/cursor/cursor-cli-experimental.md | 10 +++++++++- packages/adapters/cursor-cli/test/cursor.test.ts | 11 ++++++++++- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/harnesses/cursor/cursor-cli-experimental.md b/docs/harnesses/cursor/cursor-cli-experimental.md index 00af94cbc..c19ef83a4 100644 --- a/docs/harnesses/cursor/cursor-cli-experimental.md +++ b/docs/harnesses/cursor/cursor-cli-experimental.md @@ -83,7 +83,15 @@ references. This is an undocumented native format, not a supported Cursor API. The snapshot body comes from native ACP `session/load` and is reused only while the native history root is unchanged. It is accepted only when session, workspace, turn count, order and exact prompt text match native -history. A successful live turn must introduce exactly one native user-turn ID. +history. A successful live turn must introduce exactly one non-notification native +user-turn ID whose text matches the submitted prompt, while preserving the existing +history prefix. Both the terminal identity and an available checkpoint use that ID. +In the observed Cursor CLI `2026.10.22-27dcf5f` store, background task completion +records carry field 15 (`simulated_message_metadata`). Records with this field are +treated as Cursor-generated notifications for live prompt identity verification; +they remain in the native history for replay and Fork boundaries. This field is not +a dedicated notification flag, and other native versions or simulated message types +are not established by this compatibility rule. Missing/ambiguous history is an error; generated UUIDs, array positions and text hashes are never used as native turn keys. The adapter keeps no shadow transcript. diff --git a/packages/adapters/cursor-cli/test/cursor.test.ts b/packages/adapters/cursor-cli/test/cursor.test.ts index 570395604..b4e9f876e 100644 --- a/packages/adapters/cursor-cli/test/cursor.test.ts +++ b/packages/adapters/cursor-cli/test/cursor.test.ts @@ -13,6 +13,7 @@ import { CursorTransport, type CursorCallbacks } from "../src/transport.js"; import { cursorModelRef, cursorCatalog, cursorNativeModel } from "../src/models.js"; import { CursorInteractions } from "../src/interactions.js"; import { cursorSnapshot } from "../src/projection.js"; +import * as forkSupport from "../src/fork-support.js"; const native = vi.hoisted(() => ({ turns: [] as Array<{ id: string; text: string; notification?: true }>, @@ -290,6 +291,7 @@ describe("Cursor turn lifecycle", () => { ); }); it("keeps the prompt identity when Cursor appends background task notifications", async () => { + vi.spyOn(forkSupport, "cursorForkAvailable").mockReturnValue(true); const f = session(); const notification = (id: string) => native.turns.push({ @@ -321,7 +323,14 @@ describe("Cursor turn lifecycle", () => { ); expect(terminal[0]).toMatchObject({ event: { - outcome: { status: "succeeded" }, + outcome: { + status: "succeeded", + checkpoint: { + harnessId: "cursor-cli", + nativeSessionId: info.sessionId, + checkpointId: native.turns[1]?.id, + }, + }, nativeTurnRef: { nativeTurnKey: native.turns[1]?.id }, }, }); From 25a10e52dec5641643d1ad33e84fc5cc50c4bc91 Mon Sep 17 00:00:00 2001 From: "chongwen.zhang" Date: Sat, 31 Oct 2026 21:23:14 +0800 Subject: [PATCH 3/3] fix(cursor-cli): require a usable rewind boundary for checkpoints --- .../cursor/cursor-cli-experimental.md | 4 + packages/adapters/cursor-cli/src/adapter.ts | 7 +- .../adapters/cursor-cli/test/cursor.test.ts | 98 ++++++++++--------- 3 files changed, 63 insertions(+), 46 deletions(-) diff --git a/docs/harnesses/cursor/cursor-cli-experimental.md b/docs/harnesses/cursor/cursor-cli-experimental.md index c19ef83a4..634937b6d 100644 --- a/docs/harnesses/cursor/cursor-cli-experimental.md +++ b/docs/harnesses/cursor/cursor-cli-experimental.md @@ -86,6 +86,10 @@ when session, workspace, turn count, order and exact prompt text match native history. A successful live turn must introduce exactly one non-notification native user-turn ID whose text matches the submitted prompt, while preserving the existing history prefix. Both the terminal identity and an available checkpoint use that ID. +A checkpoint is offered only when Fork is supported and the prompt is the last +native record or the next record has a verified native rewind root, matching replay +projection and Fork validation. Missing rewind roots do not invalidate the Turn's +successful outcome or native identity. In the observed Cursor CLI `2026.10.22-27dcf5f` store, background task completion records carry field 15 (`simulated_message_metadata`). Records with this field are treated as Cursor-generated notifications for live prompt identity verification; diff --git a/packages/adapters/cursor-cli/src/adapter.ts b/packages/adapters/cursor-cli/src/adapter.ts index d42c62039..294efa6d8 100644 --- a/packages/adapters/cursor-cli/src/adapter.ts +++ b/packages/adapters/cursor-cli/src/adapter.ts @@ -833,7 +833,12 @@ export class CursorSession implements HarnessSession { formatVersion: 1, }); this.#fresh = false; - if (outcome.status === "succeeded" && cursorForkAvailable()) + const ownIndex = after.findIndex((turn) => turn.id === own.id); + if ( + outcome.status === "succeeded" && + cursorForkAvailable() && + (ownIndex === after.length - 1 || after[ownIndex + 1]?.rewindRoot) + ) outcome = { ...outcome, checkpoint: cursorCheckpoint(this.transport.sessionId, own.id), diff --git a/packages/adapters/cursor-cli/test/cursor.test.ts b/packages/adapters/cursor-cli/test/cursor.test.ts index b4e9f876e..7f84b2ce0 100644 --- a/packages/adapters/cursor-cli/test/cursor.test.ts +++ b/packages/adapters/cursor-cli/test/cursor.test.ts @@ -16,7 +16,7 @@ import { cursorSnapshot } from "../src/projection.js"; import * as forkSupport from "../src/fork-support.js"; const native = vi.hoisted(() => ({ - turns: [] as Array<{ id: string; text: string; notification?: true }>, + turns: [] as Array<{ id: string; text: string; notification?: true; rewindRoot?: string }>, })); vi.mock("../src/native-history.js", () => ({ readCursorNativeTurns: () => structuredClone(native.turns), @@ -290,51 +290,59 @@ describe("Cursor turn lifecycle", () => { }), ); }); - it("keeps the prompt identity when Cursor appends background task notifications", async () => { - vi.spyOn(forkSupport, "cursorForkAvailable").mockReturnValue(true); - const f = session(); - const notification = (id: string) => - native.turns.push({ - id: randomUUID(), - text: `\n\ntask_id: ${id}\n\n`, - notification: true, - }); - notification("before"); - f.transport.action = async (text, callbacks) => { - callbacks.update({ - sessionId: info.sessionId, - update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "ok" } }, - }); - native.turns.push({ id: randomUUID(), text }); - notification("one"); - notification("two"); - return { stopReason: "end_turn" }; - }; - await f.session.execute(start); - await vi.waitFor(() => - expect(f.output.some((x) => x.kind === "event" && x.event.type === "turn.completed")).toBe( - true, - ), - ); - await f.session.close(); - await f.done; - const terminal = f.output.filter( - (x) => x.kind === "event" && x.event.type === "turn.completed", - ); - expect(terminal[0]).toMatchObject({ - event: { - outcome: { - status: "succeeded", - checkpoint: { - harnessId: "cursor-cli", - nativeSessionId: info.sessionId, - checkpointId: native.turns[1]?.id, - }, + it.each([true, false])( + "keeps prompt identity with notifications (rewind anchor=%s)", + async (hasRewindRoot) => { + vi.spyOn(forkSupport, "cursorForkAvailable").mockReturnValue(true); + const f = session(); + const notification = (id: string) => + native.turns.push({ + id: randomUUID(), + text: `\n\ntask_id: ${id}\n\n`, + notification: true, + ...(hasRewindRoot ? { rewindRoot: "a".repeat(64) } : {}), + }); + notification("before"); + f.transport.action = async (text, callbacks) => { + callbacks.update({ + sessionId: info.sessionId, + update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "ok" } }, + }); + native.turns.push({ id: randomUUID(), text }); + notification("one"); + notification("two"); + return { stopReason: "end_turn" }; + }; + await f.session.execute(start); + await vi.waitFor(() => + expect(f.output.some((x) => x.kind === "event" && x.event.type === "turn.completed")).toBe( + true, + ), + ); + await f.session.close(); + await f.done; + const terminal = f.output.filter( + (x) => x.kind === "event" && x.event.type === "turn.completed", + ); + expect(terminal[0]).toMatchObject({ + event: { + outcome: { status: "succeeded" }, + nativeTurnRef: { nativeTurnKey: native.turns[1]?.id }, }, - nativeTurnRef: { nativeTurnKey: native.turns[1]?.id }, - }, - }); - }); + }); + if (hasRewindRoot) { + expect(terminal[0]).toHaveProperty("event.outcome.checkpoint", { + harnessId: "cursor-cli", + nativeSessionId: info.sessionId, + checkpointId: native.turns[1]?.id, + locator: { kind: "cursor-turn" }, + formatVersion: 1, + }); + } else { + expect(terminal[0]).not.toHaveProperty("event.outcome.checkpoint"); + } + }, + ); it("still fails when only background task notifications were added", async () => { const f = session(); f.transport.action = async () => {