fix(agents): reclaim session write-locks held past the holder's own maxHoldMs

openperf · openperf · commit 25db525072d7 · 2026-06-03T14:07:52.000+08:00
diff --git a/docs/reference/session-management-compaction.md b/docs/reference/session-management-compaction.md
@@ -98,8 +98,11 @@ Transcript mutations use a session write lock on the transcript file. Lock acqui
 `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. `session.writeLock.staleMs` controls when an existing lock can be
-reclaimed as stale; the default is `1800000` ms. `session.writeLock.maxHoldMs` controls the
-in-process watchdog release threshold; the default is `300000` ms. Emergency env overrides are
+reclaimed as stale; the default is `1800000` ms. `session.writeLock.maxHoldMs` is the hard hold
+limit: the holder's own in-process watchdog releases the lock at this threshold, and a contending
+writer may also reclaim a lock held past this deadline (when the lock file is unchanged) so a
+wedged holder whose watchdog cannot fire does not pin the session; the default is `300000` ms.
+Emergency env overrides are
 `OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS`, `OPENCLAW_SESSION_WRITE_LOCK_STALE_MS`, and
 `OPENCLAW_SESSION_WRITE_LOCK_MAX_HOLD_MS`.
 
diff --git a/src/agents/session-write-lock.test.ts b/src/agents/session-write-lock.test.ts
@@ -467,6 +467,34 @@ describe("acquireSessionWriteLock", () => {
     });
   });
 
+  it("reclaims a live OpenClaw-owned lock that exceeded its own maxHoldMs", async () => {
+    await withTempSessionLockFile(async ({ sessionFile, lockPath }) => {
+      const owner = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)", "openclaw"], {
+        stdio: "ignore",
+      });
+      if (!owner.pid) {
+        throw new Error("missing lock owner pid");
+      }
+      // Live OpenClaw owner, within staleMs but past its own recorded maxHoldMs: a stuck
+      // holder whose in-process watchdog can never fire must still be reclaimable. (#87483)
+      await fs.writeFile(
+        lockPath,
+        JSON.stringify({
+          pid: owner.pid,
+          createdAt: new Date(Date.now() - 30_000).toISOString(),
+          maxHoldMs: 1_000,
+        }),
+        "utf8",
+      );
+
+      try {
+        await expectCurrentPidOwnsLock({ sessionFile, timeoutMs: 500, staleMs: 600_000 });
+      } finally {
+        owner.kill("SIGTERM");
+      }
+    });
+  });
+
   it("retries when a stale lock report disappears before diagnostics", async () => {
     await withTempSessionLockFile(async ({ sessionFile, lockPath }) => {
       const owner = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)", "openclaw"], {
diff --git a/src/agents/session-write-lock.ts b/src/agents/session-write-lock.ts
@@ -46,7 +46,10 @@ export const DEFAULT_SESSION_WRITE_LOCK_MAX_HOLD_MS = 5 * 60 * 1000;
 export const DEFAULT_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS = 60_000;
 const DEFAULT_WATCHDOG_INTERVAL_MS = 60_000;
 const DEFAULT_TIMEOUT_GRACE_MS = 2 * 60 * 1000;
-const REPORT_ONLY_STALE_LOCK_REASONS = new Set(["too-old", "hold-exceeded"]);
+// "too-old" (past global staleMs) stays report-only — a live holder may still be within its own
+// maxHoldMs. "hold-exceeded" (past the holder's OWN recorded maxHoldMs) is overdue by contract and
+// reclaimable; acquire's remove-if-unchanged still skips a lock whose file changed (e.g. a release). (#87483)
+const REPORT_ONLY_STALE_LOCK_REASONS = new Set(["too-old"]);
 
 /**
  * Yield control to the event loop so other sessions can make progress
diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts
@@ -1651,7 +1651,7 @@ export const FIELD_HELP: Record<string, string> = {
   "session.writeLock.staleMs":
     "Milliseconds before an existing session transcript lock can be treated as stale and reclaimed. Default: 1800000; env override: OPENCLAW_SESSION_WRITE_LOCK_STALE_MS.",
   "session.writeLock.maxHoldMs":
-    "Milliseconds a held in-process session transcript lock may remain held before the watchdog releases it. Default: 300000; env override: OPENCLAW_SESSION_WRITE_LOCK_MAX_HOLD_MS.",
+    "Milliseconds a held session transcript lock may remain held before it is reclaimed: the holder's own in-process watchdog releases it, and a contending writer may also reclaim it once this deadline passes if the lock file is unchanged. Default: 300000; env override: OPENCLAW_SESSION_WRITE_LOCK_MAX_HOLD_MS.",
   "session.agentToAgent":
     "Groups controls for inter-agent session exchanges, including loop prevention limits on reply chaining. Keep defaults unless you run advanced agent-to-agent automation with strict turn caps.",
   "session.agentToAgent.maxPingPongTurns":
