docs(security): review OpenShell v0.0.101 contracts

[apurvvkumaria]

Summary

Records the exact OpenShell v0.0.99-to-v0.0.101 and public v0.0.85-to-v0.0.101 migration/security boundaries before any selector changes. It freezes the producer/consumer invariants, qualification selectors, credential-boundary evidence, and one-to-one correction ownership required by the upgrade epic.

Related Issue

Fixes #8599

Parent epic: #8590

Changes

• Add the OpenShell v0.0.101 migration/security review with exact commits, artifacts, inherited concerns, OS101-I01–I16, and OS101-C01–C05 ownership.
• Explicitly bind the completed review to parent epic [Epic] Qualify and pin OpenShell v0.0.101 #8590 while retaining its later selector, qualification, and final-candidate gates.
• Add a newly generated v0.0.101 child-visible credential manifest bound to upstream Git blob identities and downstream sanitizer digests; activation remains owned by Update NemoClaw selectors and pins for OpenShell v0.0.101 #8606.
• Add contract tests that freeze the reviewed identities, Docker/Podman-only selection, credential boundary, correction routing, parent-epic link, and exact 14-selector/11-final-selector qualification sets.
• Add the security contract test to the source-shape budget without changing runtime, selector, policy, or qualification behavior.

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 is migration/security evidence and contract freezing; it activates no user-facing behavior.
• 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: Independent security, correctness, test-quality, and documentation review passed for the corrected exact commit 5279c514079657101e18231b0c49846c16a9af91 with no Medium-or-higher finding.
• 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: docs-updated
• Evidence: docs/security/openshell-0.0.101-migration-review.md; the writing rules and documentation style were reviewed, and no additional user-facing page is needed because this PR activates no behavior.
• 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 published commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: Review OpenShell v0.0.101 migration and security contracts #8599 contract tests 5/5; gateway launch contracts 10/10; CLI type-check passed; npm run docs completed with 0 errors (two pre-existing Fern warnings); clean Ubuntu root/plugin installs and builds plus source-map validation passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Exact-head GitHub run 31256993579 passed all eight CLI/integration/E2E-support shards plus build/typecheck, static, audit, installer-integration, plugin, and aggregate checks.
• 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

• Security

  • Added a security review for the OpenShell 0.0.101 migration, including release integrity, credential handling, runtime identity, upgrades, recovery, and isolation requirements.
  • Added a credential-visibility manifest documenting approved sources, environment keys, and runtime-controlled variables.
  • Added safeguards requiring generated credential data to remain tied to reviewed source identities.

• Tests

  • Added comprehensive migration validation covering version evidence, credential boundaries, configuration behavior, and qualification requirements.

[coderabbitai]

📝 Walkthrough

Walkthrough

This change adds the OpenShell 0.0.101 migration review, a generated child-credential visibility manifest, and Vitest validation for source identity, artifact integrity, security boundaries, runtime configuration, inherited invariants, and qualification selectors.

Changes

OpenShell 0.0.101 migration review

Layer / File(s)	Summary
Migration and security review contracts docs/security/openshell-0.0.101-migration-review.md	Defines release boundaries, artifact trust findings, changed contracts, credential-security findings, inherited invariants, correction ownership, and acceptance requirements.
Credential visibility manifest src/lib/actions/sandbox/openshell-child-visible-credentials.v0.0.101.json, docs/security/openshell-0.0.101-migration-review.md, ci/source-shape-test-budget.json	Adds the versioned credential manifest, records source identities and hashes, defines visible and rewritten keys, and classifies runtime-controlled variables.
Qualification and acceptance validation test/openshell-0.0.101-migration-review.test.ts, docs/security/openshell-0.0.101-migration-review.md	Validates release identities, manifest integrity, Docker and Podman behavior, inherited invariants, correction ownership, migration handling, and complete and final selector sets.

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

Possibly related issues

• NVIDIA/NemoClaw issue 8602: Covers credential-manifest validation and security-boundary testing implemented here.
• NVIDIA/NemoClaw issue 8590: Covers the OpenShell 0.0.101 migration review and credential-boundary requirements implemented here.

Possibly related PRs

• NVIDIA/NemoClaw#8523: Updates the related versioned child-visible credential manifest and migration-review validation for OpenShell 0.0.99.
• NVIDIA/NemoClaw#8583: Provides related OpenShell compatibility, credential-boundary, and qualification contracts.
• NVIDIA/NemoClaw#8616: Provides related OpenShell 0.0.101 release identity and artifact trust validation.

Suggested labels: security, release-target

Suggested reviewers: cv, senthilr-nv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.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
Linked Issues check	✅ Passed	The review, generated manifest, and tests address the migration boundaries, security contracts, evidence, invariants, and correction ownership required by issue #8599.
Out of Scope Changes check	✅ Passed	The documentation, manifest, test, and source-shape budget changes directly support the review objectives and do not alter runtime or selector behavior.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: a security review of OpenShell v0.0.101 contracts.

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/8599-openshell-v101-contract-review

---

_{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 5279c51 in the codex/8599-openshell... branch remains at 96%, unchanged from commit a76e297 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 5279c51 in the codex/8599-openshell... branch remains at 81%, unchanged from commit a76e297 in the main branch.

Show a code coverage summary of the most impacted files.

File	main a76e297	codex/8599-openshell... 5279c51	+/-
src/lib/onboard...an-lifecycle.ts	95%	79%	-16%
src/lib/policy/index.ts	63%	62%	-1%
src/lib/onboard...trap/adapter.ts	68%	70%	+2%
src/lib/onboard...mo-lifecycle.ts	84%	86%	+2%
src/lib/onboard...cker-journal.ts	70%	75%	+5%
src/lib/onboard...ne-authority.ts	84%	91%	+7%
src/lib/onboard...strap/docker.ts	64%	72%	+8%
src/lib/onboard.../docker-spec.ts	65%	74%	+9%
src/lib/onboard...shared-state.ts	73%	90%	+17%
src/lib/policy/...ateway-state.ts	56%	73%	+17%

---

_{Updated August 08, 2026 12:32 UTC}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-8617.docs.buildwithfern.com/nemoclaw

[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 `@docs/security/openshell-0.0.101-migration-review.md`:
- Around line 22-35: Link the completed migration review to parent epic `#8590` by
adding an explicit reference in the acceptance section of
docs/security/openshell-0.0.101-migration-review.md (lines 22-35), then update
the contract test in test/openshell-0.0.101-migration-review.test.ts (lines
167-186) to assert that `#8590` is present.

🪄 Autofix

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: 0ed40726-7af8-483e-a22f-cf6ebb809c1a

📥 Commits

Reviewing files that changed from the base of the PR and between a76e297 and c005e03.

📒 Files selected for processing (4)

• ci/source-shape-test-budget.json
• docs/security/openshell-0.0.101-migration-review.md
• src/lib/actions/sandbox/openshell-child-visible-credentials.v0.0.101.json
• test/openshell-0.0.101-migration-review.test.ts

[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 · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Failed after a partial review · low confidence · 0 blockers · 0 warnings · 0 suggestions

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• established — base-trusted at docs/security/openshell-0.0.101-migration-review.md:30: Retain `base-trusted` for an independently rooted trust boundary.
• established — child-visible credential at docs/security/openshell-0.0.101-migration-review.md:204: Retain `child-visible credential` for child-environment credential boundaries.
• define — qualification selector at test/openshell-0.0.101-migration-review.test.ts:320: Define `qualification selector` at first explanatory use if it becomes user-facing.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite against this exact revision.

Recommended E2E: cloud-inference, managed-image-multiarch-startup, security-posture

Workflow run details

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