fix(ai-sandbox): a quiet reconnect no longer writes a durable run twice

.changeset/quiet-reconnect-claim.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-sandbox': patch
+---
+
+A reconnect during a long tool call no longer writes the rest of a durable sandbox run twice. The host that started the run holds the driver claim until the run ends, so the reconnect tails the log.

docs/config.json

@@ -1509,7 +1509,8 @@
         {
           "label": "Takeover Internals",
           "to": "sandbox/takeover-advanced",
-          "addedAt": "2026-10-21"
+          "addedAt": "2026-10-21",
+          "updatedAt": "2026-11-09"
         },
         {
           "label": "Reaping & Retention",

docs/sandbox/takeover-advanced.md

@@ -106,6 +106,8 @@ Only one host can write a run. The client has no safety net below its offset de-
 2. **An epoch.** Each claim bumps `RunRecord.driverEpoch`. The log re-reads it from time to time and refuses to append once a higher epoch exists. This covers a lock that renews slower than the run appends, or one whose signal never fires.
 3. **Quiet time.** Before its first append, the new host waits for the stored log to stop growing. So it sees an old host that still writes, and does not race it. The wait is `DEFAULT_FENCE_QUIET_MS` (5 seconds). Change it with `fenceQuietMs` on `sandboxRunDriver`. If the log never goes quiet, the drive fails and appends nothing.
 
+The host that starts the run holds this same claim until that run ends. A reconnect while that host still writes only tails the log. The first host stays the only writer. A tool call can add no events for longer than the quiet window. The claim blocks a second writer for that whole call. When the first host is gone, the quiet window applies again.
+
 ### Both channels are fenced
 
 A run's facts live in two places: its event log and its record. If only the log is fenced, a superseded host turns its refused append into a terminal `runs.update`. The record then says `'failed'` for a run the new host streams without problems. Then anything that checks status (`isTerminalRunStatus`, `findActiveRun`, a status poller, the reaper) believes that a live run died.

packages/ai-sandbox/src/claim.ts

@@ -97,6 +97,20 @@ export function runDriverLockKey(runId: string): string {
   return `run-driver:${runId}`
 }
 
+/**
+ * Run ids whose driver claim is held in THIS process.
+ *
+ * `InMemoryLockStore.withLock` waits forever if the holder calls it again, so
+ * a chat that is already inside {@link withRunClaim} must not take the claim
+ * a second time. A different process has its own set and its own lock.
+ */
+const locallyHeldDriverClaims = new Set<string>()
+
+/** True when this process already holds `runId`'s driver claim. */
+export function runDriverClaimHeldLocally(runId: string): boolean {
+  return locallyHeldDriverClaims.has(runId)
+}
+
 /** The claim was never acquired, so the caller must not drive the run. */
 export class RunClaimNotAcquiredError extends Error {
   constructor(
@@ -185,7 +199,45 @@ export async function withRunClaim<T>(
       runId,
       epoch,
     })
-    return fn({ runId, epoch, signal })
+    const claim: RunClaim = { runId, epoch, signal }
+    locallyHeldDriverClaims.add(runId)
+    try {
+      return await fn(claim)
+    } finally {
+      locallyHeldDriverClaims.delete(runId)
+    }
+  })
+}
+
+/**
+ * Hold the driver claim until `release` runs.
+ *
+ * The fresh producer uses this. Its delivery sink keeps appending after a
+ * client disconnect, and that sink does not take the claim. A takeover that
+ * only waits for a quiet log will start a second writer during a tool call
+ * that appends nothing for longer than {@link DEFAULT_FENCE_QUIET_MS}.
+ */
+export function holdRunDriverClaim(
+  options: WithRunClaimOptions,
+): Promise<() => void> {
+  let release = (): void => {}
+  const acquired = new Promise<void>((resolve, reject) => {
+    void withRunClaim(options, () => {
+      return new Promise<void>((done) => {
+        let released = false
+        release = () => {
+          if (released) return
+          released = true
+          done()
+        }
+        resolve()
+      })
+    }).catch((error: unknown) => {
+      reject(error)
+    })
+  })
+  return acquired.then(() => () => {
+    release()
   })
 }