@tanstack/ai-sandbox-cloudflare 0.3.12 → 0.4.0

package/src/chat-coordinator.ts

@@ -30,6 +30,7 @@ import {
   withSandbox,
 } from '@tanstack/ai-sandbox'
 import { SandboxCoordinator, resolveBridgeOrigin } from './coordinator'
+import { runWithCallbackActivity } from './coordinator-callbacks'
 import { timingSafeBearerEqualWeb } from './web-crypto'
 import type { StartRunInput } from './coordinator'
 import type {
@@ -233,21 +234,29 @@ export abstract class ChatSandboxCoordinator<
     ) {
       return new Response('unauthorized', { status: 401 })
     }
-    let message: unknown
-    try {
-      message = await request.json()
-    } catch {
-      // A malformed body must still produce a valid JSON-RPC error so the agent's
-      // MCP client can react, rather than an opaque DO 500 that can wedge the run.
-      return this.jsonResponse({
-        jsonrpc: '2.0',
-        id: null,
-        error: { code: -32700, message: 'Parse error' },
-      })
-    }
-    const reply = await handleBridgeJsonRpc(bridge.core, message)
-    // A notification (no id) yields null → MCP expects an empty 202 ack.
-    if (reply === null) return new Response(null, { status: 202 })
-    return this.jsonResponse(reply)
+    return runWithCallbackActivity(
+      this,
+      runId,
+      (id) => this.log.touch(id),
+      async () => {
+        let message: unknown
+        try {
+          message = await request.json()
+        } catch {
+          // A malformed body must still produce a valid JSON-RPC error so the
+          // agent's MCP client can react, rather than an opaque DO 500 that can
+          // wedge the run.
+          return this.jsonResponse({
+            jsonrpc: '2.0',
+            id: null,
+            error: { code: -32700, message: 'Parse error' },
+          })
+        }
+        const reply = await handleBridgeJsonRpc(bridge.core, message)
+        // A notification (no id) yields null → MCP expects an empty 202 ack.
+        if (reply === null) return new Response(null, { status: 202 })
+        return this.jsonResponse(reply)
+      },
+    )
   }
 }

package/src/container-coordinator.ts

@@ -34,6 +34,7 @@ import {
 } from '@tanstack/ai-sandbox'
 import { getSandbox } from '@cloudflare/sandbox'
 import { SandboxCoordinator, resolveBridgeOrigin } from './coordinator'
+import { runWithCallbackActivity } from './coordinator-callbacks'
 import { timingSafeBearerEqualWeb } from './web-crypto'
 import type { StartRunInput } from './coordinator'
 import type { ContainerRunRequest, HarnessId } from './protocol'
@@ -409,29 +410,41 @@ export abstract class ContainerSandboxCoordinator<
     ) {
       return new Response('unauthorized', { status: 401 })
     }
-    let payload: unknown
-    try {
-      payload = await request.json()
-    } catch {
-      return this.jsonResponse({ error: 'body must be valid JSON' }, 400)
-    }
-    if (!isToolExecRequest(payload)) {
-      return this.jsonResponse({ error: 'body must be { name, args }' }, 400)
-    }
-    try {
-      const result = await executeHostTool(
-        state.hostTools,
-        payload.name,
-        payload.args,
-        {
-          ...(state.context !== undefined ? { context: state.context } : {}),
-          signal: state.abort.signal,
-        },
-      )
-      return this.jsonResponse({ result })
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error)
-      return this.jsonResponse({ error: message }, 500)
-    }
+    return runWithCallbackActivity(
+      this,
+      runId,
+      (id) => this.log.touch(id),
+      async () => {
+        let payload: unknown
+        try {
+          payload = await request.json()
+        } catch {
+          return this.jsonResponse({ error: 'body must be valid JSON' }, 400)
+        }
+        if (!isToolExecRequest(payload)) {
+          return this.jsonResponse(
+            { error: 'body must be { name, args }' },
+            400,
+          )
+        }
+        try {
+          const result = await executeHostTool(
+            state.hostTools,
+            payload.name,
+            payload.args,
+            {
+              ...(state.context !== undefined
+                ? { context: state.context }
+                : {}),
+              signal: state.abort.signal,
+            },
+          )
+          return this.jsonResponse({ result })
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error)
+          return this.jsonResponse({ error: message }, 500)
+        }
+      },
+    )
   }
 }

package/src/coordinator-callbacks.ts

@@ -0,0 +1,58 @@
+type TouchRun = (runId: string) => Promise<void>
+
+const inFlightCallbacks = new WeakMap<object, Map<string, number>>()
+
+function increment(owner: object, runId: string): void {
+  let runs = inFlightCallbacks.get(owner)
+  if (!runs) {
+    runs = new Map()
+    inFlightCallbacks.set(owner, runs)
+  }
+  runs.set(runId, (runs.get(runId) ?? 0) + 1)
+}
+
+function decrement(owner: object, runId: string): void {
+  const runs = inFlightCallbacks.get(owner)
+  if (!runs) return
+  const count = runs.get(runId) ?? 0
+  if (count > 1) {
+    runs.set(runId, count - 1)
+    return
+  }
+  runs.delete(runId)
+  if (runs.size === 0) inFlightCallbacks.delete(owner)
+}
+
+export function hasInFlightCallback(owner: object, runId: string): boolean {
+  return (inFlightCallbacks.get(owner)?.get(runId) ?? 0) > 0
+}
+
+export async function runWithCallbackActivity<T>(
+  owner: object,
+  runId: string,
+  touch: TouchRun,
+  operation: () => Promise<T>,
+): Promise<T> {
+  increment(owner, runId)
+  try {
+    // Failure here proves liveness could not be persisted, so do not execute the
+    // callback operation.
+    await touch(runId)
+    try {
+      return await operation()
+    } finally {
+      // This is best-effort bookkeeping after an operation has produced its
+      // result or error. It must never replace that original outcome.
+      try {
+        await touch(runId)
+      } catch (error) {
+        console.error(
+          `[sandbox-coordinator] completion activity touch failed for run ${runId}:`,
+          error,
+        )
+      }
+    }
+  } finally {
+    decrement(owner, runId)
+  }
+}

package/src/coordinator.ts

@@ -31,21 +31,30 @@ import { EventType, isTerminalRunStatus } from '@tanstack/ai'
 // migrated on read; see './run-log').
 import { RunController } from '@tanstack/ai-sandbox'
 import { runLogStore, runLogStream } from './durability'
+import { hasInFlightCallback } from './coordinator-callbacks'
 import { DurableObjectRunEventLog } from './run-log-do'
 import type { ModelMessage, StreamChunk } from '@tanstack/ai'
 import type { RunLogRecord } from './run-log'
 
-/** Re-arm window for the liveness watchdog while a run is in flight (ms). */
+/** Upper bound on the watchdog check interval while a run is in flight (ms). */
 const WATCHDOG_MS = 30_000
 
-/**
- * How long a non-terminal run may go without ANY new event before the watchdog
- * presumes the orchestrator driving it is dead (eviction that lost the
- * `waitUntil` promise, an uncaught fault, a hung container) and fails the run so
- * tailing clients stop waiting forever. Generous so a legitimately slow agent
- * step (a long tool call that emits no chunks) is not killed prematurely.
- */
-const WATCHDOG_STALL_MS = 5 * 60_000
+/** Default permitted period without persisted run activity (ms). */
+const DEFAULT_STALL_TIMEOUT_MS = 5 * 60_000
+
+/** @internal Shared validation for direct subclasses and the eager factory path. */
+export function normalizeStallTimeoutMs(
+  stallTimeoutMs: number | false | undefined,
+): number | false {
+  if (stallTimeoutMs === undefined) return DEFAULT_STALL_TIMEOUT_MS
+  if (stallTimeoutMs === false) return false
+  if (!Number.isSafeInteger(stallTimeoutMs) || stallTimeoutMs <= 0) {
+    throw new TypeError(
+      'stallTimeoutMs must be a positive safe integer or false',
+    )
+  }
+  return stallTimeoutMs
+}
 
 /** What the Worker hands the coordinator to start a run. */
 export interface StartRunInput {
@@ -106,9 +115,15 @@ export abstract class SandboxCoordinator<
    * running — double-delivering events and racing the persisted cursor.
    */
   private readonly pumping = new WeakSet<WebSocket>()
+  private readonly stallTimeoutMs: number | false
 
-  constructor(ctx: DurableObjectState, env: TEnv) {
+  constructor(
+    ctx: DurableObjectState,
+    env: TEnv,
+    stallTimeoutMs?: number | false,
+  ) {
     super(ctx, env)
+    this.stallTimeoutMs = normalizeStallTimeoutMs(stallTimeoutMs)
     this.log = new DurableObjectRunEventLog(ctx.storage)
     this.controller = new RunController({
       runs: runLogStore(this.log),
@@ -154,7 +169,12 @@ export abstract class SandboxCoordinator<
 
   async startRun(input: StartRunInput): Promise<{ runId: string }> {
     const existing = await this.log.get(input.runId)
-    if (existing) return { runId: input.runId } // idempotent re-trigger
+    if (existing) {
+      if (!isTerminalRunStatus(existing.status)) await this.armWatchdog()
+      return { runId: input.runId }
+    }
+
+    await this.armWatchdog()
 
     // Open the run BEFORE building the stream. `pipeToRunLog`'s never-rejects
     // guarantee only covers failures AFTER the stream is handed to it — a throw
@@ -189,7 +209,6 @@ export abstract class SandboxCoordinator<
     // running the settle hook.
     const settle = (): void => this.onRunSettled(input.runId)
     this.ctx.waitUntil(done.then(settle, settle))
-    await this.ctx.storage.setAlarm(Date.now() + WATCHDOG_MS)
     return { runId: input.runId }
   }
 
@@ -320,41 +339,58 @@ export abstract class SandboxCoordinator<
   // ===========================================================================
 
   override async alarm(): Promise<void> {
+    // A previously configured alarm may still be delivered once after watchdogs
+    // are disabled. It must self-extinguish before reading storage or entering a
+    // catch path that could re-arm it. Deliberately do not call deleteAlarm().
+    if (this.stallTimeoutMs === false) return
+
     try {
       // Through the log (not a raw `rec:` list) so legacy records are migrated
       // on the way out — the storage layout is the log's private concern.
       const runs = await this.log.list()
-      const now = Date.now()
+      const cutoff = Date.now() - this.stallTimeoutMs
       let active = false
       for (const record of runs) {
         if (isTerminalRunStatus(record.status)) continue
-        if (now - record.updatedAt > WATCHDOG_STALL_MS) {
-          // No progress for too long — the driver is presumed dead. Fail the run
-          // so tailing clients stop waiting forever (the whole point of the
-          // watchdog; without this a stuck run sits at `running` indefinitely).
-          await this.failStalledRun(record.runId)
-        } else {
+        if (
+          hasInFlightCallback(this, record.runId) ||
+          record.updatedAt >= cutoff
+        ) {
           active = true
+          continue
         }
+
+        // Re-check and terminalize atomically against the same strict cutoff.
+        // A callback touch or normal completion racing this alarm wins cleanly.
+        const finished = await this.failStalledRun(record.runId, cutoff)
+        if (finished) this.onRunSettled(record.runId)
+        else active = true
       }
-      if (active) await this.ctx.storage.setAlarm(Date.now() + WATCHDOG_MS)
+      if (active) await this.armWatchdog()
     } catch (error) {
       // Never let the watchdog die silently: a transient storage error must not
       // permanently disable liveness detection. Re-arm and try again next tick.
       console.error('[sandbox-coordinator] watchdog alarm failed:', error)
-      await this.ctx.storage.setAlarm(Date.now() + WATCHDOG_MS)
+      await this.armWatchdog()
     }
   }
 
-  /** Mark a stalled (orchestrator-presumed-dead) run as a terminal error. */
-  private async failStalledRun(runId: string): Promise<void> {
-    const message = 'run watchdog: no progress; orchestrator presumed dead'
-    try {
-      await this.log.append(runId, { type: EventType.RUN_ERROR, message })
-    } catch {
-      // The run may have just reached terminal concurrently; finish is idempotent.
+  /** Arm without allowing a new run to postpone an earlier pending check. */
+  private async armWatchdog(): Promise<void> {
+    if (this.stallTimeoutMs === false) return
+    const next = Date.now() + Math.min(WATCHDOG_MS, this.stallTimeoutMs)
+    const pending = await this.ctx.storage.getAlarm()
+    if (pending === null || pending > next) {
+      await this.ctx.storage.setAlarm(next)
     }
-    await this.log.finish(runId, 'failed', { message })
-    this.onRunSettled(runId)
+  }
+
+  /** Mark a strictly stale run as a terminal error if it still qualifies. */
+  private failStalledRun(runId: string, cutoff: number): Promise<boolean> {
+    const message = 'run watchdog: no progress; orchestrator presumed dead'
+    return this.log.finishIfStale(runId, cutoff, {
+      type: EventType.RUN_ERROR,
+      message,
+    })
   }
 }

package/src/factory.ts

@@ -45,7 +45,7 @@ import { cloudflareSandbox } from './provider'
 import { ChatSandboxCoordinator } from './chat-coordinator'
 import { ContainerSandboxCoordinator } from './container-coordinator'
 import { createSandboxAgentWorker } from './worker'
-import { resolvePreviewHost } from './coordinator'
+import { normalizeStallTimeoutMs, resolvePreviewHost } from './coordinator'
 import type { ChatCoordinatorEnv, ChatRunConfig } from './chat-coordinator'
 import type {
   ContainerCoordinatorEnv,
@@ -83,6 +83,11 @@ export interface SandboxAgentEnv
 interface BaseAgentConfig<TEnv extends SandboxAgentEnv> {
   /** chat()-provided server tools, resolved per run (DO-drives: bridged over MCP). */
   tools?: (input: StartRunInput, env: TEnv) => Array<AnyTool>
+  /**
+   * Fail a run after this many milliseconds without persisted activity. Omitted
+   * defaults to five minutes; `false` disables the watchdog.
+   */
+  stallTimeoutMs?: number | false
 }
 
 /** DO-drives config: the DO runs `chat()` with the given adapter. */
@@ -188,11 +193,16 @@ function resolveCoordinator<TEnv extends SandboxAgentEnv>(
 export function createCloudflareSandboxAgent<
   TEnv extends SandboxAgentEnv = SandboxAgentEnv,
 >(config: CloudflareSandboxAgentConfig<TEnv>): CloudflareSandboxAgent<TEnv> {
+  const stallTimeoutMs = normalizeStallTimeoutMs(config.stallTimeoutMs)
   const worker = createSandboxAgentWorker<TEnv>(resolveCoordinator)
 
   if (config.mode === 'colocated') {
     const colocated = config
     class ConfiguredContainerCoordinator extends ContainerSandboxCoordinator<TEnv> {
+      constructor(ctx: DurableObjectState, env: TEnv) {
+        super(ctx, env, stallTimeoutMs)
+      }
+
       protected override config(input: StartRunInput): ContainerRunConfig {
         return {
           hostTools: colocated.tools?.(input, this.env) ?? [],
@@ -207,6 +217,10 @@ export function createCloudflareSandboxAgent<
 
   const doDrives = config
   class ConfiguredChatCoordinator extends ChatSandboxCoordinator<TEnv> {
+    constructor(ctx: DurableObjectState, env: TEnv) {
+      super(ctx, env, stallTimeoutMs)
+    }
+
     protected override config(input: StartRunInput): ChatRunConfig {
       const tools = doDrives.tools?.(input, this.env)
       return {

package/src/preview-tool.ts

@@ -68,6 +68,94 @@ export const PREVIEW_GUIDANCE: string = [
   'Once it is listening, call `exposePreview` with that port, then share the URL.',
 ].join('\n')
 
+const LOCAL_PROBE_TIMEOUT_MS = 5_000
+// Fresh quick tunnels need a few seconds of DNS/edge propagation, hence retries.
+const EDGE_PROBE_ATTEMPTS = 5
+const EDGE_PROBE_BASE_DELAY_MS = 250
+const EDGE_PROBE_FETCH_TIMEOUT_MS = 3_000
+
+/**
+ * Probe the port INSIDE the sandbox via `containerFetch`. Returns the HTTP
+ * status when a listener answered (any response — 4xx/5xx included — proves one
+ * exists), or the failure symptom (a string) when nothing did.
+ */
+async function localProbe(
+  sandbox: Sandbox,
+  port: number,
+): Promise<number | string> {
+  // A race instead of AbortSignal: signals don't serialize across the sandbox
+  // RPC boundary, and a lost in-flight probe response is harmless.
+  let timeoutId: ReturnType<typeof setTimeout> | undefined
+  const timeout = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(
+      () => reject(new Error(`no response within ${LOCAL_PROBE_TIMEOUT_MS}ms`)),
+      LOCAL_PROBE_TIMEOUT_MS,
+    )
+  })
+  try {
+    const res = await Promise.race([
+      sandbox.containerFetch('http://preview/', { method: 'HEAD' }, port),
+      timeout,
+    ])
+    return res.status
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error)
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+/**
+ * Probe a tunnel URL through the public edge with bounded retries. Only 502/530
+ * — Cloudflare's tunnel/origin-unreachable signatures — mark the URL as
+ * unreachable (401/403/404 prove the server answered, and `redirect: 'manual'`
+ * keeps a login redirect from probing some other site), and even those are
+ * trusted when the app answered the SAME status locally, so an app's own
+ * 502/530 never gets its healthy tunnel destroyed. The verdict split exists
+ * because only an OBSERVED non-matching 502/530 ('stale') is evidence that
+ * justifies destroying the tunnel; fetch exceptions ('unverified') prove
+ * nothing about it — the probe path itself may be what failed. A throw
+ * anywhere in the retry window therefore wins over an earlier 502/530: the
+ * window did not finish as HTTP probes, so we must not destroy.
+ */
+async function edgeProbeFailure(
+  url: string,
+  localStatus: number,
+): Promise<{ verdict: 'stale' | 'unverified'; symptom: string } | null> {
+  let lastFailure = 'no response'
+  let verdict: 'stale' | 'unverified' = 'unverified'
+  let sawFetchException = false
+  for (let attempt = 0; attempt < EDGE_PROBE_ATTEMPTS; attempt += 1) {
+    if (attempt > 0) {
+      await new Promise((resolve) =>
+        setTimeout(resolve, EDGE_PROBE_BASE_DELAY_MS * 2 ** (attempt - 1)),
+      )
+    }
+    try {
+      const res = await fetch(url, {
+        method: 'HEAD',
+        redirect: 'manual',
+        signal: AbortSignal.timeout(EDGE_PROBE_FETCH_TIMEOUT_MS),
+      })
+      if (
+        (res.status !== 502 && res.status !== 530) ||
+        res.status === localStatus
+      ) {
+        return null
+      }
+      lastFailure = `HTTP ${res.status}`
+      verdict = 'stale'
+    } catch (error) {
+      sawFetchException = true
+      lastFailure = error instanceof Error ? error.message : String(error)
+    }
+  }
+  return {
+    verdict: sawFetchException ? 'unverified' : verdict,
+    symptom: lastFailure,
+  }
+}
+
 /**
  * Build the `exposePreview` server tool for one run. Starting a tunnel is a
  * HOST-side call on the Sandbox DO stub, so an in-sandbox agent cannot make it from
@@ -100,11 +188,55 @@ export function exposePreviewTool(input: StartRunInput, env: PreviewToolEnv) {
     const sandbox = getSandbox(env.Sandbox, input.threadId, {
       transport: 'rpc',
     })
+    // Gate tunnel work on a live listener: a fresh tunnel to a dead port is still
+    // a dead preview, and the failure the agent can FIX is "start the server".
+    const local = await localProbe(sandbox, port)
+    if (typeof local === 'string') {
+      throw new Error(
+        `No server is listening on port ${port} inside the sandbox (${local}). Start the dev server (bound to 0.0.0.0:${port}) first, then retry exposePreview.`,
+      )
+    }
     // A Cloudflare quick tunnel (`*.trycloudflare.com`) run by `cloudflared` INSIDE
     // the sandbox: it bypasses the local Vite dev server's port entirely (so Vite
     // can't hijack the preview's asset requests) and needs no custom domain on a
     // deploy. `get(port)` is idempotent per port. See the Sandbox SDK `tunnels` API.
     const tunnel = await sandbox.tunnels.get(port)
-    return { url: tunnel.url }
+    const edgeFailure = await edgeProbeFailure(tunnel.url, local)
+    if (edgeFailure === null) return { url: tunnel.url }
+    // Never destroy on 'unverified': the tunnel may be healthy with only the
+    // probe path broken, so destroying it could kill a working preview.
+    if (edgeFailure.verdict === 'unverified') {
+      throw new Error(
+        `Port ${port} is serving inside the sandbox, but the preview tunnel could not be verified from the edge (${edgeFailure.symptom}). The tunnel was left in place — retry exposePreview in a few seconds.`,
+      )
+    }
+    // Local server healthy but the edge kept answering 502/530: the cached tunnel
+    // record is suspect. Refresh, bounded to ONE so we never churn tunnels.
+    await sandbox.tunnels.destroy(port)
+    const fresh = await sandbox.tunnels.get(port)
+    const freshFailure = await edgeProbeFailure(fresh.url, local)
+    if (freshFailure === null) {
+      return {
+        url: fresh.url,
+        note: `The tunnel for port ${port} was stale, so it was replaced. Any previously shared preview URL for this port is dead — share this new URL instead.`,
+      }
+    }
+    // Don't leave a known-dead record in DO storage (the #992 failure mode).
+    if (freshFailure.verdict === 'stale') {
+      await sandbox.tunnels.destroy(port)
+    }
+    const [diagnosis, hint] =
+      freshFailure.verdict === 'stale'
+        ? [
+            'its preview tunnel never became reachable',
+            'Retry exposePreview, and if it keeps failing, restart the dev server and try again.',
+          ]
+        : [
+            'the replacement preview tunnel could not be verified from the edge',
+            'Retry exposePreview in a few seconds.',
+          ]
+    throw new Error(
+      `Port ${port} is serving inside the sandbox, but ${diagnosis} (old tunnel: ${edgeFailure.symptom}; replacement tunnel: ${freshFailure.symptom}). ${hint}`,
+    )
   })
 }

package/src/run-log-do.ts

@@ -149,15 +149,79 @@ export class DurableObjectRunEventLog implements RunEventLog {
     this.wake(runId)
   }
 
+  async touch(runId: string): Promise<void> {
+    await this.storage.transaction(async (txn) => {
+      const stored = await txn.get<StoredRunRecord>(recKey(runId))
+      if (!stored) return
+      const { record, migrated } = migrateStoredRunRecord(stored)
+      if (isTerminalRunStatus(record.status)) {
+        if (migrated) await txn.put(recKey(runId), record)
+        return
+      }
+      await txn.put(recKey(runId), { ...record, updatedAt: Date.now() })
+    })
+    // Activity without a new event or status transition gives a tailing reader
+    // nothing to observe, so intentionally do not wake it.
+  }
+
+  async finishIfStale(
+    runId: string,
+    cutoff: number,
+    chunk: Extract<StreamChunk, { type: 'RUN_ERROR' }>,
+  ): Promise<boolean> {
+    const finished = await this.storage.transaction(async (txn) => {
+      const stored = await txn.get<StoredRunRecord>(recKey(runId))
+      if (!stored) return false
+      const { record, migrated } = migrateStoredRunRecord(stored)
+      if (isTerminalRunStatus(record.status) || record.updatedAt >= cutoff) {
+        if (migrated) await txn.put(recKey(runId), record)
+        return false
+      }
+
+      const now = Date.now()
+      const seq = record.lastSeq + 1
+      const next: RunLogRecord = {
+        ...record,
+        status: 'failed',
+        lastSeq: seq,
+        error: {
+          message: chunk.message,
+          ...(chunk.code !== undefined ? { code: chunk.code } : {}),
+        },
+        finishedAt: now,
+        updatedAt: now,
+      }
+      // Read the current activity clock and commit the terminal event + record
+      // in this one transaction. Keep wake-ups outside: transaction callbacks
+      // may be retried and must contain no external work.
+      await txn.put(evtKey(runId, seq), chunk)
+      await txn.put(recKey(runId), next)
+      return true
+    })
+    if (finished) this.wake(runId)
+    return finished
+  }
+
   async update(runId: string, patch: RunRecordPatch): Promise<void> {
-    const record = await this.getRecord(runId)
-    if (!record) return // unknown runId is a no-op
-    const next: RunLogRecord = { ...record, ...patch, updatedAt: Date.now() }
-    await this.storage.put(recKey(runId), next)
+    const updated = await this.storage.transaction(async (txn) => {
+      const stored = await txn.get<StoredRunRecord>(recKey(runId))
+      if (!stored) return false
+      const { record, migrated } = migrateStoredRunRecord(stored)
+      if (isTerminalRunStatus(record.status)) {
+        if (migrated) await txn.put(recKey(runId), record)
+        return false
+      }
+      await txn.put(recKey(runId), {
+        ...record,
+        ...patch,
+        updatedAt: Date.now(),
+      })
+      return true
+    })
     // A patch may terminalize the shared status field (core's driver writes its
-    // terminal status through `RunStore.update`) — parked readers must see it
-    // now, not a TAIL_POLL_MS later.
-    this.wake(runId)
+    // terminal status through `RunStore.update`) — wake only after that update
+    // commits. A late update racing a terminal writer is an atomic no-op.
+    if (updated) this.wake(runId)
   }
 
   async get(runId: string): Promise<RunLogRecord | null> {