fix(backup): skip delivery-queue json files from backup snapshots

abnershang · abnershang · commit 9d2812f7bdc5 · 2026-05-09T15:10:22.000+08:00
Real-world run of `openclaw backup create` on v2026.5.7 reproduced an

ENOENT race on a delivery-queue entry:

  Error: ENOENT: no such file or directory, lstat

    '$STATE_DIR/delivery-queue/3fac5e46-...json'

Files under `{stateDir}/delivery-queue/**/*.json` are transient IPC

state for the messaging delivery queue: they are created and consumed

continuously and routinely vanish between tar's directory read and

`lstat()`. They have no restoration value — capturing a partial tail

only risks tar corruption without benefit.

Extends the volatile filter with the same `isUnder` + `hasExtension`

rule style as the existing sessions / cron-runs / logs rules, and

keeps the JSDoc rule list in sync.

Tests: 44/44 green across backup-volatile-filter + backup-create.

Built-by: Vulcan 🔨
diff --git a/src/infra/backup-volatile-filter.test.ts b/src/infra/backup-volatile-filter.test.ts
@@ -55,6 +55,32 @@ describe("isVolatileBackupPath", () => {
     expect(isVolatileBackupPath(`${stateDir}/logs/../notes.jsonl`, plan)).toBe(false);
   });
 
+  it("treats delivery-queue json files under stateDir as volatile", () => {
+    expect(
+      isVolatileBackupPath(
+        `${stateDir}/delivery-queue/3fac5e46-42dc-4230-a725-51c203830b4f.json`,
+        plan,
+      ),
+    ).toBe(true);
+  });
+
+  it("treats nested delivery-queue json files under stateDir as volatile", () => {
+    expect(
+      isVolatileBackupPath(
+        `${stateDir}/delivery-queue/subdir/3fac5e46-42dc-4230-a725-51c203830b4f.json`,
+        plan,
+      ),
+    ).toBe(true);
+  });
+
+  it("does not treat non-json delivery-queue files as volatile", () => {
+    expect(isVolatileBackupPath(`${stateDir}/delivery-queue/README.md`, plan)).toBe(false);
+  });
+
+  it("does not treat delivery-queue json outside stateDir as volatile", () => {
+    expect(isVolatileBackupPath(`/tmp/delivery-queue/file.json`, plan)).toBe(false);
+  });
+
   it("normalizes Windows-style separators before anchor checks", () => {
     const winStateDir = "C:\\openclaw\\state";
     const winPlan = { stateDirs: [winStateDir] };
diff --git a/src/infra/backup-volatile-filter.ts b/src/infra/backup-volatile-filter.ts
@@ -48,6 +48,7 @@ export type VolatileFilterPlan = {
  *   - `{stateDir}/sessions/**`/`*.{jsonl,log}`
  *   - `{stateDir}/cron/runs/**`/`*.log`
  *   - `{stateDir}/logs/**`/`*.{jsonl,log}`
+ *   - `{stateDir}/delivery-queue/**`/`*.json`
  *   - Any file matching `*.{sock,pid,tmp,lock}` anywhere under scope
  */
 export function isVolatileBackupPath(absolutePath: string, plan: VolatileFilterPlan): boolean {
@@ -80,6 +81,11 @@ export function isVolatileBackupPath(absolutePath: string, plan: VolatileFilterP
     if (isUnder(filePosix, logsRoot) && hasExtension(filePosix, [".jsonl", ".log"])) {
       return true;
     }
+
+    const deliveryQueueRoot = path.posix.join(stateDirPosix, "delivery-queue");
+    if (isUnder(filePosix, deliveryQueueRoot) && hasExtension(filePosix, [".json"])) {
+      return true;
+    }
   }
 
   return false;
