fix(agents): force-release session lock on attempt teardown timeout

ditingdapeng · ditingdapeng · commit e8a7a3f7a5f1 · 2026-07-14T20:56:37.000+08:00
When releaseRetainedSessionLock() hangs beyond 30s (due to stuck tool
execution), force-dispose the lock so the session recovers immediately
instead of waiting up to 17 minutes for watchdog reclaim.
diff --git a/src/agents/embedded-agent-runner/run/attempt.release-lock-timeout.test.ts b/src/agents/embedded-agent-runner/run/attempt.release-lock-timeout.test.ts
@@ -0,0 +1,85 @@
+import { describe, expect, it, vi } from "vitest";
+import { releaseRetainedSessionLockWithTimeout } from "./attempt.release-lock-timeout.js";
+
+describe("releaseRetainedSessionLockWithTimeout", () => {
+  it("returns 'released' when lock releases within timeout", async () => {
+    const release = vi.fn().mockResolvedValue(undefined);
+    const result = await releaseRetainedSessionLockWithTimeout({
+      releaseRetainedSessionLock: release,
+      timeoutMs: 5_000,
+    });
+    expect(result).toBe("released");
+    expect(release).toHaveBeenCalledOnce();
+  });
+
+  it("returns 'timeout' when lock release exceeds timeout", async () => {
+    vi.useFakeTimers();
+    const neverResolve = () => new Promise<void>(() => {});
+    const resultPromise = releaseRetainedSessionLockWithTimeout({
+      releaseRetainedSessionLock: neverResolve,
+      timeoutMs: 30_000,
+    });
+    await vi.advanceTimersByTimeAsync(30_000);
+    const result = await resultPromise;
+    expect(result).toBe("timeout");
+    vi.useRealTimers();
+  });
+
+  it("calls forceDispose on the sessionLockController when timeout fires", async () => {
+    vi.useFakeTimers();
+    const neverResolve = () => new Promise<void>(() => {});
+    const forceDispose = vi.fn().mockResolvedValue(undefined);
+    const resultPromise = releaseRetainedSessionLockWithTimeout({
+      releaseRetainedSessionLock: neverResolve,
+      timeoutMs: 30_000,
+      sessionLockController: { forceDispose },
+    });
+    await vi.advanceTimersByTimeAsync(30_000);
+    const result = await resultPromise;
+    expect(result).toBe("timeout");
+    expect(forceDispose).toHaveBeenCalledOnce();
+    vi.useRealTimers();
+  });
+
+  it("does not call forceDispose when lock releases successfully", async () => {
+    const release = vi.fn().mockResolvedValue(undefined);
+    const forceDispose = vi.fn().mockResolvedValue(undefined);
+    const result = await releaseRetainedSessionLockWithTimeout({
+      releaseRetainedSessionLock: release,
+      timeoutMs: 5_000,
+      sessionLockController: { forceDispose },
+    });
+    expect(result).toBe("released");
+    expect(forceDispose).not.toHaveBeenCalled();
+  });
+
+  it("swallows errors from forceDispose and still returns 'timeout'", async () => {
+    vi.useFakeTimers();
+    const neverResolve = () => new Promise<void>(() => {});
+    const forceDispose = vi.fn().mockRejectedValue(new Error("force dispose failed"));
+    const resultPromise = releaseRetainedSessionLockWithTimeout({
+      releaseRetainedSessionLock: neverResolve,
+      timeoutMs: 30_000,
+      sessionLockController: { forceDispose },
+    });
+    await vi.advanceTimersByTimeAsync(30_000);
+    const result = await resultPromise;
+    expect(result).toBe("timeout");
+    expect(forceDispose).toHaveBeenCalledOnce();
+    vi.useRealTimers();
+  });
+
+  it("works when sessionLockController is undefined on timeout", async () => {
+    vi.useFakeTimers();
+    const neverResolve = () => new Promise<void>(() => {});
+    const resultPromise = releaseRetainedSessionLockWithTimeout({
+      releaseRetainedSessionLock: neverResolve,
+      timeoutMs: 30_000,
+      sessionLockController: undefined,
+    });
+    await vi.advanceTimersByTimeAsync(30_000);
+    const result = await resultPromise;
+    expect(result).toBe("timeout");
+    vi.useRealTimers();
+  });
+});
diff --git a/src/agents/embedded-agent-runner/run/attempt.release-lock-timeout.ts b/src/agents/embedded-agent-runner/run/attempt.release-lock-timeout.ts
@@ -0,0 +1,30 @@
+export async function releaseRetainedSessionLockWithTimeout(params: {
+  releaseRetainedSessionLock: () => Promise<void>;
+  timeoutMs: number;
+  sessionLockController?: { forceDispose?: () => Promise<void> };
+}): Promise<"released" | "timeout"> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const result = await Promise.race([
+      params.releaseRetainedSessionLock().then(() => "released" as const),
+      new Promise<"timeout">((resolve) => {
+        timeout = setTimeout(() => resolve("timeout"), params.timeoutMs);
+        timeout.unref?.();
+      }),
+    ]);
+    if (result === "timeout") {
+      // Force-dispose the lock so the session recovers immediately instead of
+      // waiting for the watchdog (up to 17 minutes).
+      try {
+        await params.sessionLockController?.forceDispose?.();
+      } catch {
+        // best-effort — the watchdog will still eventually reclaim
+      }
+    }
+    return result;
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  }
+}
diff --git a/src/agents/embedded-agent-runner/run/attempt.session-lock.ts b/src/agents/embedded-agent-runner/run/attempt.session-lock.ts
@@ -1219,6 +1219,7 @@ export type EmbeddedAttemptSessionLockController = {
   acquireForCleanup(params?: { session?: unknown }): Promise<SessionLock>;
   hasSessionTakeover(): boolean;
   dispose(): Promise<void>;
+  forceDispose(): Promise<void>;
 };
 
 export async function createEmbeddedAttemptSessionLockController(params: {
@@ -2156,6 +2157,28 @@ export async function createEmbeddedAttemptSessionLockController(params: {
         deactivateFence();
       }
     },
+    async forceDispose(): Promise<void> {
+      disposed = true;
+      // Force-resolve all retained lock idle waiters so any pending
+      // disposeHeldLockAfterRetainedIdle() can proceed immediately.
+      retainedLockUseCount = 0;
+      if (retainedLockIdleWaiters.size > 0) {
+        const waiters = Array.from(retainedLockIdleWaiters);
+        retainedLockIdleWaiters.clear();
+        for (const resolve of waiters) {
+          resolve();
+        }
+      }
+      try {
+        if (heldLock) {
+          const lock = heldLock;
+          heldLock = undefined;
+          await lock.release();
+        }
+      } finally {
+        deactivateFence();
+      }
+    },
   };
 }
 
