fix(snapshot): clarify OpenClaw workspace persistence

[apurvvkumaria]

Summary

OpenClaw's managed shell uses /sandbox as its home while durable workspace files live under /sandbox/.openclaw/workspace. This change makes that boundary explicit and adds the missing live regression for preserving USER.md and SOUL.md through snapshot creation, sandbox destruction, fresh same-name onboarding, and restore.

The snapshot scope remains manifest-defined; arbitrary files under /sandbox are not added to backups.

Related Issue

Related to #8136. The issue remains open pending reporter confirmation with the canonical OpenClaw workspace paths.

Changes

• Warn OpenClaw users that ~/USER.md and ~/SOUL.md resolve outside the managed workspace and are not included in snapshots.
• Direct users to $OPENCLAW_WORKSPACE_DIR/USER.md and $OPENCLAW_WORKSPACE_DIR/SOUL.md.
• Extend the snapshot-commands live target to create those canonical files, destroy the source sandbox, freshly onboard the same name, restore the saved snapshot, and verify file contents and policy metadata.
• Preserve the existing snapshot security boundary instead of capturing arbitrary sandbox-home files.
• Keep credential-root documentation aligned with the enforced root:sandbox 0710 search-only root and root-only descendants.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Independent Codex Desktop security review passed for validated commit 0bc10a053. The change preserves the manifest-defined snapshot scope, credential redaction, sandbox-name validation, shell quoting, cleanup registration, and the root-only credential descendant boundary.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: docs/manage-sandboxes/backup-restore.mdx, docs/manage-sandboxes/workspace-files.mdx, and docs/security/credential-storage.mdx; verified OpenClaw workspace snapshot paths and confidentiality-root versus descendant permissions; npm run docs passed with 0 errors and 2 known nonblocking warnings.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable; scripts/prepare-dgx-station-host.sh is unchanged.
• Station profile/scenario: Not applicable.
• Result: Not applicable.
• Supporting evidence: Not applicable.

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — the isolated support regression passed all 34 tests; semantic E2E phase validation covered 117 tests across 74 files; project membership, title style, test-size, source-shape, CLI type checking, documentation routes, formatting, secret scanning, and diff checks passed.
• Applicable broad gate passed — the refreshed PR E2E gate is running and must pass before merge.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only) — the build passed with zero errors and two known nonblocking Fern warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• Documentation

  • Clarified that ~ resolves to /sandbox, not the managed workspace, and files stored there are excluded from snapshots.
  • Recommended storing important files, including USER.md and SOUL.md, under $OPENCLAW_WORKSPACE_DIR.

• Tests

  • Expanded snapshot coverage to verify workspace files are excluded from fresh environments and restored correctly from backups, including after a fresh onboarding flow.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 86df0262-5fe1-4c8e-907c-517b7c389a34

📥 Commits

Reviewing files that changed from the base of the PR and between 21ffb95 and 0bc10a0.

📒 Files selected for processing (2)

• docs/security/credential-storage.mdx
• test/e2e/live/snapshot-commands.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• test/e2e/live/snapshot-commands.test.ts

---

📝 Walkthrough

Walkthrough

The documentation clarifies that ~ resolves to /sandbox. Snapshot tests use OPENCLAW_WORKSPACE_DIR, verify canonical workspace files, and update credential-root permission expectations.

Changes

OpenClaw workspace snapshots

Layer / File(s)	Summary
Managed workspace path documentation docs/manage-sandboxes/backup-restore.mdx, docs/manage-sandboxes/workspace-files.mdx	Documents /sandbox path resolution and directs snapshot-managed files to $OPENCLAW_WORKSPACE_DIR.
Workspace snapshot recovery validation test/e2e/live/snapshot-commands.test.ts	Adds canonical workspace fixtures and verifies their creation, clean replacement after onboarding, and recovery during snapshot restore.
Credential-root permission expectations docs/security/credential-storage.mdx, test/e2e/live/snapshot-commands.test.ts	Documents and verifies root:sandbox ownership with 0710 permissions for credential roots while descendants remain root-only.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
  participant SnapshotE2E as Snapshot E2E test
  participant SourceSandbox as Source sandbox
  participant Onboarding as Fresh onboarding
  participant SnapshotRestore as Snapshot restore
  SnapshotE2E->>SourceSandbox: Destroy source sandbox
  SnapshotE2E->>Onboarding: Perform fresh non-interactive onboarding
  Onboarding-->>SnapshotE2E: Return replacement workspace
  SnapshotE2E->>SnapshotRestore: Restore timestamped snapshot
  SnapshotRestore-->>SnapshotE2E: Recover marker, USER.md, and SOUL.md

Loading

Suggested labels: area: sandbox

Suggested reviewers: aasthajh

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: clarifying OpenClaw workspace persistence and snapshot behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/issue-8136

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-8245.docs.buildwithfern.com/nemoclaw

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 0bc10a0 in the codex/issue-8136 branch remains at 96%, unchanged from commit 62b4f28 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 0bc10a0 in the codex/issue-8136 branch remains at 81%, unchanged from commit 62b4f28 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 62b4f28	codex/issue-8136 0bc10a0	+/-
src/lib/platform.ts	89%	84%	-5%
src/lib/shields/index.ts	74%	73%	-1%
src/lib/messagi...nnels/policy.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/tunnel/services.ts	80%	80%	0%
src/lib/credentials/store.ts	55%	56%	+1%

---

_{Updated August 05, 2026 07:41 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / low confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: PR review advisor skipped: OpenShell inference configuration failed or the advisor credential is unavailable

Model lanes

• GPT-5.6 Terra (primary): Skipped
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: snapshot-commands

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[apurvvkumaria]

Resolved the failing snapshot E2E and refreshed the branch from current main.

Failure classification: PR-related expectation drift, not infrastructure or test flakiness. The confidentiality-root contract introduced by #7603 keeps every present credential root at root:sandbox 0710 so the sandbox group can traverse it, while every descendant remains root:root without group or world permission bits. The failed E2E artifact reported the intended root posture, but this test still expected root:root 0700 before and after backup.

The branch now:

• expects root:sandbox 0710 for the credential root at both validation points;
• continues to require root:root 0600 for the credential file;
• documents the same root-versus-descendant boundary;
• preserves the existing redaction, unreadability, snapshot-scope, and cleanup assertions.

Validation completed locally: PR-scoped hooks, CLI type checking, semantic E2E phase coverage (117 tests across 74 files), project membership, test-title and size checks, source-shape checks, documentation build and route validation, and the isolated 34-test support regression. GitHub reports all newly pushed commits as Verified. The refreshed CI and E2E gates are now running.

[apurvvkumaria]

CI classification update: the primary advisor retry failed before analysis because the upstream inference service rejected the workflow credential with HTTP 403. The second-opinion lane completed successfully with zero blockers, warnings, or suggestions, and the published advisor result requires no follow-up. This is an advisor-infrastructure failure, not a failure caused by this PR. All required checks currently pass except the selected snapshot E2E scenario, which is still running; I will continue monitoring it.

[apurvvkumaria]

Settled merge-gate status for the current branch revision:

• Required repository CI, CodeQL, documentation review, DCO, commit verification, and the selected snapshot E2E gate pass.
• CodeRabbit has no actionable findings, and the completed Nemotron advisor lane reported zero blockers, warnings, or suggestions.
• The Terra advisor failure is external to this change: its first attempt ended inside advisor analysis, and the single retry failed while configuring the external inference service. No further transient rerun is warranted.
• There are no unresolved review threads.

The remaining merge blocker is independent approval: GitHub reports REVIEW_REQUIRED, and the PR author cannot self-approve. I have not added or re-requested any reviewer; repository-owned routing should supply that review.