test(shields): cover retained descriptor after hash repair

[RUSHcitizen]

Summary

Adds regression coverage proving that an absent-hash lock replaces openclaw.json before sealing, so a descriptor opened before the lock cannot mutate the canonical config afterward. The production repair and broader recovery coverage already merged in #7467; this conflict resolution narrows #7396 to the remaining security invariant identified by automated review.

Related Issue

Follow-up coverage for #7382. The implementation merged in #7467.

Changes

• Opens openclaw.json for writing before removing .config-hash.
• Locks the config, then writes through the retained descriptor.
• Verifies the canonical config and regenerated hash remain unchanged on fresh sealed inodes.

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: Test-only hardening for an existing documented repair; no user-visible behavior or interface changes.
• 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: NemoClaw nine-category security review found no findings; the test-only diff strengthens descriptor/TOCTOU coverage without changing production behavior.
• 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: origin/main...792ac3b581eca45d2c69d491bb2f99fd1e71e2b3 changes only test/openclaw-config-guard-absent-hash.test.ts; existing docs already describe fresh sealed config inodes and absent-hash synthesis. The focused suite passes 11/11, the combined guard suites pass 55/55, and Biome, diff check, pre-commit, commit-msg, and pre-push pass.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable
• 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 check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — vitest run --project integration test/openclaw-config-guard.test.ts test/openclaw-config-guard-absent-hash.test.ts: 55/55 passed; the descriptor-safe follow-up passes its focused suite 11/11.
• Applicable broad gate passed — not applicable to this one-test security regression addition.
• 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: Atharv Kumaria kumariaaatharv@gmail.com
Signed-off-by: Prekshi Vyas prekshiv@nvidia.com

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

📝 Walkthrough

Walkthrough

The fail-closed lock path now reconstructs the canonical configuration pair when possible, validates it, and otherwise severs canonical entries. A new Vitest integration suite exercises missing-hash recovery, idempotence, symlink rejection, permissions, and cleanup.

Changes

Fail-closed lock recovery

Layer / File(s)	Summary
Canonical pair recovery and fallback severing scripts/openclaw-config-guard.py	The guard rebuilds openclaw.json and .config-hash from freshly captured bytes, validates the rebuilt JSON5 configuration, and falls back to rejected markers when capture fails.
Sandboxed lock behavior validation test/openclaw-config-guard-fail-closed-lock.test.ts	Integration tests run the guard in controlled fixtures and verify hash reconstruction, read-only modes, idempotent locking, symlink handling, and rejected markers.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Guard as _force_fail_closed_lock
  participant Filesystem
  participant Validator as JSON5 runtime validation
  Guard->>Filesystem: Capture openclaw.json
  Guard->>Filesystem: Replace openclaw.json and .config-hash
  Filesystem-->>Guard: Return rebuilt canonical pair
  Guard->>Validator: Validate rebuilt openclaw.json
  Guard->>Filesystem: Rename canonical paths to rejected markers if capture fails

Loading

Suggested labels: area: security

🚥 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 is relevant and specific to the new fail-closed lock behavior and its test coverage, though it emphasizes tests more than the code fix.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

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 match; 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: None

2 optional E2E recommendations

• shields-config
• security-posture

Workflow run details

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

[wscurran]

✨ Thanks for the fix. This preserves openclaw.json when it passes its own identity contract, avoiding the destructive rollback when only .config-hash is missing. Maintainers will review the sandbox shields logic and security implications.

---

Related open issues:

• #7382 [Ubuntu 26.04][WSL2][DGX Spark][Sandbox] shields up/down crash with a raw Node traceback and the rollback deletes openclaw.json when .config-hash is missing
• #7395 fix(cli): exit shields commands cleanly on deferred shields failure

---

Related open PRs:

• #7395 fix(cli): exit shields commands cleanly on deferred shields failure

---

Related open issues:

• #7382 [Ubuntu 26.04][WSL2][DGX Spark][Sandbox] shields up/down crash with a raw Node traceback and the rollback deletes openclaw.json when .config-hash is missing

[prekshivyas]

Reviewed final test-only salvage at 792ac3b. The production fix was superseded by #7467; this PR now preserves only the retained writable-descriptor regression coverage. Focused tests pass 11/11, combined guard suites pass 55/55, all 41 current checks are green, the documentation review is no-docs-needed, DCO is present, and all commits are verified. Security review: PASS for secrets, input validation, authorization, dependencies, error handling/logging, cryptography/data protection, configuration, security testing, and holistic system security. No actionable findings remain.