@agent-native/core 0.213.1 → 0.216.0

package/dist/agent/run-store.js

@@ -16,6 +16,7 @@ import { AGENT_CHAT_RECOVERY_OF_RUN_FIELD } from "./durable-background.js";
 import { LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, } from "./engine/credential-errors.js";
 import { currentExecutionFence, currentExecutionFenceForScope, ExecutionFenceError, MissingExecutionFenceError, lockAndAssertCurrentExecutionFences, StaleExecutionFenceError, withFencedExecutionWrite, } from "./execution-fence.js";
 import { AGENT_RUN_MIGRATIONS, AGENT_RUN_MIGRATIONS_TABLE, } from "./run-migrations.js";
+import { lockThreadRunSlot } from "./run-slot-lock.js";
 import { isConsistentToolCallInputFingerprint, isUnavailableToolCallInput, toolCallInputFingerprint, } from "./tool-call-journal.js";
 import { CONTINUATION_REASONS, isContinuationTerminalReason } from "./types.js";
 import { readWriteReceipt } from "./write-receipts.js";
@@ -30,6 +31,10 @@ export const STALE_RUN_ERROR_EVENT = {
     details: "The run heartbeat stopped while the run was still marked running. Partial output and tool calls were preserved when available.",
 };
 export const STALE_RUN_TERMINAL_REASON = `error:${STALE_RUN_ERROR_EVENT.errorCode}`;
+const CONTINUATION_TERMINAL_EVENT_REASONS = [
+    "auto_continue",
+    ...CONTINUATION_REASONS,
+];
 export const UNCLAIMED_BACKGROUND_RUN_ERROR_EVENT = {
     type: "error",
     error: "The agent run was handed off to a background worker that never started. It was recovered so you can try again.",
@@ -1329,10 +1334,7 @@ export async function tryClaimRunSlot(threadId, runId, maxStaleMs, options) {
             if (denied)
                 return { refused: denied };
         }
-        await tx.execute({
-            sql: "SELECT pg_advisory_xact_lock(hashtextextended(?, 0::bigint))",
-            args: [`agent-native:run-slot:${threadId}`],
-        });
+        await lockThreadRunSlot(tx, threadId);
         await lockContinuationOrder(tx, threadId, turnId);
         const abortMarker = await tx.execute({
             sql: `SELECT id FROM agent_runs WHERE thread_id = ? AND turn_id = ? AND dispatch_mode = 'turn-abort' AND status = 'aborted' LIMIT 1`,
@@ -1440,6 +1442,15 @@ export async function tryClaimRunSlot(threadId, runId, maxStaleMs, options) {
                 };
             }
         }
+        if (!continueOf && (await options?.hasPendingQueuedSubmission?.(tx))) {
+            return {
+                result: {
+                    claimed: false,
+                    activeRunId: null,
+                    queuedSubmissionPending: true,
+                },
+            };
+        }
         const continuationOrder = normalizeContinuationOrder(options?.continuationOrder) ??
             (await nextContinuationOrder(tx, threadId, turnId));
         const inserted = await tx.execute({
@@ -2069,10 +2080,7 @@ async function reapSingleStaleRun(runId, source, maxStaleMs) {
         return { reaped: false, projectionFailed: false };
     }
     const reapResult = await client.transaction(async (tx) => {
-        await tx.execute({
-            sql: "SELECT pg_advisory_xact_lock(hashtextextended(?, 0::bigint))",
-            args: [`agent-native:run-slot:${runScope.thread_id}`],
-        });
+        await lockThreadRunSlot(tx, runScope.thread_id);
         const lease = await lockTurnExecutionLease(tx, runScope.thread_id, runScope.turn_id);
         const currentRun = await tx.execute({
             sql: `SELECT status, worker_generation FROM agent_runs WHERE id = ? FOR UPDATE`,
@@ -2286,14 +2294,17 @@ export async function updateRunStatus(runId, status) {
 }
 export async function updateRunStatusIfRunning(runId, status, options = {}) {
     await ensureRunTables();
+    const terminalReason = options.terminalReason?.slice(0, 200);
     const { rowsAffected } = await withFencedExecutionWrite((tx) => tx.execute({
         sql: `UPDATE agent_runs SET status = ?, completed_at = ?, dispatch_payload = NULL,
                      thread_projection_pending = CASE WHEN ? THEN TRUE ELSE thread_projection_pending END
+                     ${terminalReason === undefined ? "" : ", terminal_reason = ?"}
               WHERE id = ? AND status = 'running'`,
         args: [
             status,
             Date.now(),
             options.threadProjectionPending === true,
+            ...(terminalReason === undefined ? [] : [terminalReason]),
             runId,
         ],
     }), { runId });
@@ -2341,10 +2352,7 @@ export async function finalizeClaimedBackgroundRunFailure(runId, failure) {
     }
     const expectedGeneration = scope.worker_generation == null ? null : String(scope.worker_generation);
     return client.transaction(async (tx) => {
-        await tx.execute({
-            sql: "SELECT pg_advisory_xact_lock(hashtextextended(?, 0::bigint))",
-            args: [`agent-native:run-slot:${scope.thread_id}`],
-        });
+        await lockThreadRunSlot(tx, scope.thread_id);
         const lease = await lockTurnExecutionLease(tx, scope.thread_id, scope.turn_id);
         const selected = await tx.execute({
             sql: `SELECT status, dispatch_mode, worker_generation
@@ -2511,7 +2519,8 @@ async function updateRunAborted(runId, reason, requireSafeBoundary) {
     if (!client.transaction) {
         throw new Error("Atomic run cancellation requires transaction support");
     }
-    const abortResult = await client.transaction(async (tx) => {
+    const abortEvent = terminalEventForAbortReason(reason);
+    const commitAbort = async (tx) => {
         await lockExecutionLeasesForRuns(tx, [runId]);
         await lockAndAssertCurrentExecutionFences(tx);
         const runResult = await tx.execute({
@@ -2558,6 +2567,7 @@ async function updateRunAborted(runId, reason, requireSafeBoundary) {
         const rowsAffected = result.rowsAffected ?? 0;
         if (rowsAffected > 0) {
             await revokeExecutionLeasesForRuns(tx, [runId]);
+            await appendAbortTerminalRunEventInTransaction(tx, runId, abortEvent);
             return { rowsAffected, appendTerminalEvent: true };
         }
         const terminalState = await tx.execute({
@@ -2565,21 +2575,16 @@ async function updateRunAborted(runId, reason, requireSafeBoundary) {
             args: [runId],
         });
         const terminalRun = terminalState.rows[0];
-        return {
-            rowsAffected,
-            appendTerminalEvent: terminalRun?.status === "aborted" &&
-                terminalRun.terminal_reason === `aborted:${reason ?? "user"}` &&
-                (!requireSafeBoundary || terminalRun.in_flight_since == null),
-        };
-    });
-    if (abortResult.appendTerminalEvent) {
-        try {
-            await safeAppendTerminalRunEvent(runId, terminalEventForAbortReason(reason), "mark-aborted");
-        }
-        catch (error) {
-            throw new AgentRunEventNotPersistedError(runId, null, true, error);
+        const appendTerminalEvent = terminalRun?.status === "aborted" &&
+            terminalRun.terminal_reason === `aborted:${reason ?? "user"}` &&
+            (!requireSafeBoundary || terminalRun.in_flight_since == null);
+        if (appendTerminalEvent) {
+            await appendAbortTerminalRunEventInTransaction(tx, runId, abortEvent);
+            return { rowsAffected: 0, appendTerminalEvent: true };
         }
-    }
+        return { rowsAffected: 0, appendTerminalEvent: false };
+    };
+    const abortResult = await retryAbortTerminalEventTransaction("mark-aborted", () => client.transaction(commitAbort));
     return abortResult.rowsAffected > 0 || abortResult.appendTerminalEvent;
 }
 async function lockExecutionLeasesForRuns(db, runIds) {
@@ -2654,12 +2659,9 @@ export async function markTurnAborted(threadId, turnId, reason = "user") {
     if (!client.transaction) {
         throw new Error("Atomic turn cancellation requires transaction support");
     }
-    const runIds = [];
-    const outcome = await client.transaction(async (tx) => {
-        await tx.execute({
-            sql: "SELECT pg_advisory_xact_lock(hashtextextended(?, 0::bigint))",
-            args: [`agent-native:run-slot:${threadId}`],
-        });
+    const commitAbort = async (tx) => {
+        const runIds = [];
+        await lockThreadRunSlot(tx, threadId);
         await lockAndAssertCurrentExecutionFences(tx);
         const lease = await lockTurnExecutionLease(tx, threadId, turnId);
         if (fence &&
@@ -2727,6 +2729,40 @@ export async function markTurnAborted(threadId, turnId, reason = "user") {
                 return "already_terminal";
             }
         }
+        const continuationRun = await tx.execute({
+            sql: `SELECT id FROM agent_runs
+            WHERE thread_id = ? AND COALESCE(turn_id, id) = ?
+              AND status = 'truncated'
+              AND terminal_reason IN (${CONTINUATION_TERMINAL_EVENT_REASONS.map(() => "?").join(", ")})
+              AND dispatch_mode IS DISTINCT FROM 'turn-abort'
+            ORDER BY started_at DESC LIMIT 1 FOR UPDATE`,
+            args: [threadId, turnId, ...CONTINUATION_TERMINAL_EVENT_REASONS],
+        });
+        const continuationRunId = String(continuationRun.rows[0]?.id ?? "");
+        if (continuationRunId) {
+            const abortedContinuation = await tx.execute({
+                sql: `UPDATE agent_runs
+              SET status = 'aborted', abort_reason = ?, completed_at = ?, terminal_reason = ?
+              WHERE id = ? AND status = 'truncated'
+                AND terminal_reason IN (${CONTINUATION_TERMINAL_EVENT_REASONS.map(() => "?").join(", ")})
+              RETURNING id`,
+                args: [
+                    reason,
+                    now,
+                    `aborted:${reason}`,
+                    continuationRunId,
+                    ...CONTINUATION_TERMINAL_EVENT_REASONS,
+                ],
+            });
+            if (abortedContinuation.rows.length > 0) {
+                runIds.push(continuationRunId);
+                await revokeExecutionLeasesForRuns(tx, [continuationRunId]);
+            }
+        }
+        const abortEvent = terminalEventForAbortReason(reason);
+        for (const runId of runIds) {
+            await appendAbortTerminalRunEventInTransaction(tx, runId, abortEvent);
+        }
         await tx.execute({
             sql: `INSERT INTO agent_runs (id, thread_id, status, abort_reason, started_at, completed_at, heartbeat_at, last_progress_at, turn_id, terminal_reason, dispatch_mode) VALUES (?, ?, 'aborted', ?, ?, ?, ?, ?, ?, ?, 'turn-abort'), (?, ?, 'aborted', ?, ?, ?, ?, ?, ?, ?, 'turn-abort') ON CONFLICT (id) DO NOTHING`,
             args: [
@@ -2751,8 +2787,8 @@ export async function markTurnAborted(threadId, turnId, reason = "user") {
             ],
         });
         return "aborted";
-    });
-    await Promise.all(runIds.map((runId) => safeAppendTerminalRunEvent(runId, terminalEventForAbortReason(reason), "mark-turn-aborted")));
+    };
+    const outcome = await retryAbortTerminalEventTransaction("mark-turn-aborted", () => client.transaction(commitAbort));
     return outcome;
 }
 export async function getRunTurnRef(runId) {
@@ -2799,12 +2835,12 @@ export async function getRunAbortState(runId) {
         ...(row.abort_reason ? { reason: row.abort_reason } : {}),
     };
 }
-function persistedRunEventData(eventData, inputSource) {
+function persistedRunEventData(eventData, inputSource, parsedEvent) {
     const stripped = stripInlineBytesFromJson(eventData, "placeholder");
-    const original = JSON.parse(eventData);
+    const original = parsedEvent ?? JSON.parse(eventData);
     if (original.type === "approval_required") {
         return JSON.stringify({
-            ...JSON.parse(stripped),
+            ...(stripped === eventData ? original : JSON.parse(stripped)),
             approvalKey: approvalKeyForHistory(original.approvalKey),
         });
     }
@@ -2816,7 +2852,7 @@ function persistedRunEventData(eventData, inputSource) {
         original.inputFingerprint !== undefined ||
         original.inputStoredFingerprint !== undefined)
         return stripped;
-    const stored = JSON.parse(stripped);
+    const stored = stripped === eventData ? original : JSON.parse(stripped);
     // Only fresh execution input can establish identity; reserialization cannot recover lost arguments.
     return JSON.stringify({
         ...stored,
@@ -2843,19 +2879,57 @@ export class AgentRunEventNotPersistedError extends Error {
 }
 export async function insertRunEvent(runId, seq, eventData, options) {
     await ensureRunTables();
-    const storedEventData = persistedRunEventData(eventData, options?.toolInputSource);
+    const event = parseRunEventData(eventData, `run ${runId} sequence ${seq}`);
+    const continuationReason = options?.allowContinuationTerminal &&
+        event.type === "auto_continue" &&
+        isContinuationTerminalReason(event.reason)
+        ? event.reason
+        : null;
+    const storedEventData = persistedRunEventData(eventData, options?.toolInputSource, event);
     const eventAt = options?.eventAt ?? Date.now();
+    const resolvesCheckpoint = terminalStatusForEvent(event) !== null;
     // The reaper must wait for the marker's commit before exposing a successor.
     let result;
     try {
         result = await withFencedExecutionWrite(async (tx) => {
-            const { rowsAffected } = await tx.execute({
-                sql: options?.requireInserted
-                    ? `WITH running_run AS MATERIALIZED (
-          SELECT id FROM agent_runs WHERE id = ? AND status = 'running' FOR UPDATE
+            const writeEvent = async (writeTx) => {
+                if (options?.allowContinuationTerminal) {
+                    const runRef = await writeTx.execute({
+                        sql: "SELECT thread_id FROM agent_runs WHERE id = ?",
+                        args: [runId],
+                    });
+                    const threadId = String(runRef.rows[0]
+                        ?.thread_id ?? "");
+                    if (threadId) {
+                        // Serialize eligibility with turn abort's marker transaction.
+                        await writeTx.execute({
+                            sql: "SELECT pg_advisory_xact_lock(hashtextextended(?, 0::bigint))",
+                            args: [`agent-native:run-slot:${threadId}`],
+                        });
+                    }
+                }
+                const runAdmissionPredicate = continuationReason
+                    ? `AND NOT EXISTS (
+                SELECT 1 FROM agent_runs AS aborted_turn
+                WHERE aborted_turn.thread_id = run.thread_id
+                  AND COALESCE(aborted_turn.turn_id, aborted_turn.id) = COALESCE(run.turn_id, run.id)
+                  AND aborted_turn.dispatch_mode = 'turn-abort'
+                  AND aborted_turn.status = 'aborted'
+              )
+              AND run.status = 'truncated'
+              AND run.terminal_reason = ?`
+                    : "AND run.status = 'running'";
+                const runAdmissionArgs = continuationReason
+                    ? [continuationReason]
+                    : [];
+                const insertSql = options?.requireInserted
+                    ? `WITH eligible_run AS MATERIALIZED (
+          SELECT run.id FROM agent_runs AS run
+          WHERE run.id = ? ${runAdmissionPredicate}
+          FOR UPDATE
         )
         INSERT INTO agent_run_events (run_id, seq, event_at, event_data)
-        SELECT id, ?, ?, ? FROM running_run LIMIT 1
+        SELECT id, ?, ?, ? FROM eligible_run LIMIT 1
         ON CONFLICT (run_id, seq) DO NOTHING`
                     : `INSERT INTO agent_run_events (run_id, seq, event_at, event_data)
       SELECT ?, ?, ?, ?
@@ -2863,40 +2937,83 @@ export async function insertRunEvent(runId, seq, eventData, options) {
         SELECT 1 FROM agent_runs
         WHERE id = ? AND status <> 'running'
       )
-      ON CONFLICT (run_id, seq) DO NOTHING`,
-                args: [
-                    runId,
-                    seq,
-                    eventAt,
-                    storedEventData,
-                    ...(options?.requireInserted ? [] : [runId]),
-                ],
-            });
-            if (!options?.requireInserted || rowsAffected === 1)
+      ON CONFLICT (run_id, seq) DO NOTHING`;
+                const insertArgs = options?.requireInserted
+                    ? [runId, ...runAdmissionArgs, seq, eventAt, storedEventData]
+                    : [runId, seq, eventAt, storedEventData, runId];
+                const { rowsAffected } = await writeTx.execute({
+                    sql: insertSql,
+                    args: insertArgs,
+                });
+                if (resolvesCheckpoint) {
+                    let terminalPersisted = rowsAffected === 1;
+                    if (!terminalPersisted) {
+                        const existing = await writeTx.execute({
+                            sql: "SELECT event_data FROM agent_run_events WHERE run_id = ? AND seq = ?",
+                            args: [runId, seq],
+                        });
+                        terminalPersisted =
+                            String(existing.rows[0]
+                                ?.event_data) === storedEventData;
+                    }
+                    if (terminalPersisted) {
+                        // The reserved checkpoint sequence sorts after ordinary events,
+                        // so an authoritative terminal event must retire it atomically.
+                        await writeTx.execute({
+                            sql: "DELETE FROM agent_run_events WHERE run_id = ? AND seq = ?",
+                            args: [runId, CHECKPOINT_TERMINAL_EVENT_SEQ],
+                        });
+                    }
+                }
+                if (!options?.requireInserted || rowsAffected === 1)
+                    return {
+                        rowsAffected,
+                        terminalRun: false,
+                        persistedIdentically: rowsAffected === 1,
+                    };
+                const existing = await writeTx.execute({
+                    sql: `SELECT event_at, event_data FROM agent_run_events
+              WHERE run_id = ? AND seq = ?`,
+                    args: [runId, seq],
+                });
+                const existingRow = existing.rows[0];
+                const persistedIdentically = existingRow !== undefined &&
+                    Number(existingRow.event_at) === eventAt &&
+                    String(existingRow.event_data) === storedEventData;
+                const run = await writeTx.execute({
+                    sql: `SELECT run.status, run.terminal_reason,
+                       EXISTS (
+                         SELECT 1 FROM agent_runs AS aborted_turn
+                         WHERE aborted_turn.thread_id = run.thread_id
+                           AND COALESCE(aborted_turn.turn_id, aborted_turn.id) = COALESCE(run.turn_id, run.id)
+                           AND aborted_turn.dispatch_mode = 'turn-abort'
+                           AND aborted_turn.status = 'aborted'
+                       ) AS turn_aborted
+                  FROM agent_runs AS run WHERE run.id = ?`,
+                    args: [runId],
+                });
+                const runRow = run.rows[0];
+                const status = runRow?.status;
+                const continuationTerminalEligible = continuationReason !== null &&
+                    status === "truncated" &&
+                    runRow?.terminal_reason === continuationReason &&
+                    runRow?.turn_aborted !== true &&
+                    runRow?.turn_aborted !== "true";
                 return {
                     rowsAffected,
-                    terminalRun: false,
-                    persistedIdentically: rowsAffected === 1,
+                    terminalRun: status !== undefined &&
+                        status !== "running" &&
+                        !continuationTerminalEligible,
+                    persistedIdentically,
                 };
-            const existing = await tx.execute({
-                sql: `SELECT event_at, event_data FROM agent_run_events
-              WHERE run_id = ? AND seq = ?`,
-                args: [runId, seq],
-            });
-            const existingRow = existing.rows[0];
-            const persistedIdentically = existingRow !== undefined &&
-                Number(existingRow.event_at) === eventAt &&
-                String(existingRow.event_data) === storedEventData;
-            const run = await tx.execute({
-                sql: "SELECT status FROM agent_runs WHERE id = ?",
-                args: [runId],
-            });
-            const status = run.rows[0]?.status;
-            return {
-                rowsAffected,
-                terminalRun: status !== "running",
-                persistedIdentically,
             };
+            if (!resolvesCheckpoint || currentExecutionFence()) {
+                return writeEvent(tx);
+            }
+            if (!tx.transaction) {
+                throw new Error("Checkpoint resolution requires run event transaction support");
+            }
+            return tx.transaction(writeEvent);
         }, { runId });
     }
     catch (error) {
@@ -2987,8 +3104,62 @@ export async function insertRunEvents(runId, events) {
 }
 export const CHECKPOINT_TERMINAL_EVENT_SEQ = 1_000_000_000;
 export async function persistRunCheckpointEvent(runId, event, terminalReason) {
-    await insertRunEvent(runId, CHECKPOINT_TERMINAL_EVENT_SEQ, JSON.stringify(event));
-    await setRunTerminalReason(runId, terminalReason);
+    await ensureRunTables();
+    const storedEventData = persistedRunEventData(JSON.stringify(event));
+    const reason = terminalReason.slice(0, 200);
+    const writeCheckpoint = async (tx) => {
+        const { rows } = await tx.execute({
+            sql: "SELECT status, terminal_reason FROM agent_runs WHERE id = ? FOR UPDATE",
+            args: [runId],
+        });
+        const run = rows[0];
+        if (!run || run.status !== "running") {
+            throw new AgentRunEventNotPersistedError(runId, CHECKPOINT_TERMINAL_EVENT_SEQ, Boolean(run));
+        }
+        const existing = await tx.execute({
+            sql: "SELECT event_data FROM agent_run_events WHERE run_id = ? AND seq = ?",
+            args: [runId, CHECKPOINT_TERMINAL_EVENT_SEQ],
+        });
+        const existingEvent = existing.rows[0];
+        if (existingEvent) {
+            if (existingEvent.event_data !== storedEventData) {
+                throw new AgentRunEventNotPersistedError(runId, CHECKPOINT_TERMINAL_EVENT_SEQ, true);
+            }
+        }
+        else {
+            const inserted = await tx.execute({
+                sql: `INSERT INTO agent_run_events (run_id, seq, event_at, event_data)
+              VALUES (?, ?, ?, ?)
+              ON CONFLICT (run_id, seq) DO NOTHING`,
+                args: [
+                    runId,
+                    CHECKPOINT_TERMINAL_EVENT_SEQ,
+                    Date.now(),
+                    storedEventData,
+                ],
+            });
+            if (inserted.rowsAffected !== 1) {
+                throw new AgentRunEventNotPersistedError(runId, CHECKPOINT_TERMINAL_EVENT_SEQ);
+            }
+        }
+        const updated = await tx.execute({
+            sql: `UPDATE agent_runs SET terminal_reason = ?
+            WHERE id = ? AND status = 'running'
+              AND (terminal_reason IS NULL OR terminal_reason = '' OR terminal_reason = ?)`,
+            args: [reason, runId, reason],
+        });
+        if (updated.rowsAffected !== 1) {
+            throw new AgentRunEventNotPersistedError(runId, CHECKPOINT_TERMINAL_EVENT_SEQ, true);
+        }
+    };
+    await withFencedExecutionWrite((tx) => {
+        if (currentExecutionFence())
+            return writeCheckpoint(tx);
+        if (!tx.transaction) {
+            throw new Error("Run checkpoint writes require transaction support");
+        }
+        return tx.transaction(writeCheckpoint);
+    }, { runId });
 }
 export async function getRunEventsSince(runId, fromSeq, opts) {
     await ensureRunTables();
@@ -3082,8 +3253,10 @@ export async function getLastTerminalRunEvent(runId) {
     await ensureRunTables();
     const client = getDbExec();
     const { rows } = await client.execute({
-        sql: `SELECT seq, event_data FROM agent_run_events WHERE run_id = ? ORDER BY seq DESC LIMIT 1`,
-        args: [runId],
+        sql: `SELECT seq, event_data FROM agent_run_events
+          WHERE run_id = ? AND seq < ?
+          ORDER BY seq DESC LIMIT 1`,
+        args: [runId, CHECKPOINT_TERMINAL_EVENT_SEQ],
     });
     const last = rows[0];
     if (!last?.event_data)
@@ -3760,16 +3933,76 @@ async function finalizeStaleRun(runId, source, projectThread = true) {
         return false;
     }
 }
-async function appendTerminalRunEventInTransaction(tx, runId, event) {
+class AbortTerminalEventWriteError extends Error {
+    runId;
+    constructor(runId, cause) {
+        const detail = cause instanceof Error ? `: ${cause.message}` : "";
+        super(`Abort terminal event was not persisted for run ${runId}${detail}`);
+        this.name = "AbortTerminalEventWriteError";
+        this.runId = runId;
+        if (cause !== undefined) {
+            Object.defineProperty(this, "cause", {
+                value: cause,
+                configurable: true,
+            });
+        }
+    }
+}
+async function retryAbortTerminalEventTransaction(source, transaction) {
+    let firstError;
+    try {
+        return await transaction();
+    }
+    catch (error) {
+        if (!(error instanceof AbortTerminalEventWriteError))
+            throw error;
+        firstError = error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    try {
+        return await transaction();
+    }
+    catch (error) {
+        if (!(error instanceof AbortTerminalEventWriteError))
+            throw error;
+        const cause = error.cause ?? error;
+        captureError(cause, {
+            tags: {
+                component: "agent-run-store",
+                operation: "append-terminal-event",
+                source,
+            },
+            extra: {
+                runId: error.runId,
+                eventType: "abort",
+                firstError: firstError.cause instanceof Error
+                    ? firstError.cause.message
+                    : String(firstError.cause ?? firstError),
+            },
+        });
+        throw new AgentRunEventNotPersistedError(error.runId, null, false, cause);
+    }
+}
+async function appendAbortTerminalRunEventInTransaction(tx, runId, event) {
+    try {
+        await appendTerminalRunEventInTransaction(tx, runId, event, true);
+    }
+    catch (error) {
+        throw new AbortTerminalEventWriteError(runId, error);
+    }
+}
+async function appendTerminalRunEventInTransaction(tx, runId, event, replaceExistingTerminal = false) {
+    const eventData = stripInlineBytesFromJson(JSON.stringify(event), "placeholder");
     const { rows } = await tx.execute({
         sql: `SELECT seq, event_data
           FROM agent_run_events
           WHERE run_id = ?
           ORDER BY seq DESC
-          LIMIT 1`,
+          LIMIT 1 FOR UPDATE`,
         args: [runId],
     });
     const last = rows[0];
+    let nextSeq = last ? Number(last.seq ?? -1) + 1 : 0;
     if (last?.event_data) {
         let parsed;
         try {
@@ -3780,31 +4013,70 @@ async function appendTerminalRunEventInTransaction(tx, runId, event) {
                 cause: error,
             });
         }
-        if (parsed &&
-            typeof parsed === "object" &&
-            terminalStatusForEvent(parsed)) {
-            return;
+        if (parsed) {
+            const lastEventIsTerminal = Boolean(terminalStatusForEvent(parsed));
+            if (lastEventIsTerminal && last.event_data === eventData)
+                return;
+            if (lastEventIsTerminal && !replaceExistingTerminal)
+                return;
+            if (lastEventIsTerminal && replaceExistingTerminal) {
+                await tx.execute({
+                    sql: "DELETE FROM agent_run_events WHERE run_id = ? AND seq = ?",
+                    args: [runId, Number(last.seq)],
+                });
+                if (Number(last.seq) === CHECKPOINT_TERMINAL_EVENT_SEQ) {
+                    const regularEvents = await tx.execute({
+                        sql: `SELECT COALESCE(MAX(seq), -1) AS seq FROM agent_run_events
+                  WHERE run_id = ? AND seq < ?`,
+                        args: [runId, CHECKPOINT_TERMINAL_EVENT_SEQ],
+                    });
+                    nextSeq =
+                        Number(regularEvents.rows[0]
+                            ?.seq ?? -1) + 1;
+                }
+                else {
+                    nextSeq = Number(last.seq);
+                }
+            }
         }
     }
-    const nextSeq = last ? Number(last.seq ?? -1) + 1 : 0;
     if (!Number.isSafeInteger(nextSeq)) {
         throw new Error(`Run ${runId} has no safe sequence for its terminal event`);
     }
-    const inserted = await tx.execute({
-        sql: `INSERT INTO agent_run_events (run_id, seq, event_at, event_data)
-          VALUES (?, ?, ?, ?)
-          ON CONFLICT (run_id, seq) DO NOTHING
-          RETURNING seq`,
-        args: [
-            runId,
-            nextSeq,
-            Date.now(),
-            stripInlineBytesFromJson(JSON.stringify(event), "placeholder"),
-        ],
-    });
-    if ((inserted.rowsAffected ?? inserted.rows.length) !== 1) {
-        throw new Error(`Run ${runId} terminal event sequence ${nextSeq} was not persisted`);
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const inserted = await tx.execute({
+            sql: `INSERT INTO agent_run_events (run_id, seq, event_at, event_data)
+            VALUES (?, ?, ?, ?)
+            ON CONFLICT (run_id, seq) DO NOTHING
+            RETURNING seq`,
+            args: [runId, nextSeq, Date.now(), eventData],
+        });
+        if ((inserted.rowsAffected ?? inserted.rows.length) === 1)
+            return;
+        const conflict = await tx.execute({
+            sql: "SELECT event_data FROM agent_run_events WHERE run_id = ? AND seq = ?",
+            args: [runId, nextSeq],
+        });
+        const conflictingEventData = conflict.rows[0]?.event_data;
+        if (typeof conflictingEventData !== "string") {
+            throw new Error(`Run ${runId} terminal event sequence ${nextSeq} was not persisted`);
+        }
+        const conflictingEvent = parseRunEventData(conflictingEventData, `conflicting event at sequence ${nextSeq} for run ${runId}`);
+        if (terminalStatusForEvent(conflictingEvent))
+            return;
+        const regularEvents = await tx.execute({
+            sql: `SELECT COALESCE(MAX(seq), -1) AS seq FROM agent_run_events
+            WHERE run_id = ? AND seq < ?`,
+            args: [runId, CHECKPOINT_TERMINAL_EVENT_SEQ],
+        });
+        nextSeq =
+            Number(regularEvents.rows[0]?.seq ??
+                -1) + 1;
+        if (!Number.isSafeInteger(nextSeq)) {
+            throw new Error(`Run ${runId} has no safe sequence for its terminal event`);
+        }
     }
+    throw new Error(`Run ${runId} terminal event conflicted repeatedly at sequence ${nextSeq}`);
 }
 async function retryPendingStaleRunThreadProjections(client) {
     const { rows } = await client.execute({
@@ -3826,69 +4098,64 @@ async function retryPendingStaleRunThreadProjections(client) {
     }
     return { failed, truncated };
 }
-async function safeAppendTerminalRunEvent(runId, event, source) {
-    let firstError;
-    try {
-        await appendTerminalRunEvent(runId, event);
-        return;
-    }
-    catch (err) {
-        firstError = err;
-    }
-    await new Promise((resolve) => setTimeout(resolve, 100));
-    try {
-        await appendTerminalRunEvent(runId, event);
-    }
-    catch (retryErr) {
-        captureError(retryErr, {
-            tags: {
-                component: "agent-run-store",
-                operation: "append-terminal-event",
-                source,
-            },
-            extra: {
-                runId,
-                eventType: typeof event.type === "string" ? event.type : "(unknown)",
-                firstError: firstError instanceof Error ? firstError.message : String(firstError),
-            },
-        });
-        throw retryErr;
-    }
-}
 async function appendTerminalRunEvent(runId, event) {
     await ensureRunTables();
     const client = getDbExec();
-    const { rows } = await client.execute({
-        sql: `SELECT seq, event_data FROM agent_run_events WHERE run_id = ? ORDER BY seq DESC LIMIT 1`,
-        args: [runId],
-    });
-    const last = rows[0];
-    if (last?.event_data) {
-        try {
-            const parsed = JSON.parse(last.event_data);
-            if (parsed?.type === "done" ||
-                parsed?.type === "error" ||
-                parsed?.type === "missing_api_key" ||
-                parsed?.type === "loop_limit" ||
-                parsed?.type === "auto_continue") {
+    if (!client.transaction) {
+        throw new Error("Terminal run event writes require transaction support");
+    }
+    const storedEventData = stripInlineBytesFromJson(JSON.stringify(event), "placeholder");
+    await client.transaction(async (tx) => {
+        const { rows } = await tx.execute({
+            sql: `SELECT seq, event_data FROM agent_run_events
+            WHERE run_id = ? ORDER BY seq DESC LIMIT 1 FOR UPDATE`,
+            args: [runId],
+        });
+        const last = rows[0];
+        let nextSeq = last ? Number(last.seq ?? -1) + 1 : 0;
+        if (last?.event_data) {
+            const parsed = parseRunEventData(last.event_data, `last persisted event for run ${runId}`);
+            const lastEventIsTerminal = parsed.type === "done" ||
+                parsed.type === "error" ||
+                parsed.type === "missing_api_key" ||
+                parsed.type === "loop_limit" ||
+                parsed.type === "auto_continue";
+            const replacesCheckpoint = Number(last.seq) === CHECKPOINT_TERMINAL_EVENT_SEQ &&
+                parsed.type === "auto_continue" &&
+                (event.type !== "auto_continue" || parsed.reason !== event.reason);
+            if (lastEventIsTerminal && !replacesCheckpoint)
                 return;
+            if (replacesCheckpoint) {
+                await tx.execute({
+                    sql: "DELETE FROM agent_run_events WHERE run_id = ? AND seq = ?",
+                    args: [runId, CHECKPOINT_TERMINAL_EVENT_SEQ],
+                });
+                const regularEvents = await tx.execute({
+                    sql: `SELECT COALESCE(MAX(seq), -1) AS seq FROM agent_run_events
+                WHERE run_id = ? AND seq < ?`,
+                    args: [runId, CHECKPOINT_TERMINAL_EVENT_SEQ],
+                });
+                nextSeq =
+                    Number(regularEvents.rows[0]
+                        ?.seq ?? -1) + 1;
             }
         }
-        catch {
-            // Ignore malformed rows and append the terminal event.
+        const inserted = await tx.execute({
+            sql: `INSERT INTO agent_run_events (run_id, seq, event_at, event_data) VALUES (?, ?, ?, ?) ON CONFLICT (run_id, seq) DO NOTHING RETURNING seq`,
+            args: [runId, nextSeq, Date.now(), storedEventData],
+        });
+        if (inserted.rows.length === 0) {
+            throw new Error(`Run ${runId} terminal event conflicted with sequence ${nextSeq}`);
         }
-    }
-    const nextSeq = last ? Number(last.seq ?? -1) + 1 : 0;
-    const inserted = await client.execute({
-        sql: `INSERT INTO agent_run_events (run_id, seq, event_at, event_data) VALUES (?, ?, ?, ?) ON CONFLICT (run_id, seq) DO NOTHING RETURNING seq`,
-        args: [
-            runId,
-            nextSeq,
-            Date.now(),
-            stripInlineBytesFromJson(JSON.stringify(event), "placeholder"),
-        ],
     });
-    if (inserted.rows.length === 0) {
-        throw new Error(`Run ${runId} terminal event conflicted with sequence ${nextSeq}`);
+}
+function parseRunEventData(eventData, context) {
+    const parsed = JSON.parse(eventData);
+    if (parsed === null ||
+        typeof parsed !== "object" ||
+        Array.isArray(parsed) ||
+        typeof parsed.type !== "string") {
+        throw new Error(`Run event data is malformed for ${context}`);
     }
+    return parsed;
 }