fix(rebuild): reuse gateway web-search credential in preflight

[nvshaxie]

Summary

nemoclaw rebuild --yes failed preflight with Brave Search credential is invalid. Brave Search requires BRAVE_API_KEY or a saved Brave Search credential in non-interactive mode. for sandboxes whose web search works. saveCredential stages web-search keys to the process env only — the OpenShell gateway provider is the durable system of record — so a fresh rebuild process holds no host key, and the preflight demanded one it would never use: the OpenClaw recreate path already reuses the gateway-registered credential (messaging-prep requiresExactOpenClawProviderBinding). After this change the preflight accepts that same gateway credential-only provider binding, and rebuild succeeds without re-exporting BRAVE_API_KEY.

Related Issue

Fixes #7097

Changes

• src/lib/actions/sandbox/rebuild-target-runtime.ts: before demanding a host key, preflightRebuildWebSearchCredential accepts a matching gateway credential-only provider binding (<sandbox>-<provider>-search, provider type, recorded credential key) read via readGatewayProviderMetadata, scoped to the sandbox's resolved gateway. The reuse is gated to the OpenClaw agent (target.agentDefinition === null) — the only recreate path that reuses the binding — and only when no host key is staged; a staged key and non-OpenClaw agents keep the existing validation path, and a missing/mismatched binding still fails closed.
• src/lib/actions/sandbox/rebuild-target-runtime.test.ts: cover gateway-binding reuse, fail-closed on missing binding, staged-host-key validation, and the non-OpenClaw validation path.

Scope note: issue #7097 also reports the balanced tier creating a global brave provider profile as a side effect. The provider profile import in NemoClaw has tolerated already exists since #6165, and decoupling the egress preset from the provider profile is a design decision (the profile drives the L7 proxy token rewrite), so it is not changed here; details on the issue.

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: no doc page documents a host-key requirement for rebuild; this removes an incorrect preflight failure so behavior matches the existing quickstart web-search docs.
• 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: author review — the reuse check reads provider identity metadata only (readGatewayProviderMetadata never reads or exports credential values), requires the exact recorded name/type/credential-key binding with no config keys, is scoped to the sandbox's resolved gateway, and fails closed for mismatches, staged host keys, and non-OpenClaw agents.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

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 — command/result: npx vitest run --project cli src/lib/actions/sandbox/rebuild-target-runtime.test.ts (7 passed); npm run test:changed (60 passed); npx vitest run --project integration test/rebuild-credential-preflight.test.ts test/rebuild-stale-recovery.test.ts test/rebuild-shields-auto-unlock.test.ts (13 passed); npm run typecheck:cli clean.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• 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: Shawn Xie shaxie@nvidia.com

Summary by CodeRabbit

• New Features

  • Web-search credentials can now be reused during sandbox runtime recreation when an existing gateway credential matches the configured web-search provider.

• Bug Fixes

  • Improved credential preflight logic: correctly revalidates when a staged host key is present, fails when neither a valid gateway credential nor host key is available, and preserves the expected behavior for non-OpenClaw agent configurations.

• Tests

  • Added coverage for the new web-search credential reuse and failure scenarios during runtime preflight.

[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: 9636f38d-6972-4fd7-9b45-aa3f4272ea44

📥 Commits

Reviewing files that changed from the base of the PR and between b3d610f and f6e61cd.

📒 Files selected for processing (1)

• src/lib/actions/sandbox/rebuild-target-runtime.test.ts

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

• src/lib/actions/sandbox/rebuild-target-runtime.test.ts

---

📝 Walkthrough

Walkthrough

Rebuild runtime preflight now reuses matching web-search credentials registered on the sandbox gateway when no host key is staged. Otherwise it preserves credential validation and failure handling. Tests add gateway-related mocks and cover reuse, fallback validation, staged-key precedence, and non-OpenClaw behavior.

Changes

Web-search rebuild preflight

Layer / File(s)	Summary
Gateway credential reuse logic src/lib/actions/sandbox/rebuild-target-runtime.ts	Rebuild preflight checks sandbox gateway metadata for a matching credential-only web-search binding, reuses it when applicable, and otherwise validates the target configuration through the existing credential path.
Gateway reuse preflight tests src/lib/actions/sandbox/rebuild-target-runtime.test.ts	Mocks gateway and credential dependencies and verifies reuse, missing-credential failure, provider mismatch failure, staged host-key precedence, and non-OpenClaw validation behavior.

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

Suggested labels: area: sandbox, bug-fix

Suggested reviewers: ericksoa, cv

Sequence Diagram(s)

sequenceDiagram
  participant RebuildPreflight
  participant GatewayMetadata
  participant CredentialValidation
  RebuildPreflight->>GatewayMetadata: read sandbox gateway provider metadata
  GatewayMetadata-->>RebuildPreflight: matching binding or no match
  RebuildPreflight->>CredentialValidation: validate and stage host credential when needed

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: reusing gateway web-search credentials during rebuild preflight.
Linked Issues check	✅ Passed	The PR addresses the rebuild false-rejection by reusing a saved gateway credential and keeps the balanced-tier profile side effect out of scope.
Out of Scope Changes check	✅ Passed	The changes stay focused on rebuild preflight logic and tests, with no unrelated functionality added.

✨ 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 fix/7097-rebuild-web-search-gateway-credential

---

_{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 remains at 96%, unchanged from the main branch.

TypeScript / code-coverage/cli

The overall coverage in the fix/7097-rebuild-web... branch remains at 80%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 980e348	fix/7097-rebuild-web... 664200b	+/-
src/lib/actions...rget-runtime.ts	95%	90%	-5%
src/lib/state/registry.ts	86%	83%	-3%
src/lib/adapter...hell/resolve.ts	100%	100%	0%
src/lib/agent/dashboard-ui.ts	96%	96%	0%
src/lib/onboard...der-metadata.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	91%	91%	0%
src/lib/securit...p-url-target.ts	100%	100%	0%
src/lib/credentials/store.ts	59%	64%	+5%
src/lib/actions...flight-error.ts	80%	100%	+20%
src/lib/core/pr...mpt-activity.ts	67%	92%	+25%

---

_{Updated July 18, 2026 20:02 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[coderabbitai]

Actionable comments posted: 1

🤖 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/rebuild-target-runtime.test.ts`:
- Around line 219-233: Add a regression test alongside the existing preflight
failure test that supplies gateway provider metadata with a present but
non-matching binding, then exercises preflightRebuildTargetRuntime. Assert the
preflight fails closed and verifies the expected credential validation and bail
behavior, covering the mismatched-binding path separately from missing metadata.

🪄 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: a81b7d12-cabb-4252-9c5c-38f94ed3b706

📥 Commits

Reviewing files that changed from the base of the PR and between 7750075 and b3d610f.

📒 Files selected for processing (2)

• src/lib/actions/sandbox/rebuild-target-runtime.test.ts
• src/lib/actions/sandbox/rebuild-target-runtime.ts

[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 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, state-backup-restore, upgrade-stale-sandbox

3 optional E2E recommendations

• rebuild-openclaw
• sandbox-rebuild
• brave-search

Workflow run details

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

[apurvvkumaria]

Reviewed exact head 664200b after the current-main refresh. Focused tests, full CI, CodeQL, advisors, and selected E2E checks are green; all review threads are resolved. Security review found no correctness or security blocker.