fix: keep live OpenClaw session locks during cleanup (#88129)

steipete · web-flow · commit 0b86decf948d · 2026-05-29T22:42:04.000+02:00
Keep session lock cleanup from removing live OpenClaw-owned locks solely because they are old. Cleanup now reports age-only stale locks without deleting them, while still removing dead, orphaned, recycled, malformed-old, and non-OpenClaw-owned locks. Update doctor docs and regression coverage for the cleanup/repair contract. Refs #87779
diff --git a/docs/gateway/doctor.md b/docs/gateway/doctor.md
@@ -382,7 +382,7 @@ That stages grounded durable candidates into the short-term dreaming store while
 
   </Accordion>
   <Accordion title="3c. Session lock cleanup">
-    Doctor scans every agent session directory for stale write-lock files — files left behind when a session exited abnormally. For each lock file found it reports: the path, PID, whether the PID is still alive, lock age, and whether it is considered stale (dead PID, older than 30 minutes, or a live PID that can be proven to belong to a non-OpenClaw process). In `--fix` / `--repair` mode it removes stale lock files automatically; otherwise it prints a note and instructs you to rerun with `--fix`.
+    Doctor scans every agent session directory for stale write-lock files — files left behind when a session exited abnormally. For each lock file found it reports: the path, PID, whether the PID is still alive, lock age, and whether it is considered stale (dead PID, malformed owner metadata, older than 30 minutes, or a live PID that can be proven to belong to a non-OpenClaw process). In `--fix` / `--repair` mode it removes locks with dead, orphaned, recycled, malformed-old, or non-OpenClaw owners automatically. Old locks that are still owned by a live OpenClaw process are reported but left in place so doctor does not cut off an active transcript writer.
   </Accordion>
   <Accordion title="3d. Session transcript branch repair">
     Doctor scans agent session JSONL files for the duplicated branch shape created by the 2026.4.24 prompt transcript rewrite bug: an abandoned user turn with OpenClaw internal runtime context plus an active sibling containing the same visible user prompt. In `--fix` / `--repair` mode, doctor backs up each affected file next to the original and rewrites the transcript to the active branch so gateway history and memory readers no longer see duplicate turns.
diff --git a/src/agents/session-write-lock.test.ts b/src/agents/session-write-lock.test.ts
@@ -668,7 +668,7 @@ describe("acquireSessionWriteLock", () => {
         },
         {
           name: "old-live.jsonl.lock",
-          removed: true,
+          removed: false,
           stale: true,
           staleReasons: ["too-old"],
         },
@@ -680,17 +680,82 @@ describe("acquireSessionWriteLock", () => {
           stale: true,
           staleReasons: ["dead-pid", "too-old"],
         },
+      ]);
+
+      await expectPathMissing(staleDeadLock);
+      await expect(fs.access(staleAliveLock)).resolves.toBeUndefined();
+      await expect(fs.access(freshAliveLock)).resolves.toBeUndefined();
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("cleans old live .jsonl lock files owned by non-OpenClaw processes", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-lock-"));
+    const sessionsDir = path.join(root, "sessions");
+    await fs.mkdir(sessionsDir, { recursive: true });
+    const nowMs = Date.now();
+    const lockPath = path.join(sessionsDir, "old-non-openclaw.jsonl.lock");
+
+    try {
+      await fs.writeFile(
+        lockPath,
+        JSON.stringify({
+          pid: process.pid,
+          createdAt: new Date(nowMs - 120_000).toISOString(),
+        }),
+        "utf8",
+      );
+
+      const result = await cleanStaleLockFiles({
+        sessionsDir,
+        staleMs: 30_000,
+        nowMs,
+        removeStale: true,
+        readOwnerProcessArgs: () => ["python", "worker.py"],
+      });
+
+      expect(lockCleanupRecords(result.cleaned)).toEqual([
         {
-          name: "old-live.jsonl.lock",
+          name: "old-non-openclaw.jsonl.lock",
           removed: true,
           stale: true,
-          staleReasons: ["too-old"],
+          staleReasons: ["too-old", "non-openclaw-owner"],
         },
       ]);
+      await expectPathMissing(lockPath);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
 
-      await expectPathMissing(staleDeadLock);
-      await expectPathMissing(staleAliveLock);
-      await expect(fs.access(freshAliveLock)).resolves.toBeUndefined();
+  it("does not clean fresh malformed .jsonl lock files during cleanup sweeps", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-lock-"));
+    const sessionsDir = path.join(root, "sessions");
+    await fs.mkdir(sessionsDir, { recursive: true });
+    const nowMs = Date.now();
+    const lockPath = path.join(sessionsDir, "fresh-malformed.jsonl.lock");
+
+    try {
+      await fs.writeFile(lockPath, "{}", "utf8");
+
+      const result = await cleanStaleLockFiles({
+        sessionsDir,
+        staleMs: 30_000,
+        nowMs,
+        removeStale: true,
+      });
+
+      expect(lockCleanupRecords(result.locks)).toEqual([
+        {
+          name: "fresh-malformed.jsonl.lock",
+          removed: false,
+          stale: true,
+          staleReasons: ["missing-pid", "invalid-createdAt"],
+        },
+      ]);
+      expect(result.cleaned).toEqual([]);
+      await expect(fs.access(lockPath)).resolves.toBeUndefined();
     } finally {
       await fs.rm(root, { recursive: true, force: true });
     }
diff --git a/src/agents/session-write-lock.ts b/src/agents/session-write-lock.ts
@@ -43,6 +43,7 @@ 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"]);
 
 /**
  * Yield control to the event loop so other sessions can make progress
@@ -530,7 +531,10 @@ function shouldTreatAsNonOpenClawOwner(params: {
   heldByThisProcess: boolean;
   readOwnerProcessArgs: SessionLockOwnerProcessArgsReader;
 }): boolean {
-  if (params.inspected.stale || params.inspected.pid === null || !params.inspected.pidAlive) {
+  if (params.inspected.pid === null || !params.inspected.pidAlive) {
+    return false;
+  }
+  if (params.inspected.staleReasons.includes("recycled-pid")) {
     return false;
   }
   if (params.inspected.pid === process.pid && params.heldByThisProcess) {
@@ -578,6 +582,21 @@ async function shouldReclaimContendedLockFile(
   }
 }
 
+async function shouldRemoveLockDuringCleanup(
+  lockPath: string,
+  details: LockInspectionDetails,
+  staleMs: number,
+  nowMs: number,
+): Promise<boolean> {
+  if (!details.stale) {
+    return false;
+  }
+  if (details.staleReasons.every((reason) => REPORT_ONLY_STALE_LOCK_REASONS.has(reason))) {
+    return false;
+  }
+  return await shouldReclaimContendedLockFile(lockPath, details, staleMs, nowMs);
+}
+
 function sessionLockHeldByThisProcess(normalizedSessionFile: string): boolean {
   return SESSION_LOCKS.heldEntries().some(
     (entry) => entry.normalizedTargetPath === normalizedSessionFile,
@@ -728,7 +747,7 @@ export async function cleanStaleLockFiles(params: {
       removed: false,
     };
 
-    if (lockInfo.stale && removeStale) {
+    if (removeStale && (await shouldRemoveLockDuringCleanup(lockPath, lockInfo, staleMs, nowMs))) {
       await fs.rm(lockPath, { force: true });
       lockInfo.removed = true;
       cleaned.push(lockInfo);
diff --git a/src/commands/doctor-session-locks.test.ts b/src/commands/doctor-session-locks.test.ts
@@ -104,7 +104,7 @@ describe("noteSessionLockHealth", () => {
     await expect(fs.access(freshLock)).resolves.toBeUndefined();
   });
 
-  it("uses configured stale threshold when repairing lock files", async () => {
+  it("uses configured stale threshold without removing live OpenClaw lock files", async () => {
     const sessionsDir = state.sessionsDir();
     await fs.mkdir(sessionsDir, { recursive: true });
 
@@ -124,8 +124,8 @@ describe("noteSessionLockHealth", () => {
     expect(note).toHaveBeenCalledTimes(1);
     const [message] = firstNoteCall();
     expect(message).toContain("stale=yes (too-old)");
-    expect(message).toContain("[removed]");
-    await expectPathMissing(configuredStaleLock);
+    expect(message).not.toContain("[removed]");
+    await expect(fs.access(configuredStaleLock)).resolves.toBeUndefined();
   });
 
   it("removes fresh live locks when the owner is not an OpenClaw process", async () => {
