pi-cursor-sdk 0.4.0 → 0.5.0

package/dist/cursor-cloud-lifecycle.js

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
-import { closeSync, constants, existsSync, fchmodSync, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, readSync, writeFileSync } from "node:fs";
+import { closeSync, constants, existsSync, fchmodSync, fstatSync, fsyncSync, openSync, readFileSync, readSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { resolveCursorApiKey } from "./cursor-api-key.js";
 import { MAX_CLOUD_REPORT_BRANCHES, } from "./cursor-cloud-reporting.js";
 import { CLOUD_AGENT_ID_PATTERN, CLOUD_LIFECYCLE_ENTRY_TYPE, CLOUD_LIFECYCLE_JOURNAL_PREFIX, } from "../shared/cursor-cloud-lifecycle-constants.mjs";
-import { fsyncExistingRegularFile, noFollowFlag, openExistingRegularFileNoFollow } from "./cursor-durable-fs.js";
+import { createRegularFileExclusive, fsyncExistingRegularFile, openExistingRegularFileNoFollow } from "./cursor-durable-fs.js";
 import { truncateCursorDisplayLine } from "./cursor-display-text.js";
 import { asRecord, getString } from "./cursor-record-utils.js";
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
@@ -19,6 +19,7 @@ const MAX_LIST_RECORDS = 25;
 const MAX_CLOUD_AGENT_ID_ERROR_LENGTH = 256;
 const DURABLE_LEDGER_VERSION = 1;
 const DURABLE_LEDGER_PREFIX = CLOUD_LIFECYCLE_JOURNAL_PREFIX;
+const cloudBindings = new Map();
 let cloudLifecycleApi;
 let cloudLifecycleSession = {};
 let durableWriterForTests;
@@ -111,52 +112,29 @@ function buildBaseEntry(agentId, action) {
     };
 }
 function captureCloudLifecycleSession(ctx) {
-    cloudLifecycleSession = {
-        sessionFile: ctx.sessionManager.getSessionFile?.() ?? undefined,
-        sessionId: ctx.sessionManager.getSessionId?.() ?? undefined,
-        getBranch: () => ctx.sessionManager.getBranch(),
+    const manager = ctx.sessionManager;
+    return {
+        sessionFile: manager.getSessionFile() ?? undefined,
+        sessionId: manager.getSessionId(),
+        getBranch: () => manager.getBranch(),
     };
 }
 function durableLedgerPath(sessionFile, sessionId) {
     const sessionHash = createHash("sha256").update(sessionId).digest("hex").slice(0, 32);
     return join(dirname(sessionFile), `${DURABLE_LEDGER_PREFIX}-${sessionHash}.journal`);
 }
-function sameFileIdentity(left, right) {
-    return left.dev === right.dev && left.ino === right.ino;
-}
-function createRegularFileExclusive(path, flags, mode) {
-    let fd;
-    try {
-        fd = openSync(path, flags | constants.O_CREAT | constants.O_EXCL | noFollowFlag(), mode);
-        const opened = fstatSync(fd);
-        const after = lstatSync(path);
-        if (!opened.isFile() || !after.isFile() || !sameFileIdentity(opened, after)) {
-            throw new Error("created journal path changed while opening");
-        }
-        return fd;
-    }
-    catch (error) {
-        if (fd !== undefined) {
-            try {
-                closeSync(fd);
-            }
-            catch { }
-        }
-        throw error;
-    }
-}
-function fsyncCloudLifecycleSessionFile() {
+function fsyncCloudLifecycleSessionFile(session) {
     if (sessionFsyncForTests)
         return sessionFsyncForTests();
-    const sessionFile = cloudLifecycleSession.sessionFile;
+    const sessionFile = session.sessionFile;
     if (!sessionFile || !existsSync(sessionFile))
         return true;
     return fsyncExistingRegularFile(sessionFile);
 }
-function appendDurableCloudLifecycleEntry(data, anchorEntryId) {
+function appendDurableCloudLifecycleEntry(data, anchorEntryId, session) {
     if (durableWriterForTests)
         return durableWriterForTests(data);
-    const { sessionFile, sessionId } = cloudLifecycleSession;
+    const { sessionFile, sessionId } = session;
     if (!sessionFile || !sessionId)
         return false;
     const entry = {
@@ -210,14 +188,14 @@ function appendDurableCloudLifecycleEntry(data, anchorEntryId) {
         }
     }
 }
-function appendCloudLifecycleEntry(pi, data) {
-    if (!data || (!durableWriterForTests && (!cloudLifecycleSession.sessionFile || !cloudLifecycleSession.sessionId)))
+function appendCloudLifecycleEntry(pi, data, session) {
+    if (!data || (!durableWriterForTests && (!session.sessionFile || !session.sessionId)))
         return false;
     let anchorEntryId;
     try {
-        const previousEntryId = durableWriterForTests ? undefined : cloudLifecycleSession.getBranch?.().at(-1)?.id;
+        const previousEntryId = durableWriterForTests ? undefined : session.getBranch?.().at(-1)?.id;
         pi.appendEntry(CLOUD_LIFECYCLE_ENTRY_TYPE, data);
-        const anchor = cloudLifecycleSession.getBranch?.().at(-1);
+        const anchor = session.getBranch?.().at(-1);
         anchorEntryId = durableWriterForTests
             ? "test-cloud-lifecycle-entry"
             : anchor?.type === "custom" &&
@@ -230,15 +208,14 @@ function appendCloudLifecycleEntry(pi, data) {
         return false;
     }
     return anchorEntryId !== undefined &&
-        fsyncCloudLifecycleSessionFile() &&
-        appendDurableCloudLifecycleEntry(data, anchorEntryId);
+        fsyncCloudLifecycleSessionFile(session) &&
+        appendDurableCloudLifecycleEntry(data, anchorEntryId, session);
 }
-function appendCloudLifecycleMutationEntry(pi, ctx, data) {
-    const anchorEntryId = ctx.sessionManager.getBranch().at(-1)?.id;
-    if (!data || !anchorEntryId || !fsyncCloudLifecycleSessionFile() || !appendDurableCloudLifecycleEntry(data, anchorEntryId))
+function appendCloudLifecycleMutationEntry(pi, data, session, anchorEntryId) {
+    if (!data || !anchorEntryId || !fsyncCloudLifecycleSessionFile(session) || !appendDurableCloudLifecycleEntry(data, anchorEntryId, session))
         return false;
     try {
-        pi.appendEntry(CLOUD_LIFECYCLE_ENTRY_TYPE, data);
+        pi?.appendEntry(CLOUD_LIFECYCLE_ENTRY_TYPE, data);
     }
     catch {
         // The fsynced mutation journal is authoritative.
@@ -247,12 +224,20 @@ function appendCloudLifecycleMutationEntry(pi, ctx, data) {
 }
 export function registerCursorCloudLifecycleLedger(pi) {
     cloudLifecycleApi = pi;
-    pi.on("session_start", (_event, ctx) => captureCloudLifecycleSession(ctx));
-    pi.on("before_agent_start", (_event, ctx) => captureCloudLifecycleSession(ctx));
-    pi.on("session_tree", (_event, ctx) => captureCloudLifecycleSession(ctx));
+    const binding = { api: pi, session: {} };
+    cloudBindings.set(pi, binding);
+    const capture = (ctx) => {
+        binding.session = captureCloudLifecycleSession(ctx);
+        cloudLifecycleSession = binding.session;
+    };
+    pi.on("session_start", (_event, ctx) => capture(ctx));
+    pi.on("before_agent_start", (_event, ctx) => capture(ctx));
+    pi.on("session_tree", (_event, ctx) => capture(ctx));
+    pi.on("session_shutdown", () => { cloudBindings.delete(pi); });
 }
 export function recordCursorCloudLifecycleRun(report, options = {}) {
-    if (!cloudLifecycleApi)
+    const api = options.binding?.api ?? cloudLifecycleApi;
+    if (!api)
         return false;
     const baseEntry = buildBaseEntry(report.agentId, "record");
     if (!baseEntry)
@@ -261,19 +246,26 @@ export function recordCursorCloudLifecycleRun(report, options = {}) {
     const runId = typeof report.runId === "string"
         ? sanitizeLedgerString(report.runId, MAX_LEDGER_RUN_ID_LENGTH, options.apiKey)
         : "";
-    return appendCloudLifecycleEntry(cloudLifecycleApi, {
+    return appendCloudLifecycleEntry(api, {
         ...baseEntry,
         ...(runId ? { runId } : {}),
         ...(branches ? { branches } : {}),
-    });
-}
-export function recordCursorCloudLifecycleSafely(report, apiKey) {
-    try {
-        return recordCursorCloudLifecycleRun({ ...report, branches: [] }, { apiKey });
-    }
-    catch {
-        return false;
-    }
+    }, options.binding?.session ?? cloudLifecycleSession);
+}
+export function captureCursorCloudLifecycleRecorder(owner) {
+    const current = owner ? cloudBindings.get(owner) : undefined;
+    const api = current?.api ?? (owner ? undefined : cloudLifecycleApi);
+    const session = { ...(current?.session ?? (owner ? {} : cloudLifecycleSession)) };
+    return (report, apiKey) => {
+        if (!api)
+            return false;
+        try {
+            return recordCursorCloudLifecycleRun({ ...report, branches: report.branches ?? [] }, { apiKey, binding: { api, session } });
+        }
+        catch {
+            return false;
+        }
+    };
 }
 export function createCursorCloudLifecyclePersistenceError(agentId, phase, cancellationConfirmed, apiKey) {
     const boundedAgentId = truncateCursorDisplayLine(scrubSensitiveText(agentId, apiKey), MAX_CLOUD_AGENT_ID_ERROR_LENGTH);
@@ -357,9 +349,8 @@ function readCursorCloudLifecycleEntries(entries) {
 export function readCursorCloudLifecycleAgents(entries) {
     return reduceCloudLifecycleEntries(readCursorCloudLifecycleEntries(entries));
 }
-function readDurableCloudLifecycleJournal(ctx) {
-    const sessionFile = ctx.sessionManager.getSessionFile?.();
-    const sessionId = ctx.sessionManager.getSessionId?.();
+function readDurableCloudLifecycleJournal(session) {
+    const { sessionFile, sessionId } = session;
     if (!sessionFile || !sessionId)
         return [];
     let fd;
@@ -403,13 +394,13 @@ function readDurableCloudLifecycleJournal(ctx) {
     }
     return entries;
 }
-function readDurableCloudLifecycleEntries(ctx) {
-    const sessionFile = ctx.sessionManager.getSessionFile?.();
+function readDurableCloudLifecycleEntries(session) {
+    const { sessionFile } = session;
     if (!sessionFile)
         return [];
     const fileless = !existsSync(sessionFile);
-    const branchIds = new Set(ctx.sessionManager.getBranch().map((entry) => entry.id));
-    return readDurableCloudLifecycleJournal(ctx).flatMap((entry) => {
+    const branchIds = new Set((session.getBranch?.() ?? []).map((entry) => entry.id));
+    return readDurableCloudLifecycleJournal(session).flatMap((entry) => {
         if (entry.data.action !== "record")
             return [entry.data];
         if (fileless)
@@ -420,18 +411,18 @@ function readDurableCloudLifecycleEntries(ctx) {
 function cloudLifecycleEntryKey(data) {
     return JSON.stringify([data.action, data.agentId, data.runId, data.timestamp, data.branches]);
 }
-function reconcileDurableCloudLifecycleOrphans(pi, ctx) {
-    const sessionFile = ctx.sessionManager.getSessionFile?.();
+function reconcileDurableCloudLifecycleOrphans(pi, session) {
+    const { sessionFile } = session;
     if (!sessionFile || !existsSync(sessionFile))
         return true;
-    const journal = readDurableCloudLifecycleJournal(ctx);
+    const journal = readDurableCloudLifecycleJournal(session);
     const claimedAgentIds = new Set(journal.flatMap((entry) => entry.data.action === "record" && entry.anchorEntryId !== null ? [entry.data.agentId] : []));
     const latestOrphanByAgent = new Map();
     for (const entry of journal) {
         if (entry.data.action === "record" && entry.anchorEntryId === null)
             latestOrphanByAgent.set(entry.data.agentId, entry);
     }
-    const branch = ctx.sessionManager.getBranch();
+    const branch = session.getBranch?.() ?? [];
     for (const [agentId, orphan] of latestOrphanByAgent) {
         if (claimedAgentIds.has(agentId))
             continue;
@@ -447,25 +438,25 @@ function reconcileDurableCloudLifecycleOrphans(pi, ctx) {
             }
         }
         if (matchingEntry) {
-            if (!fsyncCloudLifecycleSessionFile() || !appendDurableCloudLifecycleEntry(orphan.data, matchingEntry.id))
+            if (!fsyncCloudLifecycleSessionFile(session) || !appendDurableCloudLifecycleEntry(orphan.data, matchingEntry.id, session))
                 return false;
             continue;
         }
-        if (orphan.sessionFile !== sessionFile && !appendCloudLifecycleEntry(pi, orphan.data))
+        if (orphan.sessionFile !== sessionFile && !appendCloudLifecycleEntry(pi, orphan.data, session))
             return false;
     }
     return true;
 }
-function reconcileDurableCloudLifecycleOrphansForCommand(pi, ctx) {
-    if (reconcileDurableCloudLifecycleOrphans(pi, ctx))
+function reconcileDurableCloudLifecycleOrphansForCommand(pi, ctx, session) {
+    if (reconcileDurableCloudLifecycleOrphans(pi, session))
         return true;
     ctx.ui.notify("Unable to reconcile the durable Cursor cloud lifecycle journal with this session branch.", "error");
     return false;
 }
-function readRecordedCloudAgents(ctx) {
-    const durableEntries = readDurableCloudLifecycleEntries(ctx);
+function readRecordedCloudAgents(session) {
+    const durableEntries = readDurableCloudLifecycleEntries(session);
     const durableKeys = new Set(durableEntries.map(cloudLifecycleEntryKey));
-    const branchOnlyEntries = readCursorCloudLifecycleEntries(ctx.sessionManager.getBranch())
+    const branchOnlyEntries = readCursorCloudLifecycleEntries(session.getBranch?.() ?? [])
         .filter((entry) => !durableKeys.has(cloudLifecycleEntryKey(entry)));
     return reduceCloudLifecycleEntries([...durableEntries, ...branchOnlyEntries]);
 }
@@ -544,40 +535,78 @@ async function resolveCloudLifecycleMutationApiKey(ctx) {
     return undefined;
 }
 async function mutateRecordedCloudAgent(params) {
-    const records = readRecordedCloudAgents(params.ctx);
-    const validationError = validateRecordedCloudAgentId(params.agentId, records, params.action);
+    const manager = params.ctx.sessionManager;
+    const ui = params.ctx.ui;
+    const modelRegistry = params.ctx.modelRegistry;
+    const binding = cloudBindings.get(params.pi);
+    let anchorEntryId = manager.getBranch().at(-1)?.id;
+    // Include recoverable fileless records before auth, without writing anything
+    // until credentials are available. General provider recording stays live.
+    const readAuthority = () => JSON.stringify([readRecordedCloudAgents(params.session), readDurableCloudLifecycleJournal(params.session)]);
+    let authority = readAuthority();
+    const isOriginCurrent = () => {
+        try {
+            return cloudBindings.get(params.pi) === binding &&
+                params.ctx.sessionManager === manager &&
+                manager.getSessionFile() === params.session.sessionFile &&
+                manager.getSessionId() === params.session.sessionId &&
+                manager.getBranch().at(-1)?.id === anchorEntryId;
+        }
+        catch {
+            return false; // Pi invalidates the command context on owning reload.
+        }
+    };
+    const checkAuthority = () => {
+        if (isOriginCurrent() && readAuthority() === authority)
+            return true;
+        ui.notify(`Cursor cloud ${params.action} was not started because its originating session branch or authority changed. Retry from the intended branch.`, "error");
+        return false;
+    };
+    const apiKey = await resolveCloudLifecycleMutationApiKey({ modelRegistry, ui, sessionManager: manager });
+    if (!apiKey || !checkAuthority())
+        return;
+    if (!reconcileDurableCloudLifecycleOrphansForCommand(params.pi, { modelRegistry, ui, sessionManager: manager }, params.session))
+        return;
+    // Reconciliation may append only the unchanged, captured orphan authority.
+    anchorEntryId = manager.getBranch().at(-1)?.id;
+    authority = readAuthority();
+    const validationError = validateRecordedCloudAgentId(params.agentId, readRecordedCloudAgents(params.session), params.action);
     if (validationError) {
-        params.ctx.ui.notify(validationError, "error");
+        ui.notify(validationError, "error");
         return;
     }
-    const apiKey = params.apiKey;
     let operations;
     try {
         operations = await getSdkOperations();
     }
     catch (error) {
-        params.ctx.ui.notify(`Failed to prepare Cursor cloud ${params.action}: ${formatCloudLifecycleError(error, apiKey)}`, "error");
+        ui.notify(`Failed to prepare Cursor cloud ${params.action}: ${formatCloudLifecycleError(error, apiKey)}`, "error");
         return;
     }
-    if (!appendCloudLifecycleMutationEntry(params.pi, params.ctx, buildBaseEntry(params.agentId, params.action === "archive" ? "archive_intent" : "delete_intent"))) {
-        params.ctx.ui.notify(`Cursor cloud ${params.action} was not started because its durable intent could not be recorded.`, "error");
+    if (!checkAuthority())
+        return;
+    if (!appendCloudLifecycleMutationEntry(params.pi, buildBaseEntry(params.agentId, params.action === "archive" ? "archive_intent" : "delete_intent"), params.session, anchorEntryId)) {
+        ui.notify(`Cursor cloud ${params.action} was not started because its durable intent could not be recorded.`, "error");
         return;
     }
+    // After SDK start the actual result belongs to this journal and post-intent
+    // anchor, even if Pi replaces the context or selects another branch.
+    anchorEntryId = manager.getBranch().at(-1)?.id;
     try {
         await operations[params.action](params.agentId, { apiKey });
     }
     catch (error) {
-        params.ctx.ui.notify(`Cursor cloud ${params.action} for agent ${params.agentId} is unresolved: ${formatCloudLifecycleError(error, apiKey)} Inspect it in the Cursor Cloud dashboard before retrying.`, "error");
+        ui.notify(`Cursor cloud ${params.action} for agent ${params.agentId} is unresolved: ${formatCloudLifecycleError(error, apiKey)} Inspect it in the Cursor Cloud dashboard before retrying.`, "error");
         return;
     }
-    if (!appendCloudLifecycleMutationEntry(params.pi, params.ctx, buildBaseEntry(params.agentId, params.action))) {
-        params.ctx.ui.notify(`Cursor cloud agent ${params.agentId} ${params.action === "archive" ? "archived" : "deleted"}, but its durable result could not be recorded. Inspect it in the Cursor Cloud dashboard before retrying.`, "error");
+    if (!appendCloudLifecycleMutationEntry(isOriginCurrent() ? params.pi : undefined, buildBaseEntry(params.agentId, params.action), params.session, anchorEntryId)) {
+        ui.notify(`Cursor cloud agent ${params.agentId} ${params.action === "archive" ? "archived" : "deleted"}, but its durable result could not be recorded. Inspect it in the Cursor Cloud dashboard before retrying.`, "error");
         return;
     }
-    params.ctx.ui.notify(`Cursor cloud agent ${params.agentId} ${params.action === "archive" ? "archived" : "deleted"}.`, "info");
+    ui.notify(`Cursor cloud agent ${params.agentId} ${params.action === "archive" ? "archived" : "deleted"}.`, "info");
 }
 export async function runCursorCloudLifecycleCommand(pi, args, ctx) {
-    captureCloudLifecycleSession(ctx);
+    const session = captureCloudLifecycleSession(ctx);
     const usage = "Usage: /cursor-cloud list | archive <bc-agentId> | delete <bc-agentId> --yes";
     const tokens = tokenizeArgs(args);
     const [subcommand, agentId, ...rest] = tokens;
@@ -586,9 +615,9 @@ export async function runCursorCloudLifecycleCommand(pi, args, ctx) {
             ctx.ui.notify(`Invalid Cursor cloud arguments. ${usage}`, "error");
             return;
         }
-        if (!reconcileDurableCloudLifecycleOrphansForCommand(pi, ctx))
+        if (!reconcileDurableCloudLifecycleOrphansForCommand(pi, ctx, session))
             return;
-        ctx.ui.notify(formatCloudLifecycleRecords(readRecordedCloudAgents(ctx)), "info");
+        ctx.ui.notify(formatCloudLifecycleRecords(readRecordedCloudAgents(session)), "info");
         return;
     }
     if (subcommand === "archive") {
@@ -601,10 +630,7 @@ export async function runCursorCloudLifecycleCommand(pi, args, ctx) {
             ctx.ui.notify(validationError, "error");
             return;
         }
-        const apiKey = await resolveCloudLifecycleMutationApiKey(ctx);
-        if (!apiKey || !reconcileDurableCloudLifecycleOrphansForCommand(pi, ctx))
-            return;
-        await mutateRecordedCloudAgent({ pi, ctx, agentId, action: "archive", apiKey });
+        await mutateRecordedCloudAgent({ pi, ctx, agentId, action: "archive", session });
         return;
     }
     if (subcommand === "delete") {
@@ -617,16 +643,14 @@ export async function runCursorCloudLifecycleCommand(pi, args, ctx) {
             ctx.ui.notify(validationError, "error");
             return;
         }
-        const apiKey = await resolveCloudLifecycleMutationApiKey(ctx);
-        if (!apiKey || !reconcileDurableCloudLifecycleOrphansForCommand(pi, ctx))
-            return;
-        await mutateRecordedCloudAgent({ pi, ctx, agentId, action: "delete", apiKey });
+        await mutateRecordedCloudAgent({ pi, ctx, agentId, action: "delete", session });
         return;
     }
     ctx.ui.notify(`Invalid Cursor cloud command. ${usage}`, "error");
 }
 export const __testUtils = {
     reset: () => {
+        cloudBindings.clear();
         cloudLifecycleApi = undefined;
         cloudLifecycleSession = {};
         durableWriterForTests = undefined;

package/dist/cursor-durable-fs.js

@@ -1,5 +1,6 @@
-import { closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync } from "node:fs";
-function sameFileIdentity(left, right) {
+import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, openSync, readSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+export function sameFileIdentity(left, right) {
     return left.dev === right.dev && left.ino === right.ino;
 }
 export function noFollowFlag() {
@@ -29,7 +30,100 @@ export function openExistingRegularFileNoFollow(path, flags) {
         throw error;
     }
 }
-/** Opens a read-write descriptor (required for Windows FlushFileBuffers) so fsync applies to the real file, not a swapped-in symlink target. */
+/** Creates a private regular file without replacing or following an existing path. */
+export function createRegularFileExclusive(path, flags, mode) {
+    const fd = openSync(path, flags | constants.O_CREAT | constants.O_EXCL | noFollowFlag(), mode);
+    try {
+        const opened = fstatSync(fd);
+        const after = lstatSync(path);
+        if (!opened.isFile() || !after.isFile() || !sameFileIdentity(opened, after))
+            throw new Error("created file changed while opening");
+        return fd;
+    }
+    catch (error) {
+        closeSync(fd);
+        throw error;
+    }
+}
+/** Bounded, fail-closed framed journals; an incomplete last frame is not recognized. */
+export function readDurableFramePrefix(path, maxBytes = 16 * 1024 * 1024) {
+    let fd;
+    try {
+        fd = openExistingRegularFileNoFollow(path, constants.O_RDONLY);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { frames: [], incompleteTail: false };
+        throw error;
+    }
+    try {
+        if (fstatSync(fd).size > maxBytes)
+            throw new Error("journal exceeds size limit");
+        const buffer = Buffer.alloc(Math.min(fstatSync(fd).size + 1, maxBytes + 1));
+        let length = 0;
+        while (length < buffer.length) {
+            const count = readSync(fd, buffer, length, buffer.length - length, length);
+            if (!count)
+                break;
+            length += count;
+        }
+        if (length === buffer.length)
+            throw new Error("journal changed or exceeds size limit");
+        const text = buffer.subarray(0, length).toString("utf8");
+        const end = text.lastIndexOf("\n");
+        return {
+            frames: end < 0 ? [] : text.slice(0, end).split("\n").map(line => JSON.parse(line)),
+            incompleteTail: !!text && !text.endsWith("\n"),
+        };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function readDurableFrames(path, maxBytes = 16 * 1024 * 1024) {
+    const result = readDurableFramePrefix(path, maxBytes);
+    if (result.incompleteTail)
+        throw new Error("incomplete journal frame");
+    return result.frames;
+}
+export function appendDurableFrame(path, data, validate) {
+    // Validate framing and the owner's complete candidate history once, before recognition.
+    const frames = readDurableFrames(path);
+    validate?.([...frames, data]);
+    let created = false;
+    let fd;
+    try {
+        fd = createRegularFileExclusive(path, constants.O_RDWR | constants.O_APPEND, 0o600);
+        created = true;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        fd = openExistingRegularFileNoFollow(path, constants.O_RDWR | constants.O_APPEND);
+    }
+    try {
+        if (process.platform !== "win32")
+            fchmodSync(fd, 0o600);
+        const frame = `${JSON.stringify(data)}\n`;
+        if (fstatSync(fd).size + Buffer.byteLength(frame) > 16 * 1024 * 1024)
+            throw new Error("journal exceeds size limit");
+        writeFileSync(fd, frame);
+        fsyncSync(fd);
+        if (created && process.platform !== "win32") {
+            const directoryFd = openSync(dirname(path), constants.O_RDONLY);
+            try {
+                fsyncSync(directoryFd);
+            }
+            finally {
+                closeSync(directoryFd);
+            }
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Opens a read-write descriptor (required for Windows FlushFileBuffers) without following a swapped-in symlink. */
 export function fsyncExistingRegularFile(path) {
     let fd;
     try {