fix(state): allow locked OpenClaw peer links

[apurvvkumaria]

Summary

Current OpenClaw messaging extensions can link their OpenClaw peer dependency to the locked runtime package path. Backup and Shields audits treated that exact image-owned link as unsafe, so the channels stop/start E2E failed before backup even though the link came from the shipped image. This change accepts only the exact legacy and current image package targets while arbitrary targets and wrong source paths still fail closed.

Related Issue

Part of #7140. Unblocks the OpenClaw channels stop/start coverage in #7580.

Changes

• Keep the TypeScript backup/extraction policy and privileged Python state guard on the same two-target contract.
• Accept extension peer links only at extensions/<safe-id>/node_modules/openclaw and only when they target the legacy global package or current locked runtime package.
• Cover pre-backup audit, post-extraction audit, Shields transitions, current-runtime sibling tampering, and wrong-source rejection.

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: this restores the existing documented backup/rebuild behavior; the internal image path and narrow audit exception are not user-facing configuration.
• 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: an independent Codex security review passed after verifying that the TypeScript and Python guards share the exact two-target allowlist and retain path-shape, state-root, sibling-target, and wrong-source rejection.
• 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: no-docs-needed
• Evidence: docs/manage-sandboxes/backup-restore.mdx, docs/manage-sandboxes/set-up-whatsapp.mdx, and docs/reference/host-files-and-state.mdx already describe the restored durable-state behavior and unsafe-link rejection. No documentation files changed.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

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, including the source-shape and 1,500-line test-file budget gates
• Targeted behavior tests pass for the current change set — 24 CLI policy tests, 82 backup/extraction tests, and 5 focused guard rejection tests passed; an offline Linux container also passed both trusted targets through preflight/lock/unlock and rejected sibling/wrong-source cases.
• Applicable broad gate passed — not applicable to this narrow exact-target compatibility fix; npm run build:cli, npm run typecheck:cli, source-shape, title-style, project-overlap, and full changed-file hooks passed.
• 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)
• 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

• Bug Fixes

  • Improved handling of OpenClaw extension links across supported installation locations.
  • Preserved valid extension links during state backups, restores, and transitions.
  • Continued rejecting untrusted or tampered links outside approved package paths.

• Tests

  • Expanded coverage for multiple extensions and trusted runtime package locations.
  • Added regression checks for archive extraction, snapshots, and state-directory transitions.

[coderabbitai]

📝 Walkthrough

Walkthrough

OpenClaw symlink validation now accepts multiple image-owned package paths instead of one global path. Runtime, archive, state-transition, and snapshot tests add coverage for the WhatsApp target and continue rejecting disallowed source or tampered links.

Changes

OpenClaw symlink policy

Layer / File(s)	Summary
Expand OpenClaw image target validation src/lib/state/openclaw-managed-extensions.ts, scripts/state-dir-guard.py	Both validators use a whitelist containing the legacy global package path and the runtime image package path.
Cover allowed and rejected runtime links src/lib/state/openclaw-managed-extensions.test.ts, test/state-dir-guard.test.ts, test/security-sandbox-tar-traversal.test.ts	Tests cover WhatsApp runtime links, exact target preservation, source-path restrictions, and tampered targets.
Update snapshot audit fixtures test/snapshot.test.ts	The pre-backup audit fixture includes the WhatsApp peer-link entry.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: ericksoa, laitingsheng

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: allowing locked OpenClaw peer links in state validation.

✨ 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/7140-openclaw-whatsapp-backup-symlink

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 702917d in the codex/7140-openclaw-... branch remains at 96%, unchanged from commit df433c5 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 702917d in the codex/7140-openclaw-... branch remains at 81%, unchanged from commit df433c5 in the main branch.

Show a code coverage summary of the most impacted files.

File	main df433c5	codex/7140-openclaw-... 702917d	+/-
src/lib/platform.ts	89%	84%	-5%
src/lib/messagi...nnels/policy.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	88%	88%	0%

---

_{Updated July 26, 2026 12:13 UTC}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

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

Recommended E2E: onboard-repair, onboard-resume

1 optional E2E recommendation

• state-backup-restore

Workflow run details

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

[cv]

Approved exact head 702917d after product-scope, correctness, manual nine-category security, compliance, documentation, collision, 133 focused tests, refreshed build/typecheck, fresh CI/advisors, and selected onboard-repair/onboard-resume E2E review. Canonical gate passed with all 52 current checks green.