fix(agents): fail fast on session lock fallback

sallyom · sallyom · commit e3143af07868 · 2026-05-06T20:05:37.000-04:00
Signed-off-by: sallyom &lt;somalley@redhat.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -131,6 +131,7 @@ Docs: https://docs.openclaw.ai
 - Doctor/OpenAI Codex: revert the 2026.5.5 `doctor --fix` repair that rewrote valid `openai-codex/*` ChatGPT/Codex OAuth routes to `openai/*`, which could break OAuth-only GPT-5.5 setups or accidentally move users onto the OpenAI API-key route. If 2026.5.5 already changed your default model, run `openclaw models set openai-codex/gpt-5.5 && openclaw config validate` to switch the default agent back to the Codex OAuth PI route. Fixes #78407.
 - Discord/groups: instruct group-chat agents to stay silent when a message is addressed to someone else, replying only when invited or correcting key facts. (#78615)
 - Discord/groups: tell Discord-channel agents to wrap bare URLs as `<https://example.com>` so link previews do not expand into uninvited embeds. (#78614)
+- Agents/fallback: fail fast on session write-lock timeouts instead of trying fallback models for local file contention. Fixes #66646. Thanks @sallyom.
 - Telegram/Codex: generate DM topic labels with Codex-compatible simple-completion requests so auto-created private topics can be renamed instead of staying `New Chat`.
 - Plugins/runtime fetch: drop third-party symbol metadata from plain request header dictionaries before passing them into native `fetch` or `Headers`, so SDK and guarded/proxy fetch paths do not reject otherwise valid plugin requests. Fixes #77846. Thanks @shakkernerd.
 - Web fetch: bound guarded dispatcher cleanup after request timeouts so timed-out fetches return tool errors instead of leaving Gateway tool lanes active. (#78439) Thanks @obviyus.
diff --git a/src/agents/failover-error.ts b/src/agents/failover-error.ts
@@ -210,7 +210,7 @@ function normalizeDirectErrorSignal(err: unknown): FailoverSignal {
   };
 }
 
-function hasSessionWriteLockTimeout(err: unknown, seen: Set<object> = new Set()): boolean {
+export function hasSessionWriteLockTimeout(err: unknown, seen: Set<object> = new Set()): boolean {
   if (isSessionWriteLockTimeoutError(err)) {
     return true;
   }
diff --git a/src/agents/model-fallback.test.ts b/src/agents/model-fallback.test.ts
@@ -21,6 +21,7 @@ import {
 } from "./model-fallback.js";
 import { classifyEmbeddedPiRunResultForModelFallback } from "./pi-embedded-runner/result-fallback-classifier.js";
 import type { EmbeddedPiRunResult } from "./pi-embedded-runner/types.js";
+import { SessionWriteLockTimeoutError } from "./session-write-lock-error.js";
 import { makeModelFallbackCfg } from "./test-helpers/model-fallback-config-fixture.js";
 
 vi.mock("../infra/file-lock.js", () => ({
@@ -555,6 +556,35 @@ describe("runWithModelFallback", () => {
     }
   });
 
+  it("fails fast on session write-lock timeouts instead of trying model fallbacks", async () => {
+    const cfg = makeCfg({
+      agents: {
+        defaults: {
+          model: {
+            primary: "openai/gpt-5.4",
+            fallbacks: ["anthropic/claude-opus-4-6"],
+          },
+        },
+      },
+    });
+    const lockError = new SessionWriteLockTimeoutError({
+      timeoutMs: 10_000,
+      owner: "pid=37121",
+      lockPath: "/tmp/openclaw/session.jsonl.lock",
+    });
+    const run = vi.fn().mockRejectedValueOnce(lockError);
+
+    await expect(
+      runWithModelFallback({
+        cfg,
+        provider: "openai",
+        model: "gpt-5.4",
+        run,
+      }),
+    ).rejects.toBe(lockError);
+    expect(run).toHaveBeenCalledTimes(1);
+  });
+
   it("uses optional result classification to continue to configured fallbacks", async () => {
     const cfg = makeCfg({
       agents: {
diff --git a/src/agents/model-fallback.ts b/src/agents/model-fallback.ts
@@ -16,6 +16,7 @@ import {
   FailoverError,
   coerceToFailoverError,
   describeFailoverError,
+  hasSessionWriteLockTimeout,
   isFailoverError,
   isTimeoutError,
 } from "./failover-error.js";
@@ -1048,6 +1049,9 @@ export async function runWithModelFallback<T>(params: {
           sessionId: params.sessionId,
           lane: params.lane,
         }) ?? err;
+      if (hasSessionWriteLockTimeout(normalized)) {
+        throw err;
+      }
 
       // LiveSessionModelSwitchError during fallback may point at a later
       // candidate that is already the active live-session selection.  Jump

Original file line number	Diff line number	Diff line change
`@@ -210,7 +210,7 @@ function normalizeDirectErrorSignal(err: unknown): FailoverSignal {`
`210`	`210`	`};`
`211`	`211`	`}`
`212`	`212`
`213`		`-function hasSessionWriteLockTimeout(err: unknown, seen: Set<object> = new Set()): boolean {`
	`213`	`+export function hasSessionWriteLockTimeout(err: unknown, seen: Set<object> = new Set()): boolean {`
`214`	`214`	`if (isSessionWriteLockTimeoutError(err)) {`
`215`	`215`	`return true;`
`216`	`216`	`}`