fix(onboard): honor explicit sandbox recreation (#9318)

<!-- markdownlint-disable MD041 -->
## Summary

Explicit `--recreate-sandbox` requests now bypass a stale saved build or
policy fingerprint during resumed onboarding. Previously, the recovery
path rejected the request while instructing the user to supply the flag
that was already present.

## Related Issue

Fixes #9297

## Changes

- Honor explicit sandbox recreation before comparing saved create-input
fingerprints.
- Add regression coverage for build, policy, and durable create-intent
drift while preserving denial without the flag.

## Type of Change

- [x] 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

- [x] Tests added or updated for changed behavior
- [ ] Existing tests cover changed behavior — justification:
- [ ] Tests not applicable — justification:
- [ ] Docs updated for user-facing behavior changes
- [x] Docs not applicable — justification: Existing command
documentation already covers resumable onboarding and explicit sandbox
recreation. This fix adds no command, flag, default, configuration, or
user-visible text.
- [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:
#9318 (comment)
- [x] Non-success, skipped, or missing CI check accepted by maintainer —
the advisory Nemotron second-opinion lane failed, while the primary
Advisor completed with no blockers, warnings, or suggestions and
recommended merge as-is:
#9318 (comment)

## Documentation Writer Review

- [x] Documentation writer subagent reviewed the completed changes
- Result: `no-docs-needed`
- Evidence: Exact-revision review confirmed that existing command and
recovery documentation already covers resumable onboarding and explicit
sandbox recreation. This fix makes the documented `--recreate-sandbox`
recovery instruction work after saved build, policy, or durable create
inputs drift; it adds no command, flag, default, configuration, or
user-visible text. `git diff --check` passed; exact-revision CI and
automated review passed apart from the accepted advisory second-opinion
failure.
- Agent: Codex
<!-- docs-review-head-sha: c797ec9 -->
<!-- docs-review-agents-blob-sha: b9fb6a9 -->

## DGX Station Hardware Evidence

- [ ] Tested on DGX Station
- Tested commit:
- Station profile/scenario:
- Result:
- Supporting evidence:

## Verification

- [x] PR description includes a `Signed-off-by:` line and every commit
appears as `Verified` in GitHub
- [x] 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
- [x] Targeted behavior tests pass for the current change set, or tests
are marked not applicable above — command/result or justification: `npx
vitest run --project cli
src/lib/onboard/machine/handlers/sandbox-checkpoint-crash-recovery.test.ts`
passed 42/42; `npx vitest run --project cli
src/lib/onboard/machine/handlers/sandbox-recreate-journal.test.ts`
passed 15/15.
- [ ] Applicable broad gate passed — `npm test` for broad
runtime/test-harness changes; `npm run check` for repo-wide
validation/coverage changes — command/result:
- [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)
- [ ] 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)

---
Signed-off-by: San Dang <sdang@nvidia.com>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Bug Fixes**
  * Improved sandbox recovery when build or policy settings change.
* Explicit sandbox recreation now proceeds without incorrectly reporting
a fingerprint mismatch error.
* Prevented unnecessary failures when checkpoint configuration changes
during intentional recreation.

* **Tests**
* Added coverage to verify successful sandbox recreation after build or
policy checkpoint changes.
  * Confirmed recreation is performed once and completes without errors.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: sandl99

src/lib/onboard/machine/handlers/sandbox-checkpoint-crash-recovery.test.ts

@@ -26,10 +26,13 @@ vi.mock("../../messaging-channel-setup", () => ({
 
 vi.mocked(detectMessagingChannelsFromEnv).mockReturnValue([]);
 
-function defaultCreateFingerprint(sandboxName = "my-assistant"): string {
+function defaultCreateFingerprint(
+  builtFingerprint = "my-assistant",
+  policyFingerprint = "default",
+): string {
   return [
-    sandboxName,
-    "default",
+    builtFingerprint,
+    policyFingerprint,
     "provider",
     "model",
     "openai-completions",
@@ -925,6 +928,34 @@ describe("sandbox crash-recovery replay (#5961, #6228)", () => {
     expect(calls.error.mock.calls.flat().join("\n")).toContain("--recreate-sandbox");
   });
 
+  it.each([
+    ["build", defaultCreateFingerprint("v0.0.108")],
+    ["policy", defaultCreateFingerprint("my-assistant", "previous-policy")],
+  ] as const)("recreates after %s drift when explicitly requested (#9297)", async (_drift, fingerprint) => {
+    const session = sessionWithCheckpoint(
+      crashedCheckpoint({
+        effectGroups: {
+          sandbox_create: { completedAt: "2026-01-01T00:00:00.000Z", fingerprint },
+        },
+      }),
+    );
+    session.machine.state = "openclaw";
+    const { deps, calls } = createDeps({ getSandboxReuseState: () => "ready" }, session);
+
+    await handleSandboxState({
+      ...baseOptions(deps, session),
+      resume: true,
+      sandboxName: "my-assistant",
+      recreateSandbox: () => true,
+    });
+
+    expect(calls.createSandbox).toHaveBeenCalledOnce();
+    expect(calls.createSandbox.mock.calls[0]?.at(-1)).toEqual(
+      expect.objectContaining({ recreate: true }),
+    );
+    expect(calls.error).not.toHaveBeenCalled();
+  });
+
   it("rejects reuse when a resolved policy or package input drifted despite an unchanged build version and policy tier (#7022)", async () => {
     const { deps, calls } = createDeps({ getSandboxReuseState: () => "ready" });
     const session = sessionWithCheckpoint(crashedCheckpoint());
@@ -1021,6 +1052,45 @@ describe("sandbox crash-recovery replay (#5961, #6228)", () => {
     expect(resumedRun.calls.error.mock.calls.flat().join("\n")).toContain("--recreate-sandbox");
   });
 
+  it("recreates after stable resolved create-intent drift when explicitly requested (#9297)", async () => {
+    const session = createSession({ sessionId: "sess-1", agent: "openclaw" });
+    const updateSession = vi.fn((mutator: (value: typeof session) => void) => {
+      mutator(session);
+      return session;
+    });
+    const firstRun = createDeps({ getSandboxReuseState: () => "missing", updateSession });
+
+    await handleSandboxState({
+      ...baseOptions(firstRun.deps, session),
+      resume: false,
+      sandboxName: "my-assistant",
+    });
+
+    const resumedRun = createDeps({ getSandboxReuseState: () => "missing", updateSession });
+    const defaultResolve = resumedRun.calls.resolveCreateIntent.getMockImplementation();
+    expect(defaultResolve).toBeDefined();
+    resumedRun.calls.resolveCreateIntent.mockImplementation(async (input) => {
+      const resolved = await defaultResolve!(input);
+      return {
+        ...resolved,
+        policy: { ...resolved.policy, basePolicyPath: "/repo/changed-policy.yaml" },
+      };
+    });
+
+    await handleSandboxState({
+      ...baseOptions(resumedRun.deps, session),
+      resume: true,
+      recreateSandbox: () => true,
+      sandboxName: "my-assistant",
+    });
+
+    expect(resumedRun.calls.createSandbox).toHaveBeenCalledOnce();
+    expect(resumedRun.calls.createSandbox.mock.calls[0]?.at(-1)).toEqual(
+      expect.objectContaining({ recreate: true }),
+    );
+    expect(resumedRun.calls.error).not.toHaveBeenCalled();
+  });
+
   it("rejects reasoning capability drift before replaying a recorded sandbox create (#7570)", async () => {
     const session = createSession({ sessionId: "sess-1", agent: "openclaw" });
     const updateSession = vi.fn((mutator: (value: typeof session) => void) => {

src/lib/onboard/machine/handlers/sandbox.ts

@@ -851,6 +851,7 @@ class SandboxStateFlow<
     sandboxName: string,
     createIntent: ResolvedSandboxCreateIntent,
   ): void {
+    if (this.options.recreateSandbox(false)) return;
     const recordedFingerprint = state.session?.checkpoint?.effectGroups.sandbox_create?.fingerprint;
     if (!recordedFingerprint) return;
     // Older and reuse-backfilled receipts contain the stable create-input prefix.