fix: backup skips volatile cache paths by ZengWen-DT · Pull Request #98879 · openclaw/openclaw

ZengWen-DT · 2026-07-02T03:30:17Z

What Problem This Solves

Fixes an issue where openclaw backup create could archive disposable agent runtime cache, browser cache, retired archive, and transient side-effect files from runtime-owned state paths. Those paths can be large or short-lived during live operation, so including them can bloat backups or make archive creation fail if a disposable file disappears while tar is walking the tree.

Why This Change Was Made

The backup volatile-path filter now covers agent runtime tmp/cache/shell snapshot directories, managed browser user-data cache/resource directories, retired archive paths, and non-SQLite transient lock/partial/WAL/SHM/journal paths under transient-owned roots while preserving durable agent auth/profile files, browser profile files, and installed plugin source under state/extensions. The archive writer also gives node-tar a backup-scoped synthetic stat cache for known volatile paths so entries that vanish before lstat still reach the normal filtered skip path; SQLite sidecars remain under the existing SQLite snapshot safety checks instead of the generic volatile path.

User Impact

Backup archives are smaller and more reliable during live OpenClaw use. Operators still get durable state such as agent auth profiles, browser profile preferences/cookies, and installed plugin source lockfiles, while disposable runtime/cache paths are counted in skippedVolatileCount and omitted from the tarball.

Evidence

Source/dependency check: [email protected] calls filter only after lstat succeeds in Pack, so a disappeared file can reject before the existing filter sees it; the new scoped statCache handles only paths already classified as volatile.
Real backup behavior after repair: with an isolated OPENCLAW_STATE_DIR containing agent cache, browser Default/Cache, a retired archive path, transient-root cache/queue/item.wal and downloads/download.partial, durable browser Default/Preferences, and durable state/extensions/example/{Cargo.lock,download.partial}, running pnpm openclaw backup create --output <tmp>/out --no-include-workspace --json produced skippedVolatileCount=5; tar -tzf showed durable browser preferences and both state/extensions files, and did not show the cache/archive/transient-root side-effect paths.
Real agent turn: pnpm openclaw agent --local --agent proof --model deepseek/deepseek-v4-pro --message "Reply with exactly: backup proof agent ok" --json --timeout 180 completed through provider deepseek, model deepseek-v4-pro, HTTP status 200, final text backup proof agent ok.
node scripts/run-vitest.mjs src/infra/backup-volatile-filter.test.ts src/infra/backup-create.test.ts passed after repair: 63 unit-fast tests and 39 infra tests.
node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core.tsbuildinfo && node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.test.src.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/test-src.tsbuildinfo passed after repair.
pnpm format:fix -- src/infra/backup-volatile-filter.ts src/infra/backup-volatile-filter.test.ts src/infra/backup-create.test.ts passed after repair.
pnpm format:docs:check -- docs/cli/backup.md passed.
git diff --check passed after repair.
pnpm build passed after repair.
./.agents/skills/autoreview/scripts/autoreview --mode local passed after repair with no accepted/actionable findings.

AI-assisted.

clawsweeper · 2026-07-02T03:34:00Z

Codex review: needs real behavior proof before merge. Reviewed July 2, 2026, 2:01 AM ET / 06:01 UTC.

Summary
The PR adds a backup-scoped node-tar statCache that synthesizes stats for paths already classified as volatile, plus a regression test for disappearing volatile files.

PR surface: Source +39, Tests +48. Total +87 across 2 files.

Reproducibility: yes. source-reproducible: current main's volatile predicate lacks the requested agent runtime, browser cache, archived, and transient suffix rules, and the PR head only calls that predicate from statCache. I did not run a live filesystem-race repro in this read-only review.

Review metrics: 1 noteworthy metric.

Requested Filter Families: 0 of 4 added in net diff. The canonical issue asks for agent runtime, browser cache/resource, archived, and transient-suffix rules, but the current PR no longer changes the volatile predicate.

Stored data model
Persistent data-model change detected: persistent cache schema: src/infra/backup-create.test.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #98865
Summary: This PR is a partial candidate for the canonical backup volatile-path issue, but the current head does not yet implement the central missing filter families.

Members:

canonical: Backup archive should skip volatile agent runtime and browser cache paths #98865 - The PR body uses closing syntax for this issue, and that issue contains the acceptance criteria for the broader volatile path families.
partial_overlap: fix(backup): retry on tar EOF race and skip known volatile files #72251 - That merged PR introduced the existing backup volatile filter and tar EOF retry baseline, but it does not cover the additional path families requested here.
partial_overlap: fix(backup): filter agent volatile dirs, browser cache, and lock files from archives #98882 - That closed unmerged PR targeted the same canonical issue, but it is not a viable replacement landing path.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🧂 unranked krab
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

[P1] Either implement the missing volatile predicate rules with focused tests, or retitle and unlink the PR as a stat-cache-only fix.
[P1] Add exact-head real backup proof after the scope is corrected, with private paths, credentials, phone numbers, endpoints, and other sensitive details redacted.

Proof guidance:

[P1] Needs stronger real behavior proof before merge: Terminal proof is present, but it describes broader filter behavior missing from the current head; exact-head backup proof should be refreshed with private details redacted. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

[P1] Merging with the current closing reference would likely close Backup archive should skip volatile agent runtime and browser cache paths #98865 while its central volatile filter expansion remains unimplemented.
[P1] The terminal proof and PR body describe broader cache/archive/transient filtering that is not present in the current head, so reviewers could overestimate what this branch proves.

Maintainer options:

Complete Or Narrow Before Merge (recommended)
Update the branch so it either implements the claimed filter families with tests and exact-head proof, or removes the closing reference and stale broad claims.
Accept As Partial Fix
Maintainers could intentionally merge the stat-cache-only improvement only if the canonical issue remains open for the missing volatile path classes.
Pause In Favor Of Canonical Issue
If this branch is no longer intended to carry the filter expansion, pause or close it and continue from the canonical issue instead.

Next step before merge

[P1] Maintainer/contributor action is needed to choose the final scope and provide exact-head real behavior proof; automation should not repair around the missing contributor proof gate.

Security
Cleared: The diff touches backup archive code and tests only; no dependency, workflow, package-script, credential, permission, or downloaded-code path changes were found.

Review findings

[P1] Cover the missing volatile path families — src/infra/backup-create.ts:70-72

Review details

Best possible solution:

Either restore the narrow volatile-filter expansion with exact-head backup proof, or retitle and unlink this as a stat-cache-only race fix while keeping the canonical issue open.

Do we have a high-confidence way to reproduce the issue?

Yes, source-reproducible: current main's volatile predicate lacks the requested agent runtime, browser cache, archived, and transient suffix rules, and the PR head only calls that predicate from statCache. I did not run a live filesystem-race repro in this read-only review.

Is this the best way to solve the issue?

No. The stat-cache layer is a good sub-fix for ENOENT on already-volatile paths, but the best fix for the linked backup bug must also update the centralized volatile predicate or narrow the PR scope.

Full review comments:

[P1] Cover the missing volatile path families — src/infra/backup-create.ts:70-72
The new stat cache only synthesizes stats for paths that isVolatileBackupPath already marks volatile. The canonical backup issue asks for agent runtime cache/tmp/shell snapshots, browser cache/resource paths, retired archive paths, and transient lock/partial/WAL/SHM/journal paths; those still reach tar traversal unless the predicate is extended or the PR is narrowed and unlinked from that broader issue.
Confidence: 0.91

Overall correctness: patch is incorrect
Overall confidence: 0.91

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 75240f438564.

Label changes

Label justifications:

P2: This is a normal-priority backup reliability fix with bounded CLI/archive impact.
merge-risk: 🚨 other: Merging as written could close the canonical backup issue while the requested filter expansion remains missing.
rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🧂 unranked krab.
status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: Terminal proof is present, but it describes broader filter behavior missing from the current head; exact-head backup proof should be refreshed with private details redacted. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

PR surface:

Source +39, Tests +48. Total +87 across 2 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	1	41	2	+39
Tests	1	48	0	+48
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	2	89	2	+87

What I checked:

PR head only handles already-classified volatile paths: At the current PR head, BackupVolatileStatCache returns a synthetic stat only when isVolatileBackupPath already returns true, so it cannot cover missing path families in the predicate. (src/infra/backup-create.ts:70, 1ac0f28a1201)
Current main filter remains narrower than requested: Current main's volatile predicate covers sessions, cron/log files, delivery queues, and .sock/.pid/.tmp under state, but not agent runtime cache/tmp/shell snapshots, browser cache/resource paths, archived paths, or lock/partial/WAL/SHM/journal suffixes. (src/infra/backup-volatile-filter.ts:72, 75240f438564)
Archive creation depends on the same predicate: createBackupArchive increments skippedVolatileCount and excludes entries only when isVolatileBackupPath matches, so non-matching cache/archive paths are still traversed and archived. (src/infra/backup-create.ts:825, 75240f438564)
Canonical issue asks for broader behavior: The linked canonical issue asks to skip agent runtime tmp/cache/shell snapshots, browser cache/resource paths, retired archives, wider transient suffixes, and ENOENT on those volatile paths.
Dependency contract supports the narrow mechanism: tar v7.5.16 checks statCache before lstat and applies filter after a stat object exists, so a synthetic stat is appropriate only for paths the OpenClaw predicate already classifies as volatile. (node-tar/src/pack.ts:399)
Feature provenance: Merged PR fix(backup): retry on tar EOF race and skip known volatile files #72251 introduced the current backup volatile filter and retry behavior that this PR builds on. (src/infra/backup-create.ts, 9eaca28ef715)

Likely related people:

abnershang: Merged PR metadata and git show tie the current live-backup EOF retry and volatile filter to commit 9eaca28. (role: introduced current volatile-filter behavior; confidence: high; commits: 9eaca28ef715; files: src/infra/backup-create.ts, src/infra/backup-volatile-filter.ts, src/infra/backup-create.test.ts)
steipete: Live PR metadata for the merged backup volatile-filter baseline records steipete as merger and landing-comment author. (role: merger and recent backup-area reviewer; confidence: high; commits: 9eaca28ef715; files: src/infra/backup-create.ts, src/infra/backup-volatile-filter.ts)
shichangs: Commit 0ecfd37 added the local backup CLI, docs, and command surface affected by this PR. (role: backup CLI surface introducer; confidence: high; commits: 0ecfd37b4465; files: src/commands/backup.ts, src/commands/backup-shared.ts, docs/cli/backup.md)
Gustavo Madeira Santana: Commit 3ba6491 extracted the backup archive infrastructure into src/infra/backup-create.ts. (role: adjacent backup infrastructure contributor; confidence: medium; commits: 3ba64916599b; files: src/infra/backup-create.ts, src/commands/backup.ts)
vincentkoc: The live PR timeline shows vincentkoc force-pushed the current head and is assigned, making them a likely follow-up routing contact for this branch state. (role: current PR branch updater and assignee; confidence: medium; commits: 1ac0f28a1201; files: src/infra/backup-create.ts, src/infra/backup-create.test.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

ZengWen-DT · 2026-07-02T03:51:04Z

@clawsweeper re-review

Addressed the backup volatile suffix finding by narrowing .lock/.partial/WAL/SHM/journal-style skips to transient-owned roots such as cache, downloads, locks, tmp, and queue paths. Durable installed plugin source files under state/extensions, including Cargo.lock and download.partial, now stay in the archive.

Fresh evidence:

node scripts/run-vitest.mjs src/infra/backup-volatile-filter.test.ts src/infra/backup-create.test.ts
node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core.tsbuildinfo && node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.test.src.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/test-src.tsbuildinfo
real pnpm openclaw backup create --output <tmp>/out --no-include-workspace --json proof confirmed state/extensions/example/{Cargo.lock,download.partial} are included while cache/archive/transient-root side-effect paths are skipped
git diff --check
pnpm build
./.agents/skills/autoreview/scripts/autoreview --mode local

clawsweeper · 2026-07-02T03:51:06Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

vincentkoc · 2026-07-02T06:05:20Z

Land-ready proof for repaired head 1ac0f28a120126fee297c9ecd28e0f1fd2e61e8b:

narrowed the contributor branch to the real node-tar disappearance race; removed the unproven expansion of backup-exclusion policy and its docs/tests
dependency contract checked against tar 7.5.16: Pack consults statCache before lstat, then applies filter in ONSTAT; the synthetic stat is returned only for paths the existing volatile predicate rejects
focused Testbox proof: tbx_01kwgmny2ayh0d6fe2xmvy8gg5 — format check and 71 backup tests passed
scoped check:changed passed on the same Testbox
fresh autoreview: clean, no accepted/actionable findings (confidence 0.99)
exact-head GitHub CI: https://github.com/openclaw/openclaw/actions/runs/28568768579 — completed successfully, including the previously failing whole-suite shard after rebasing onto the main inventory fix
repository-native OPENCLAW_TESTBOX=1 scripts/pr prepare-run 98879 passed

Known proof gaps: none for the bounded writer-level race fix. The broader question of additional disposable backup paths remains intentionally out of this PR.

vincentkoc · 2026-07-02T06:05:43Z

Merged via squash.

Prepared head SHA: 1ac0f28a120126fee297c9ecd28e0f1fd2e61e8b
Landed commit: e0970cfec57219e461506f438c487586a1a7f2f7

…ilter.ts (openclaw#98879) Replace the vague one-line description of skipped files with a structured list matching isVolatileBackupPath in src/infra/backup-volatile-filter.ts. The filter was introduced in PR openclaw#98879 (fixes openclaw#98865) but the docs were not updated at the time. Each rule is listed with its glob pattern so operators can understand exactly which files are excluded from backup archives.

* fix: skip volatile backup cache paths * fix(backup): tolerate disappearing volatile files --------- Co-authored-by: Vincent Koc <[email protected]>

openclaw-barnacle Bot added docs Improvements or additions to documentation size: M labels Jul 2, 2026

clawsweeper Bot mentioned this pull request Jul 2, 2026

fix(backup): filter agent volatile dirs, browser cache, and lock files from archives #98882

Closed

2 tasks

ZengWen-DT force-pushed the fix/98865-backup-volatile-cache-paths branch from 72cf342 to 9bcea8e Compare July 2, 2026 03:50

github-actions Bot mentioned this pull request Jul 2, 2026

🦞 OpenClaw 生态日报 2026-07-02 96loveslife/big_model_radar#91

Open

vincentkoc force-pushed the fix/98865-backup-volatile-cache-paths branch from 9bcea8e to 2e56a6c Compare July 2, 2026 05:39

openclaw-barnacle Bot added size: S and removed docs Improvements or additions to documentation size: M labels Jul 2, 2026

vincentkoc self-assigned this Jul 2, 2026

fix: skip volatile backup cache paths

66b3092

fix(backup): tolerate disappearing volatile files

1ac0f28

vincentkoc force-pushed the fix/98865-backup-volatile-cache-paths branch from 2e56a6c to 1ac0f28 Compare July 2, 2026 05:55

vincentkoc merged commit e0970cf into openclaw:main Jul 2, 2026
95 checks passed

sheyanmin mentioned this pull request Jul 2, 2026

fix(infra): extend backup volatile filter to skip agent runtime cache, browser cache, archived paths and transient lock/partial/wal/shm/journal files #98969

Closed

4 tasks

github-actions Bot mentioned this pull request Jul 2, 2026

📡 Upstream Digest — 2026-07-02 07:23 UTC curtismercier/openclaw-mods#1187

Open

maweibin mentioned this pull request Jul 2, 2026

docs(backup): list volatile path rules aligned with backup-volatile-filter.ts (#98879) #99007

Merged

clawsweeper Bot mentioned this pull request Jul 8, 2026

Backup archive volatile-path filtering remains incomplete after the upstream #98865 fix release candidate #101975

Closed

clawsweeper Bot mentioned this pull request Jul 25, 2026

Backup can fail on volatile Codex shell snapshots #113546

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix: backup skips volatile cache paths#98879

fix: backup skips volatile cache paths#98879
vincentkoc merged 2 commits into
openclaw:mainfrom
ZengWen-DT:fix/98865-backup-volatile-cache-paths

ZengWen-DT commented Jul 2, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jul 2, 2026 •

edited

Loading

Uh oh!

ZengWen-DT commented Jul 2, 2026

Uh oh!

clawsweeper Bot commented Jul 2, 2026 •

edited

Loading

Uh oh!

vincentkoc commented Jul 2, 2026

Uh oh!

Uh oh!

vincentkoc commented Jul 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

ZengWen-DT commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

clawsweeper Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ZengWen-DT commented Jul 2, 2026

Uh oh!

clawsweeper Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vincentkoc commented Jul 2, 2026

Uh oh!

Uh oh!

vincentkoc commented Jul 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ZengWen-DT commented Jul 2, 2026 •

edited

Loading

clawsweeper Bot commented Jul 2, 2026 •

edited

Loading

clawsweeper Bot commented Jul 2, 2026 •

edited

Loading