feat(state): add key-level restore ownership to agent manifests#6445
Merged
Conversation
Agent manifests can now declare per-key restore ownership for mixed-ownership state files. A key-allowlist merge restores only typed, bounded, or enum user keys and requires the declared fresh tables and headers; a named openclaw-config strategy covers OpenClaw's deep merge. Ownership is validated at manifest load time and read from the live manifest during restore, so snapshot format is unchanged and existing manifests keep whole-file behavior until they opt in. The generic restore engine now dispatches on the manifest instead of agent-specific conditionals. Migrates Deep Agents Code onto the declarative schema and removes its local config-restore workaround, and re-homes OpenClaw's merge behind the manifest marker. Resolves #6334 Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds manifest-declared state-file restore ownership, strict validation, key-allowlisted TOML merging, atomic replacement, and target-manifest-driven sandbox restore routing. Rebuild and snapshot flows propagate target-agent and custom-image context with expanded restore and safety tests. ChangesManifest contracts and validation
Key-allowlist merge engine
Manifest-driven sandbox restore
Rebuild and creation restore wiring
Snapshot restore and reconciliation coverage
Estimated code review effort: 5 (Critical) | ~120 minutes Possibly related PRs
Suggested labels: Suggested reviewers: Sequence Diagram(s)sequenceDiagram
participant SnapshotRestore
participant SandboxRestore
participant AgentManifest
participant StateFileRestore
participant RemoteSandbox
SnapshotRestore->>SandboxRestore: restore backup for target sandbox
SandboxRestore->>AgentManifest: load target state-file declarations
AgentManifest-->>SandboxRestore: validated ownership and strategy
SandboxRestore->>StateFileRestore: restore each declared state file
StateFileRestore->>RemoteSandbox: merge or atomically replace state file
RemoteSandbox-->>StateFileRestore: restore result
StateFileRestore-->>SandboxRestore: per-file success or failure
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Contributor
Code Coverage OverviewLanguages: TypeScript TypeScript / code-coverage/pluginThe overall coverage remains at 96%, unchanged from the branch. TypeScript / code-coverage/cliThe overall coverage in the branch remains at 79%, unchanged from the branch. Show a code coverage summary of the most impacted files.
Updated |
Contributor
PR Review Advisor (Nemotron Ultra) — Changes requestedMerge posture: Do not merge yet Action checklist
Findings index
🚨 Required before mergeAddress these before merging unless a maintainer explicitly overrides the advisor with rationale.
|
Contributor
PR Review Advisor — No blocking findingsMerge posture: No blocking advisor findings This is an automated review. Required findings need action before merge. Warnings and optional suggestions do not require a response or follow-up. A human maintainer makes the final merge decision. |
Contributor
E2E Advisor RecommendationRequired E2E: Dispatch hint: Full advisor summaryE2E Recommendation AdvisorBase: Required E2E
Optional E2E
New E2E recommendations
Dispatch hint
|
Contributor
E2E Target RecommendationRequired E2E targets: Dispatch required E2E targets:
Full E2E target advisor summaryE2E Target AdvisorBase: Required E2E targets
Optional E2E targets
Relevant changed files
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (3)
src/lib/state/state-file-key-merge.test.ts (2)
300-321: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy liftPrefer behavioral coverage for the generated restore command.
This test locks on command substrings and embedded source details, but does not prove the command safely stages, replaces, or rejects unsafe paths. Consider making the Python executable injectable for tests and running the generated command against temp files.
As per path instructions, tests should prefer observable outcomes through the public boundary over source-text assertions.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/lib/state/state-file-key-merge.test.ts` around lines 300 - 321, The test for buildKeyAllowlistMergeRestoreCommand is too implementation-focused, since it asserts command substrings and embedded source text instead of observable restore behavior. Update the coverage to exercise the public boundary by making the Python executable used by buildKeyAllowlistMergeRestoreCommand injectable for tests, then run the generated restore command against temp files to verify it stages, replaces, and rejects unsafe paths correctly. Keep the assertions centered on the outcomes of buildKeyAllowlistMergeRestoreCommand rather than checking internal command fragments or KEY_ALLOWLIST_MERGE_PYTHON source details.Source: Path instructions
21-50: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy liftAvoid replacing the TOML boundary with JSON-backed fakes.
The wrapper executes the merge algorithm, but not production TOML parsing/serialization. Use real TOML fixtures with the actual
tomllib/tomli_wpath where possible, so malformed TOML, TOML numeric forms, and emitted TOML are covered.As per path instructions, tests should prefer observable behavior and flag broad mocks that bypass the behavior under test.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/lib/state/state-file-key-merge.test.ts` around lines 21 - 50, The test wrapper currently fakes tomllib and tomli_w with JSON-backed modules, which bypasses the real TOML behavior under test. Update the state-file merge tests in state-file-key-merge.test.ts to use real TOML fixtures and the actual tomllib/tomli_w path where possible, so the merge logic is exercised against genuine TOML parsing, malformed TOML, numeric forms, and emitted TOML; keep the wrapper focused on running the script rather than replacing serialization/parsing semantics.Source: Path instructions
src/lib/agent/definition-types.ts (1)
46-51: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winEncode restore ownership as a discriminated union.
The exported interface currently permits invalid combinations like
merge: "openclaw-config"withuserKeys, ormerge: "key-allowlist"withoutuserKeys. Encoding the parser invariants in the type keeps downstream restore dispatch harder to misuse.Suggested type tightening
-export interface StateFileRestoreOwnership { - merge: StateFileRestoreMerge; - userKeys?: readonly StateFileUserKey[]; - requireFreshTables?: readonly string[]; - requireFreshHeaders?: readonly StateFileFreshHeader[]; -} +export type StateFileRestoreOwnership = + | { + merge: "openclaw-config"; + userKeys?: never; + requireFreshTables?: never; + requireFreshHeaders?: never; + } + | { + merge: "key-allowlist"; + userKeys: readonly StateFileUserKey[]; + requireFreshTables?: readonly string[]; + requireFreshHeaders?: readonly StateFileFreshHeader[]; + };🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/lib/agent/definition-types.ts` around lines 46 - 51, Update StateFileRestoreOwnership in definition-types.ts to a discriminated union keyed by merge so the parser invariants are encoded in the type. Keep the existing StateFileRestoreMerge symbol as the discriminator, but split the current interface into branch types so the key-allowlist shape requires userKeys and the openclaw-config shape forbids it, while preserving requireFreshTables and requireFreshHeaders only where valid. Make sure any downstream references to StateFileRestoreOwnership continue to compile against the new union.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/lib/agent/defs.test.ts`:
- Around line 529-734: The new behavior-oriented test titles in defs.test.ts are
missing the required local issue suffix; update each added it(...) description
to end with the linked issue reference in the final "(`#1234`)" form. Keep the
existing test intent the same, and only adjust the titles for the affected
restore-related cases so they follow the project’s test naming convention.
In `@src/lib/agent/manifest-readers.ts`:
- Around line 140-210: The `readStateFileUserKey` parser currently accepts
`values`, `min/max`, and `max_length` but silently ignores any other properties
on `raw`, which lets typos in `restore` and `user_keys[]` records pass
unnoticed. Add a fail-closed unknown-field check in `readStateFileUserKey` (and
the related restore-schema reader referenced by this path) by validating the
allowed keys for each `type` and throwing on any extra property such as
misspelled `requireFreshTables` or `maxLength`, so only explicitly supported
fields are accepted.
In `@src/lib/state/sandbox.ts`:
- Around line 876-880: The restore flow in sandbox.ts is failing open when
`loadAgent()` throws, because the `agent` load in the ownership restore path
swallows every error and returns an empty ownership map. Update the restore
logic around `loadAgent`, `restore ownership`, and the downstream restore
decision near the wholesale-restore fallback so that manifest load/validation
failures are treated as state-file restore failures, not as unmanaged restores;
this should fail closed and prevent managed files from bypassing the key
allowlist validation.
In `@src/lib/state/state-file-key-merge.ts`:
- Around line 108-136: The validation helper value_allowed currently lets
non-finite numbers through and uses loose equality for enum matching. Update
value_allowed in state-file-key-merge so the number branch explicitly rejects
NaN and infinities before applying min/max checks, and make the enum branch
require strict membership against the allowed values without allowing
boolean/integer coercion. Keep the fix localized to value_allowed and any
restore path that depends on it.
- Around line 278-280: Reject unsafe state-file paths before building the
restore command in state-file-key-merge logic. In the code that composes
`destination` from `normalizedDir` and `spec.path`, add a local `path.posix`
validation or parsing-time rejection so absolute paths and any `..` segments are
refused before concatenation. Keep the fix near the restore-command assembly
that uses `shellQuote`, and ensure `stateFileKeyMergeSpec`/`state_files`
handling cannot resolve outside the intended `dir`.
---
Nitpick comments:
In `@src/lib/agent/definition-types.ts`:
- Around line 46-51: Update StateFileRestoreOwnership in definition-types.ts to
a discriminated union keyed by merge so the parser invariants are encoded in the
type. Keep the existing StateFileRestoreMerge symbol as the discriminator, but
split the current interface into branch types so the key-allowlist shape
requires userKeys and the openclaw-config shape forbids it, while preserving
requireFreshTables and requireFreshHeaders only where valid. Make sure any
downstream references to StateFileRestoreOwnership continue to compile against
the new union.
In `@src/lib/state/state-file-key-merge.test.ts`:
- Around line 300-321: The test for buildKeyAllowlistMergeRestoreCommand is too
implementation-focused, since it asserts command substrings and embedded source
text instead of observable restore behavior. Update the coverage to exercise the
public boundary by making the Python executable used by
buildKeyAllowlistMergeRestoreCommand injectable for tests, then run the
generated restore command against temp files to verify it stages, replaces, and
rejects unsafe paths correctly. Keep the assertions centered on the outcomes of
buildKeyAllowlistMergeRestoreCommand rather than checking internal command
fragments or KEY_ALLOWLIST_MERGE_PYTHON source details.
- Around line 21-50: The test wrapper currently fakes tomllib and tomli_w with
JSON-backed modules, which bypasses the real TOML behavior under test. Update
the state-file merge tests in state-file-key-merge.test.ts to use real TOML
fixtures and the actual tomllib/tomli_w path where possible, so the merge logic
is exercised against genuine TOML parsing, malformed TOML, numeric forms, and
emitted TOML; keep the wrapper focused on running the script rather than
replacing serialization/parsing semantics.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 120f5162-3224-49e2-8cef-4df049d98759
📒 Files selected for processing (16)
agents/langchain-deepagents-code/manifest.yamlagents/openclaw/manifest.yamlsrc/lib/agent/definition-types.tssrc/lib/agent/defs.test.tssrc/lib/agent/defs.tssrc/lib/agent/manifest-readers.tssrc/lib/onboard/created-sandbox-finalization.test.tssrc/lib/onboard/created-sandbox-finalization.tssrc/lib/state/dcode-config-restore-input.test.tssrc/lib/state/dcode-config-restore-input.tssrc/lib/state/openclaw-config-restore-input.test.tssrc/lib/state/openclaw-config-restore-input.tssrc/lib/state/sandbox.tssrc/lib/state/state-file-key-merge.test.tssrc/lib/state/state-file-key-merge.tssrc/lib/state/state-file-restore-policy.ts
💤 Files with no reviewable changes (4)
- src/lib/state/state-file-restore-policy.ts
- src/lib/state/dcode-config-restore-input.test.ts
- src/lib/state/dcode-config-restore-input.ts
- src/lib/state/openclaw-config-restore-input.ts
…uild and snapshot restore Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
…s own module Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
…st merge Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/lib/actions/sandbox/snapshot-restore.test.ts`:
- Around line 446-490: Add test coverage for the positive
applyManagedStateFileRestore path in the snapshot restore flow. In this
`it.each` case inside `runSandboxSnapshot`, assert the `restoreSandboxStateMock`
call includes `applyManagedStateFileRestore: true` when the source sandbox uses
the DCode agent (`langchain-deepagents-code`) and the clone target matches the
no-Dockerfile scenario that should flip `usesManagedDcodeIdentity` to true.
Update the existing restore assertions in this test block to verify the full
options passed to `restoreSandboxStateMock`, not just the `false` branch.
In `@src/lib/agent/state-file-restore-reader.test.ts`:
- Around line 20-27: The cleanup in afterEach for tempAgentDirs currently
introduces an if guard, which violates the test-file guardrail. Update the
afterEach logic in state-file-restore-reader.test.ts to remove the conditional
by restructuring the loop so it only processes defined entries from
tempAgentDirs, while preserving the recursive fs.rmSync cleanup behavior. Use
the existing afterEach and tempAgentDirs symbols to locate and adjust the
teardown code.
In `@src/lib/agent/state-file-restore-reader.ts`:
- Around line 182-212: In readStateFileFreshHeaders, add the same strict object
validation used elsewhere in the manifest parser so require_fresh_headers
entries reject unknown keys before reading fields. Also stop defaulting match
via readString(raw, "match") ?? "exact"; instead require match to be either
absent or an explicit string value, and throw if it is present but not a string
or not one of the allowed values. Keep the existing array and value checks, but
make the object path consistent with restore/user_keys validation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: eda4fae1-da0b-4011-880d-6b8bf196262c
📒 Files selected for processing (18)
agents/langchain-deepagents-code/manifest.yamlsrc/lib/actions/sandbox/rebuild-dcode-recovery.test.tssrc/lib/actions/sandbox/rebuild-local-provider-recreate.test.tssrc/lib/actions/sandbox/rebuild-pipeline.tssrc/lib/actions/sandbox/rebuild-prepared-recovery.test.tssrc/lib/actions/sandbox/rebuild-restore-phase.test.tssrc/lib/actions/sandbox/rebuild-restore-phase.tssrc/lib/actions/sandbox/snapshot-restore.test.tssrc/lib/actions/sandbox/snapshot.test.tssrc/lib/actions/sandbox/snapshot.tssrc/lib/agent/defs.test.tssrc/lib/agent/manifest-readers.tssrc/lib/agent/state-file-restore-reader.test.tssrc/lib/agent/state-file-restore-reader.tssrc/lib/state/sandbox.tssrc/lib/state/state-file-key-merge.tstest/helpers/rebuild-flow-lifecycle-cases.tstest/helpers/rebuild-flow-recovery-cases.ts
💤 Files with no reviewable changes (1)
- src/lib/agent/defs.test.ts
✅ Files skipped from review due to trivial changes (1)
- src/lib/actions/sandbox/rebuild-prepared-recovery.test.ts
🚧 Files skipped from review as they are similar to previous changes (3)
- agents/langchain-deepagents-code/manifest.yaml
- src/lib/state/state-file-key-merge.ts
- src/lib/state/sandbox.ts
Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
src/lib/onboard/created-sandbox-finalization.test.ts (1)
218-234: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winConsider extracting a shared default-deps builder for these tests.
Several tests in this file construct near-identical
depsobjects (discoverFreshOpenClawImagePluginInstalls,restoreRecreatedSandboxState,getDcodeSelectionDrift,register,note,error,exitProcess), differing only in a couple of overrides. A small factory (e.g.,makeFinalizationDeps(overrides)) would reduce duplication and make future flag additions (likeapplyManagedStateFileRestore) easier to thread consistently across tests.Also applies to: 359-396, 440-476, 478-527, 529-575
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/lib/onboard/created-sandbox-finalization.test.ts` around lines 218 - 234, Several tests in created-sandbox-finalization.test.ts are duplicating almost the same deps setup, so extract a shared default-deps factory such as makeFinalizationDeps(overrides) and use it in the affected test cases. Move the common pieces from the existing deps objects used around restoreRecreatedSandboxState, discoverFreshOpenClawImagePluginInstalls, getDcodeSelectionDrift, register, note, error, and exitProcess into that helper, then pass only per-test overrides so new flags like applyManagedStateFileRestore stay consistent everywhere.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@src/lib/onboard/created-sandbox-finalization.test.ts`:
- Around line 218-234: Several tests in created-sandbox-finalization.test.ts are
duplicating almost the same deps setup, so extract a shared default-deps factory
such as makeFinalizationDeps(overrides) and use it in the affected test cases.
Move the common pieces from the existing deps objects used around
restoreRecreatedSandboxState, discoverFreshOpenClawImagePluginInstalls,
getDcodeSelectionDrift, register, note, error, and exitProcess into that helper,
then pass only per-test overrides so new flags like applyManagedStateFileRestore
stay consistent everywhere.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 61b00ddf-1a65-4c7e-905d-8112817466fe
📒 Files selected for processing (16)
agents/langchain-deepagents-code/manifest.yamlsrc/lib/actions/sandbox/rebuild-dcode-recovery.test.tssrc/lib/actions/sandbox/rebuild-local-provider-recreate.test.tssrc/lib/actions/sandbox/rebuild-pipeline.tssrc/lib/actions/sandbox/rebuild-prepared-recovery.test.tssrc/lib/actions/sandbox/rebuild-restore-phase.test.tssrc/lib/actions/sandbox/rebuild-restore-phase.tssrc/lib/actions/sandbox/snapshot-restore.test.tssrc/lib/actions/sandbox/snapshot.tssrc/lib/agent/defs.test.tssrc/lib/agent/state-file-restore-reader.test.tssrc/lib/onboard/created-sandbox-finalization.test.tssrc/lib/onboard/created-sandbox-finalization.tssrc/lib/state/openclaw-config-restore-input.test.tssrc/lib/state/openclaw-config-restore-input.tssrc/lib/state/sandbox.ts
💤 Files with no reviewable changes (3)
- src/lib/state/openclaw-config-restore-input.test.ts
- src/lib/state/openclaw-config-restore-input.ts
- src/lib/state/sandbox.ts
✅ Files skipped from review due to trivial changes (2)
- src/lib/actions/sandbox/rebuild-dcode-recovery.test.ts
- src/lib/actions/sandbox/rebuild-prepared-recovery.test.ts
🚧 Files skipped from review as they are similar to previous changes (10)
- src/lib/actions/sandbox/rebuild-pipeline.ts
- agents/langchain-deepagents-code/manifest.yaml
- src/lib/actions/sandbox/rebuild-local-provider-recreate.test.ts
- src/lib/actions/sandbox/snapshot.ts
- src/lib/actions/sandbox/rebuild-restore-phase.ts
- src/lib/agent/defs.test.ts
- src/lib/onboard/created-sandbox-finalization.ts
- src/lib/agent/state-file-restore-reader.test.ts
- src/lib/actions/sandbox/rebuild-restore-phase.test.ts
- src/lib/actions/sandbox/snapshot-restore.test.ts
Merged
21 tasks
… match Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
…d config Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
…n snapshot restore Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
…hip lookup Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
21 tasks
… staged write Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
… and replace Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
Contributor
E2E Target Results — ❌ Some jobs failedRun: 29129384871
|
Contributor
E2E Target Results — ❌ Some jobs failedRun: 29129667043
|
Contributor
E2E Target Results — ❌ Some jobs failedRun: 29130111510
|
…el-state-ownership
Contributor
E2E Target Results — ❌ Some jobs failedRun: 29140856250
|
Contributor
E2E Target Results — ❌ Some jobs failedRun: 29143011000
|
Contributor
E2E Target Results — ❌ Some jobs failedRun: 29143776167
|
cv
approved these changes
Jul 11, 2026
cv
left a comment
cv
left a comment
Collaborator
There was a problem hiding this comment.
Current-head re-review passed at b2725d5. The prior HOLD items are resolved: current main is integrated, real TOML and filesystem race/symlink/inode-swap paths are covered, managed ownership and the custom-image trust exception are explicit and documented, required exact-head E2Es passed, all commits are Verified, and the formal GPT gate returned merge_as_is with no findings. Nemotron’s transient retry-convergence scenario is worthwhile follow-up coverage rather than evidence of a product defect; the custom-image boundary is intentional and tested. The lone cancel-superseded failure is a run-pagination tooling error, not a code/test failure.
Contributor
E2E Target Results — ✅ All requested tests passedRun: 29173513546
|
cv
dismissed
cjagwani’s stale review
Dismissed after current-commit re-review: main is synced, key-level ownership and safe TOML merge/race handling are covered, documentation is complete, ChatGPT auth state is now excluded from managed snapshots, all 51 ordinary checks and trusted advisors are green, and the full ten-target live matrix passed.
21 tasks
cv
added a commit
that referenced
this pull request
Jul 12, 2026
<!-- markdownlint-disable MD041 --> ## Summary Release-prep documentation for v0.0.81 now summarizes user-facing changes merged since v0.0.80. It also closes the Hermes dashboard-profile backup gap and distinguishes direct blueprint-runner actions from public host CLI commands. ## Changes - Add the `v0.0.81` section to `docs/about/release-notes.mdx` with links to the detailed user guides. - Document that Hermes rebuilds preserve `.hermes/dashboard-home/`, including Dashboard `MEMORY.md` and `USER.md`. - Update Hermes manual backup and restore examples to transfer those two profile files without copying generated configuration or the secret-bearing dashboard `.env`. - Explain the new per-item backup failure causes. - Clarify that migration snapshot retention fragments are direct-runner arguments and are not exposed by the host `nemoclaw` CLI. ### Source summary - #6445 -> `docs/about/release-notes.mdx`, `docs/manage-sandboxes/backup-restore.mdx`, and `docs/manage-sandboxes/workspace-files.mdx`: Summarize manifest-owned key-level restore and current-config authority. - #6617 -> `docs/about/release-notes.mdx` and `docs/manage-sandboxes/backup-restore.mdx`: Record the fail-closed `/proc` fallback used to verify an idle Deep Agents runtime before snapshot creation. - #6685 -> `docs/about/release-notes.mdx`, `docs/manage-sandboxes/backup-restore.mdx`, and `docs/manage-sandboxes/workspace-files.mdx`: Document Hermes Web Dashboard profile persistence and safe manual transfer. - #6649 -> `docs/about/release-notes.mdx`: Summarize host-validated loopback compatible-endpoint routing through the sandbox gateway. - #6643 -> `docs/about/release-notes.mdx`: Summarize automatic `max_completion_tokens` handling for GPT-5 and o-series models. - #6661 -> `docs/about/release-notes.mdx`: Summarize bounded connection reuse for eligible provider-validation probes. - #6704 -> `docs/about/release-notes.mdx`: Record that direct blueprint apply stops instead of persisting incomplete state after provider or inference setup fails. - #6677 -> `docs/about/release-notes.mdx`: Summarize transactional recovery for legacy Docker containers whose managed supervisor disappeared after restart. - #6625 -> `docs/about/release-notes.mdx`: Record Hermes managed-startup persistence across direct Docker restarts. - #6597 -> `docs/about/release-notes.mdx`: Record final-sandbox gateway cleanup on macOS. - #6680 -> `docs/about/release-notes.mdx`: Summarize managed Deep Agents first-run and process-tree cleanup improvements. - #6647 -> `docs/about/release-notes.mdx`: Record fail-closed validation for the managed Deep Agents fetch CA bundle. - #6645 -> `docs/about/release-notes.mdx`: Summarize WhatsApp loopback pairing and trusted npm plugin provenance. - #6673 -> `docs/about/release-notes.mdx` and `docs/manage-sandboxes/backup-restore.mdx`: Document stopped-sandbox backup remediation. - #6631 -> `docs/about/release-notes.mdx` and `docs/manage-sandboxes/backup-restore.mdx`: Document per-item backup failure causes. - #6620 -> `docs/about/release-notes.mdx`: Record the created-but-not-ready sandbox lifecycle receipt. - #6664 -> `docs/about/release-notes.mdx`: Record prompt-aware onboarding progress output. - #6598 -> `docs/about/release-notes.mdx`: Summarize stale replay-result invalidation during resumed onboarding. - #6593 -> `docs/about/release-notes.mdx`: Summarize contextual OpenClaw audit findings for managed dashboard compatibility settings. - #6650 -> `docs/about/release-notes.mdx`: Record redaction of token-shaped URL query values. - #6638 -> `docs/about/release-notes.mdx`: Record the exact-path MCP `DELETE` policy recipe for session termination. - #5453 -> `docs/reference/host-files-and-state.mdx`: Clarify that snapshot retention actions belong to direct runner integrations and are not standalone host CLI commands. ### Skipped from docs-skip - #6633 matched the `openclaw-sandbox-permissive.yaml` path in `docs/.docs-skip` and produced no documentation in this update. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [ ] Doc only (prose changes, no code sample modifications) - [x] Doc only (includes code sample changes) ## Quality Gates - [ ] Tests added or updated for changed behavior - [ ] Existing tests cover changed behavior — justification: - [x] Tests not applicable — justification: This is a documentation-only release-prep update; behavior is protected by the merged source PRs, and the documentation build validates the changed examples and routes. - [x] 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: - [ ] Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: ## Verification - [x] PR description includes the DCO sign-off declaration and every commit appears as `Verified` in GitHub - [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or `npm run check:diff` passed when hooks were skipped or unavailable - [x] Targeted behavior tests pass for the current change set, or tests are marked not applicable above — tests are not applicable for this documentation-only change; `npm run docs` completed successfully. - [ ] Applicable broad gate passed — `npm test` for broad runtime/test-harness changes; `npm run check` for repo-wide validation/coverage changes — command/result: not run for this documentation-only change. - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) — 0 errors; two existing Fern warnings remain. - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages only) — no new pages. --- Signed-off-by: Carlos Villela <cvillela@nvidia.com> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Added release notes for v0.0.81 covering state preservation, inference setup, sandbox recovery, session setup, pairing, diagnostics, and security policy updates. - Expanded backup and restore guidance to include dashboard profile files and clarify files that must not be copied. - Added dashboard profile persistence details to workspace and rebuild documentation. - Clarified snapshot retention guidance and the distinction between host CLI capabilities and direct runner actions. - Added more detailed backup failure reporting information. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Signed-off-by: Carlos Villela <cvillela@nvidia.com>
Hadar301
pushed a commit
to Hadar301/NemoClaw-OpenShift
that referenced
this pull request
Jul 12, 2026
…IA#6445) <!-- markdownlint-disable MD041 --> ## Summary Agent manifests can now declare key-level restore ownership for mixed-ownership state files. Managed restore preserves only manifest-owned user preferences while the current target manifest remains authoritative for generated configuration. Deep Agents Code is migrated to this schema, and the restore path now fails closed on unsafe manifests, paths, TOML, filesystem races, and target/backup mismatches. ## Related Issue Resolves NVIDIA#6334 ## Changes - Add a strict, discriminated state_files restore schema for key-allowlist and openclaw-config strategies, including canonical relative-path validation and rejection of duplicate or ancestor-overlapping ownership declarations. - Require the current target manifest to authorize the backup agent, config directory, state-file path, strategy, and restore ownership before SSH or filesystem mutation. - Make managed key-level merge the default. Whole-file restore is available only through the explicit allowCustomImageWholeStateFileRestore capability for custom-image restore. - Read bounded backup TOML directly from Python stdin, parse with tomllib, create a private unpredictable O_EXCL stage, traverse parent directories without following symlinks, and revalidate current/stage metadata before atomic replacement. - Preserve all safe leading comments, preserve non-dictionary fresh ancestors instead of clobbering them, and keep fresh managed tables and headers authoritative. - Migrate the Deep Agents Code manifest and remove the agent-specific restore-policy callback. - Document managed key-level restore, target-manifest authority, and the custom-Dockerfile whole-file exception. ## Type of Change - [x] Code change (feature, bug fix, or refactor) - [x] Code change with doc updates - [ ] Doc only (prose changes, no code sample modifications) - [ ] Doc only (includes code sample changes) ## Quality Gates - [x] Tests added or updated for changed behavior - [ ] Existing tests cover changed behavior — justification: - [ ] Tests not applicable — justification: - [x] Docs updated for user-facing behavior changes - [ ] Docs not applicable — justification: - [x] Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging) - [x] Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: maintainer-assisted review of the behavior at dd65850 passed all nine security categories; current head f9e4537 adds only a formatting-only blank-line deletion to satisfy the onboard.ts net-growth guardrail. - [ ] Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: ## Verification - [x] PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub - [x] Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable - [x] Targeted behavior tests pass for the current change set, or tests are marked not applicable above — 175 focused CLI assertions plus 71 affected integration assertions passed; the final phase/contract rerun passed 23/23. npm run typecheck:cli, npm run build:cli, npm run test-size:check, and git diff --check also passed. - [ ] Applicable broad gate passed — not applicable locally; targeted CLI/integration coverage exercised every changed restore path, and repository CI is running on the exact head. - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] npm run docs builds without warnings (doc changes only) — build passed with 0 errors and 2 pre-existing hidden-page warnings - [x] Doc pages follow the style guide (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages only) — no new pages --- Signed-off-by: Tinson Lai <tinsonl@nvidia.com> Signed-off-by: Charan Jagwani <cjagwani@nvidia.com> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added manifest-driven, fine-grained state-file restore rules with typed user key allowlists and “freshness” requirements. * Custom Dockerfile sandboxes can restore whole state files during rebuilds when enabled. * **Bug Fixes** * Snapshot restore now fails closed for unknown, unsafe, stale, or conflicting state data, with stronger atomic replacement safeguards. * **Documentation** * Updated sandbox backup/restore guidance to reflect key-level ownership semantics, allowed preference preservation, and restore failure behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: Tinson Lai <tinsonl@nvidia.com> Signed-off-by: Charan Jagwani <cjagwani@nvidia.com> Signed-off-by: Carlos Villela <cvillela@nvidia.com> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Charan Jagwani <cjagwani@nvidia.com> Co-authored-by: Carlos Villela <cvillela@nvidia.com>
Hadar301
pushed a commit
to Hadar301/NemoClaw-OpenShift
that referenced
this pull request
Jul 12, 2026
<!-- markdownlint-disable MD041 --> ## Summary Release-prep documentation for v0.0.81 now summarizes user-facing changes merged since v0.0.80. It also closes the Hermes dashboard-profile backup gap and distinguishes direct blueprint-runner actions from public host CLI commands. ## Changes - Add the `v0.0.81` section to `docs/about/release-notes.mdx` with links to the detailed user guides. - Document that Hermes rebuilds preserve `.hermes/dashboard-home/`, including Dashboard `MEMORY.md` and `USER.md`. - Update Hermes manual backup and restore examples to transfer those two profile files without copying generated configuration or the secret-bearing dashboard `.env`. - Explain the new per-item backup failure causes. - Clarify that migration snapshot retention fragments are direct-runner arguments and are not exposed by the host `nemoclaw` CLI. ### Source summary - NVIDIA#6445 -> `docs/about/release-notes.mdx`, `docs/manage-sandboxes/backup-restore.mdx`, and `docs/manage-sandboxes/workspace-files.mdx`: Summarize manifest-owned key-level restore and current-config authority. - NVIDIA#6617 -> `docs/about/release-notes.mdx` and `docs/manage-sandboxes/backup-restore.mdx`: Record the fail-closed `/proc` fallback used to verify an idle Deep Agents runtime before snapshot creation. - NVIDIA#6685 -> `docs/about/release-notes.mdx`, `docs/manage-sandboxes/backup-restore.mdx`, and `docs/manage-sandboxes/workspace-files.mdx`: Document Hermes Web Dashboard profile persistence and safe manual transfer. - NVIDIA#6649 -> `docs/about/release-notes.mdx`: Summarize host-validated loopback compatible-endpoint routing through the sandbox gateway. - NVIDIA#6643 -> `docs/about/release-notes.mdx`: Summarize automatic `max_completion_tokens` handling for GPT-5 and o-series models. - NVIDIA#6661 -> `docs/about/release-notes.mdx`: Summarize bounded connection reuse for eligible provider-validation probes. - NVIDIA#6704 -> `docs/about/release-notes.mdx`: Record that direct blueprint apply stops instead of persisting incomplete state after provider or inference setup fails. - NVIDIA#6677 -> `docs/about/release-notes.mdx`: Summarize transactional recovery for legacy Docker containers whose managed supervisor disappeared after restart. - NVIDIA#6625 -> `docs/about/release-notes.mdx`: Record Hermes managed-startup persistence across direct Docker restarts. - NVIDIA#6597 -> `docs/about/release-notes.mdx`: Record final-sandbox gateway cleanup on macOS. - NVIDIA#6680 -> `docs/about/release-notes.mdx`: Summarize managed Deep Agents first-run and process-tree cleanup improvements. - NVIDIA#6647 -> `docs/about/release-notes.mdx`: Record fail-closed validation for the managed Deep Agents fetch CA bundle. - NVIDIA#6645 -> `docs/about/release-notes.mdx`: Summarize WhatsApp loopback pairing and trusted npm plugin provenance. - NVIDIA#6673 -> `docs/about/release-notes.mdx` and `docs/manage-sandboxes/backup-restore.mdx`: Document stopped-sandbox backup remediation. - NVIDIA#6631 -> `docs/about/release-notes.mdx` and `docs/manage-sandboxes/backup-restore.mdx`: Document per-item backup failure causes. - NVIDIA#6620 -> `docs/about/release-notes.mdx`: Record the created-but-not-ready sandbox lifecycle receipt. - NVIDIA#6664 -> `docs/about/release-notes.mdx`: Record prompt-aware onboarding progress output. - NVIDIA#6598 -> `docs/about/release-notes.mdx`: Summarize stale replay-result invalidation during resumed onboarding. - NVIDIA#6593 -> `docs/about/release-notes.mdx`: Summarize contextual OpenClaw audit findings for managed dashboard compatibility settings. - NVIDIA#6650 -> `docs/about/release-notes.mdx`: Record redaction of token-shaped URL query values. - NVIDIA#6638 -> `docs/about/release-notes.mdx`: Record the exact-path MCP `DELETE` policy recipe for session termination. - NVIDIA#5453 -> `docs/reference/host-files-and-state.mdx`: Clarify that snapshot retention actions belong to direct runner integrations and are not standalone host CLI commands. ### Skipped from docs-skip - NVIDIA#6633 matched the `openclaw-sandbox-permissive.yaml` path in `docs/.docs-skip` and produced no documentation in this update. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [ ] Doc only (prose changes, no code sample modifications) - [x] Doc only (includes code sample changes) ## Quality Gates - [ ] Tests added or updated for changed behavior - [ ] Existing tests cover changed behavior — justification: - [x] Tests not applicable — justification: This is a documentation-only release-prep update; behavior is protected by the merged source PRs, and the documentation build validates the changed examples and routes. - [x] 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: - [ ] Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: ## Verification - [x] PR description includes the DCO sign-off declaration and every commit appears as `Verified` in GitHub - [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or `npm run check:diff` passed when hooks were skipped or unavailable - [x] Targeted behavior tests pass for the current change set, or tests are marked not applicable above — tests are not applicable for this documentation-only change; `npm run docs` completed successfully. - [ ] Applicable broad gate passed — `npm test` for broad runtime/test-harness changes; `npm run check` for repo-wide validation/coverage changes — command/result: not run for this documentation-only change. - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) — 0 errors; two existing Fern warnings remain. - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages only) — no new pages. --- Signed-off-by: Carlos Villela <cvillela@nvidia.com> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Added release notes for v0.0.81 covering state preservation, inference setup, sandbox recovery, session setup, pairing, diagnostics, and security policy updates. - Expanded backup and restore guidance to include dashboard profile files and clarify files that must not be copied. - Added dashboard profile persistence details to workspace and rebuild documentation. - Clarified snapshot retention guidance and the distinction between host CLI capabilities and direct runner actions. - Added more detailed backup failure reporting information. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Signed-off-by: Carlos Villela <cvillela@nvidia.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Agent manifests can now declare key-level restore ownership for mixed-ownership state files. Managed restore preserves only manifest-owned user preferences while the current target manifest remains authoritative for generated configuration. Deep Agents Code is migrated to this schema, and the restore path now fails closed on unsafe manifests, paths, TOML, filesystem races, and target/backup mismatches.
Related Issue
Resolves #6334
Changes
Type of Change
Quality Gates
Verification
Signed-off-by: Tinson Lai tinsonl@nvidia.com
Signed-off-by: Charan Jagwani cjagwani@nvidia.com
Summary by CodeRabbit