fix: thread session write-lock timeout config

Author: steipete

CHANGELOG.md

@@ -43,6 +43,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Sessions/transcripts: use one `session.writeLock.acquireTimeoutMs` policy for session transcript lock acquisitions and raise the default wait to 60 seconds, avoiding user-visible lock timeouts during legitimate slow prep, cleanup, compaction, and mirror work. Fixes #75894. Thanks @shandutta.
 - Control UI: contain the standalone iOS PWA viewport with safe-area-aware document locking, so Add-to-Home-Screen launches cannot scroll past the device bounds. Refs #76072. Thanks @kvncrw.
 - Agents/restart recovery: match cleaned transcript locks by exact transcript lock paths plus the canonical session fallback, so interrupted main sessions using topic-suffixed transcripts resume after gateway restart. Refs #76052. Thanks @anyech.
 - Agents/runtime: cache the stable system-prompt prefix and reuse prompt-report tool schema stats during dispatch prep, reducing repeated CPU work before streaming starts. Fixes #75999; supersedes #76061. Thanks @zackchiutw and @STLI69.

docs/concepts/agent-loop.md

@@ -50,7 +50,8 @@ wired end-to-end.
   See [Command Queue](/concepts/queue).
 - Transcript writes are also protected by a session write lock on the session file. The lock is
   process-aware and file-based, so it catches writers that bypass the in-process queue or come from
-  another process.
+  another process. Session transcript writers wait up to `session.writeLock.acquireTimeoutMs`
+  before reporting the session as busy; the default is `60000` ms.
 - Session write locks are non-reentrant by default. If a helper intentionally nests acquisition of
   the same lock while preserving one logical writer, it must opt in explicitly with
   `allowReentrant: true`.

docs/reference/session-management-compaction.md

@@ -94,6 +94,11 @@ configured age, count, or disk budget.
 
 OpenClaw no longer creates automatic `sessions.json.bak.*` rotation backups during Gateway writes. The legacy `session.maintenance.rotateBytes` key is ignored and `openclaw doctor --fix` removes it from older configs.
 
+Transcript mutations use a session write lock on the transcript file. Lock acquisition waits up to
+`session.writeLock.acquireTimeoutMs` before surfacing a busy-session error; the default is `60000`
+ms. Raise this only when legitimate prep, cleanup, compaction, or transcript mirror work contends
+longer on slow machines. Stale-lock detection and maximum hold warnings remain separate policies.
+
 Enforcement order for disk budget cleanup (`mode: "enforce"`):
 
 1. Remove oldest archived, orphan transcript, or orphan trajectory artifacts first.

extensions/codex/src/app-server/compact.ts

@@ -74,6 +74,7 @@ export async function maybeCompactCodexAppServerSession(
           sessionFile: params.sessionFile,
           reason: "compaction",
           runtimeContext: params.contextEngineRuntimeContext,
+          config: params.config,
         });
       } catch (error) {
         embeddedAgentLog.warn(

extensions/codex/src/app-server/run-attempt.ts

@@ -430,6 +430,7 @@ export async function runCodexAppServerAttempt(
         tokenBudget: params.contextTokenBudget,
       }),
       runMaintenance: runHarnessContextEngineMaintenance,
+      config: params.config,
       warn: (message) => embeddedAgentLog.warn(message),
     });
     historyMessages =
@@ -1178,6 +1179,7 @@ export async function runCodexAppServerAttempt(
           promptCache: result.promptCache,
         }),
         runMaintenance: runHarnessContextEngineMaintenance,
+        config: params.config,
         warn: (message) => embeddedAgentLog.warn(message),
       });
     }
@@ -1638,6 +1640,7 @@ async function mirrorTranscriptBestEffort(params: {
       sessionKey: params.sessionKey,
       messages: params.result.messagesSnapshot,
       idempotencyScope: `codex-app-server:${params.threadId}:${params.turnId}`,
+      config: params.params.config,
     });
   } catch (error) {
     embeddedAgentLog.warn("failed to mirror codex app-server transcript", { error });

extensions/codex/src/app-server/transcript-mirror.ts

@@ -6,8 +6,10 @@ import { CURRENT_SESSION_VERSION, type SessionManager } from "@mariozechner/pi-c
 import {
   acquireSessionWriteLock,
   emitSessionTranscriptUpdate,
+  resolveSessionWriteLockAcquireTimeoutMs,
   runAgentHarnessBeforeMessageWriteHook,
   type AgentMessage,
+  type SessionWriteLockAcquireTimeoutConfig,
 } from "openclaw/plugin-sdk/agent-harness-runtime";
 
 const TRANSCRIPT_APPEND_SCAN_CHUNK_BYTES = 64 * 1024;
@@ -25,6 +27,7 @@ export async function mirrorCodexAppServerTranscript(params: {
   agentId?: string;
   messages: AgentMessage[];
   idempotencyScope?: string;
+  config?: SessionWriteLockAcquireTimeoutConfig;
 }): Promise<void> {
   const messages = params.messages.filter(
     (message) => message.role === "user" || message.role === "assistant",
@@ -36,7 +39,7 @@ export async function mirrorCodexAppServerTranscript(params: {
   await fs.mkdir(path.dirname(params.sessionFile), { recursive: true });
   const lock = await acquireSessionWriteLock({
     sessionFile: params.sessionFile,
-    timeoutMs: 10_000,
+    timeoutMs: resolveSessionWriteLockAcquireTimeoutMs(params.config),
   });
   try {
     const existingIdempotencyKeys = await readTranscriptIdempotencyKeys(params.sessionFile);

src/agents/agent-command.ts

@@ -584,6 +584,7 @@ async function agentCommandInternal(
           sessionAgentId,
           threadId: opts.threadId,
           sessionCwd: resolveAcpSessionCwd(acpResolution.meta) ?? workspaceDir,
+          config: cfg,
         });
       } catch (error) {
         log.warn(
@@ -1208,6 +1209,7 @@ async function agentCommandInternal(
           sessionAgentId,
           threadId: opts.threadId,
           sessionCwd: workspaceDir,
+          config: cfg,
         });
         sessionEntry = await (
           await loadCliCompactionRuntime()

src/agents/command/attempt-execution.cli.test.ts

@@ -387,6 +387,7 @@ describe("CLI attempt execution", () => {
       storePath,
       sessionAgentId: "main",
       sessionCwd: tmpDir,
+      config: {},
     });
 
     const sessionFile = updatedEntry?.sessionFile;
@@ -443,6 +444,7 @@ describe("CLI attempt execution", () => {
       storePath,
       sessionAgentId: "main",
       sessionCwd: tmpDir,
+      config: {},
     });
 
     const messages = await readSessionMessages(updatedEntry?.sessionFile ?? "");

src/agents/command/attempt-execution.ts

@@ -21,7 +21,10 @@ import { isCliRuntimeAlias, resolveCliRuntimeExecutionProvider } from "../model-
 import { isCliProvider } from "../model-selection.js";
 import { runEmbeddedPiAgent, type EmbeddedPiRunResult } from "../pi-embedded.js";
 import { buildAgentRuntimeAuthPlan } from "../runtime-plan/auth.js";
-import { acquireSessionWriteLock } from "../session-write-lock.js";
+import {
+  acquireSessionWriteLock,
+  resolveSessionWriteLockAcquireTimeoutMs,
+} from "../session-write-lock.js";
 import { buildWorkspaceSkillSnapshot } from "../skills.js";
 import { buildUsageWithNoCost } from "../stream-message-shared.js";
 import {
@@ -76,6 +79,7 @@ type PersistTextTurnTranscriptParams = {
   sessionAgentId: string;
   threadId?: string | number;
   sessionCwd: string;
+  config: OpenClawConfig;
   assistant: {
     api: string;
     provider: string;
@@ -193,7 +197,7 @@ async function persistTextTurnTranscript(
   });
   const lock = await acquireSessionWriteLock({
     sessionFile,
-    timeoutMs: 10_000,
+    timeoutMs: resolveSessionWriteLockAcquireTimeoutMs(params.config),
     allowReentrant: true,
   });
   try {
@@ -202,6 +206,7 @@ async function persistTextTurnTranscript(
         transcriptPath: sessionFile,
         sessionId: params.sessionId,
         cwd: params.sessionCwd,
+        config: params.config,
         message: {
           role: "user",
           content: promptText,
@@ -215,6 +220,7 @@ async function persistTextTurnTranscript(
         transcriptPath: sessionFile,
         sessionId: params.sessionId,
         cwd: params.sessionCwd,
+        config: params.config,
         message: {
           role: "assistant",
           content: [{ type: "text", text: replyText }],
@@ -264,6 +270,7 @@ export async function persistAcpTurnTranscript(params: {
   sessionAgentId: string;
   threadId?: string | number;
   sessionCwd: string;
+  config: OpenClawConfig;
 }): Promise<SessionEntry | undefined> {
   return await persistTextTurnTranscript({
     ...params,
@@ -287,6 +294,7 @@ export async function persistCliTurnTranscript(params: {
   sessionAgentId: string;
   threadId?: string | number;
   sessionCwd: string;
+  config: OpenClawConfig;
 }): Promise<SessionEntry | undefined> {
   const replyText = resolveCliTranscriptReplyText(params.result);
   const provider = params.result.meta.agentMeta?.provider?.trim() ?? "cli";
@@ -304,6 +312,7 @@ export async function persistCliTurnTranscript(params: {
     sessionAgentId: params.sessionAgentId,
     threadId: params.threadId,
     sessionCwd: params.sessionCwd,
+    config: params.config,
     assistant: {
       api: "cli",
       provider,

src/agents/command/cli-compaction.ts

@@ -166,6 +166,7 @@ async function compactCliTranscript(params: {
     reason: "compaction",
     sessionManager: params.sessionManager,
     runtimeContext,
+    config: params.cfg,
   });
   return true;
 }