fix(uninstall): delete all installed host models

[rsliter]

Summary

Previously, uninstall --delete-models removed only two statically listed Ollama models and preserved the shared Hugging Face cache. It now removes every model reported by the host's loopback Ollama inventory and deletes non-credential Hugging Face cache data after managed model runtimes stop, while preserving authentication files and shared model stores needed by sibling gateways. Inventory, path-safety, or deletion failures now make uninstall return nonzero.

Related Issue

Fixes #8917

Changes

• Replace the static Ollama model allowlist with a validated ollama list inventory pinned to 127.0.0.1:11434, then attempt removal of every reported model and propagate failures.
• Delete non-credential data under the current user's ~/.cache/huggingface/ only after managed local and distributed runtimes stop. Preserve token and stored_tokens, reject unsafe cache ownership or paths, and keep shared model stores while sibling gateways remain.
• Update uninstall planning, confirmation text, CLI help, smoke-script help, user documentation, and behavior tests for the expanded destructive scope and recovery states.

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:
• 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: Codex Desktop reviewed destructive cleanup, credential lifetime, endpoint authority, ownership checks, sibling-gateway behavior, partial failure, and retry states; tests preserve Hugging Face credentials and force Ollama cleanup to loopback.
• 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/inference/choose-local-inference-server.mdx, docs/inference/set-up-llama-cpp.mdx, docs/manage-sandboxes/uninstall-nemoclaw.mdx, docs/reference/commands.mdx, docs/reference/host-files-and-state.mdx
• 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 commit appears as Verified in GitHub
• 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
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: eight affected CLI suites passed 127/127 tests; npx vitest run --project integration test/uninstall.test.ts -t "uses NemoHermes branding" passed 2/2 matching tests.
• 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: Rebecca Sliter 571084+rsliter@users.noreply.github.com

Summary by CodeRabbit

• New Features

  • Uninstalling with --delete-models now removes all locally installed Ollama models and non-credential Hugging Face cache data.
  • Hugging Face authentication files are preserved.
  • Cleanup includes safety checks, runtime shutdown ordering, sibling-environment protection, and clear failure reporting.

• Documentation

  • Updated uninstall guides and command help to explain cleanup scope, safeguards, preserved data, partial cleanup, and recovery guidance.

[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: 6cc894d1-3a97-4bb3-9da1-b8164f2fd45c

📥 Commits

Reviewing files that changed from the base of the PR and between a1b8884 and 7fe855f.

📒 Files selected for processing (2)

• src/lib/inference/local-model-profile/cleanup-entry.ts
• src/lib/inference/local-model-profile/cleanup.test.ts

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

• src/lib/inference/local-model-profile/cleanup-entry.ts

---

📝 Walkthrough

Walkthrough

The uninstall flow now inventories all local Ollama models and removes them when --delete-models is enabled. It also removes non-credential data from the shared Hugging Face cache, preserves authentication files, validates cache safety, and reports cleanup failures.

Changes

Host model cleanup

Layer / File(s)	Summary
Uninstall plan and path contract src/lib/domain/uninstall/paths.ts, src/lib/domain/uninstall/plan.ts, src/lib/domain/uninstall/*.test.ts	The plan defines aggregate actions for Ollama models and Hugging Face cache data. Default paths include ~/.cache/huggingface.
Hugging Face cache cleanup src/lib/inference/local-model-profile/cleanup.ts, src/lib/inference/local-model-profile/*test.ts	Cleanup validates ownership, symlink status, permissions, and filesystem authority. It removes non-credential cache data and preserves token and stored_tokens.
Inventory and cleanup execution src/lib/actions/uninstall/run-plan.ts, src/lib/actions/uninstall/*test.ts	Uninstall inventories models through ollama list, uses the local Ollama host, removes each model, orders distributed cleanup before host cleanup, and propagates failures.
CLI and documentation contract src/commands/internal/uninstall/*, src/lib/actions/root-help.ts, scripts/smoke-macos-install.sh, docs/**/*.mdx, test/uninstall.test.ts	Help text, documentation, and assertions describe the expanded deletion scope and preservation rules.

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

Mergeability Score: ⚪ Minimal · up to 7fe85

The uninstall behavior now removes all reported host models and eligible cache data while preserving credentials and shared stores; no actionable merge-blocking risk remains after normal checks and review.

Suggested labels: area: cli, area: docs, area: local-models, area: security

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% 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 changes implement the linked issue requirements for complete Ollama inventory and deletion, Hugging Face cleanup, safety checks, failure handling, preservation, documentation, and tests.
Out of Scope Changes check	✅ Passed	The changes remain within the linked issue scope and support model cleanup behavior, safety, testing, CLI messaging, and documentation.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the primary change: uninstall now deletes all installed host models instead of a fixed subset.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/delete-all-host-models-8917

---

_{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 12b1048 in the codex/delete-all-hos... branch remains at 96%, unchanged from commit e1391a4 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 12b1048 in the codex/delete-all-hos... branch remains at 82%, unchanged from commit 7c721ae in the main branch.

Show a code coverage summary of the most impacted files.

File	main 7c721ae	codex/delete-all-hos... 12b1048	+/-
src/lib/cua/bounded-file.ts	94%	84%	-10%
src/lib/cua/run...ime-manifest.ts	91%	84%	-7%
src/lib/cua/contract.ts	87%	80%	-7%
src/lib/messagi.../ilink-login.ts	96%	89%	-7%
src/lib/trace.ts	94%	90%	-4%
src/lib/state/o...d-checkpoint.ts	90%	87%	-3%
src/lib/actions...all/run-plan.ts	85%	86%	+1%
src/lib/onboard...press-resume.ts	78%	82%	+4%
src/lib/securit...ntial-filter.ts	91%	95%	+4%
src/lib/onboard...der/snapshot.ts	75%	83%	+8%

---

_{Updated August 12, 2026 23:28 UTC}

[github-actions]

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

[coderabbitai]

Actionable comments posted: 4

🤖 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 `@scripts/smoke-macos-install.sh`:
- Line 62: Update the --delete-models help description in
scripts/smoke-macos-install.sh to say “non-credential Hugging Face cache data,”
clarifying that credentials are preserved. Update the public help-output
assertion in test/uninstall.test.ts to require the same wording.

In `@src/lib/actions/root-help.ts`:
- Around line 84-86: Update the --delete-models description in
src/lib/actions/root-help.ts (lines 84-86), the planned cleanup description in
src/commands/internal/uninstall/plan.ts (line 23), and the runtime cleanup
description in src/commands/internal/uninstall/run-plan.ts (line 33) to state
that Hugging Face cache data is deleted while authentication files remain,
matching the confirmation prompt wording.

In `@src/lib/actions/uninstall/run-plan.ts`:
- Around line 1777-1783: Add an explicit timeout to each `runtime.run`
invocation used by the Ollama removal loop in `run-plan.ts`, preserving the
existing environment and ignored-stdio options. Ensure the timeout applies
independently to every `ollama rm` model attempt, and add a regression assertion
verifying the configured timeout is passed to the command.

In `@src/lib/domain/uninstall/plan.ts`:
- Around line 110-125: The uninstall plan and executor disagree on where Hugging
Face cache cleanup occurs. In src/lib/domain/uninstall/plan.ts:110-125, move the
delete/preserve Hugging Face cache actions to the step executed by
runLocalModelRuntimeCleanup(), or alternatively keep Model stores authoritative
and update src/lib/actions/uninstall/run-plan.ts:2285-2286 to dispatch those
declared actions there; ensure the JSON plan, logs, and actual execution use the
same step.

🪄 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: 0e022589-3add-462e-9be8-17b9cf501e51

📥 Commits

Reviewing files that changed from the base of the PR and between 830d436 and 3bf053e.

📒 Files selected for processing (20)

• docs/inference/choose-local-inference-server.mdx
• docs/inference/set-up-llama-cpp.mdx
• docs/manage-sandboxes/uninstall-nemoclaw.mdx
• docs/reference/commands.mdx
• docs/reference/host-files-and-state.mdx
• scripts/smoke-macos-install.sh
• src/commands/internal/uninstall/plan.ts
• src/commands/internal/uninstall/run-plan.ts
• src/lib/actions/root-help.ts
• src/lib/actions/uninstall/run-plan-dual-station.test.ts
• src/lib/actions/uninstall/run-plan-local-model-profile.test.ts
• src/lib/actions/uninstall/run-plan.ts
• src/lib/domain/uninstall/paths.test.ts
• src/lib/domain/uninstall/paths.ts
• src/lib/domain/uninstall/plan.test.ts
• src/lib/domain/uninstall/plan.ts
• src/lib/inference/local-model-profile/cleanup-path-safety.test.ts
• src/lib/inference/local-model-profile/cleanup.test.ts
• src/lib/inference/local-model-profile/cleanup.ts
• test/uninstall.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 · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 2 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized terminology decisions differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 2 more warnings, the same number of suggestions.

6 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• cache data at docs/reference/host-files-and-state.mdx:144: selected only by the second-opinion lane as define.
• runtime cleanup at src/lib/actions/uninstall/run-plan.ts:1551: selected only by the second-opinion lane as established.
• non-credential at src/lib/inference/local-model-profile/cleanup.ts:735: selected only by the second-opinion lane as established.
• model stores at src/lib/domain/uninstall/plan.ts:110: selected only by the second-opinion lane as justified.
• cache-data cleanup at src/lib/inference/local-model-profile/cleanup-entry.ts:19: selected only by the second-opinion lane as justified.
• Ollama inventory at docs/manage-sandboxes/uninstall-nemoclaw.mdx:27: selected only by the second-opinion lane as justified.

3 additional E2E selections from the second opinion

Advisory only. The primary lane did not select these E2E jobs or targets.

• sandbox-operations: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• spark-install: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• llama-cpp-dgx-spark-qualification: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

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.

• justified — non-credential Hugging Face cache data at src/lib/inference/local-model-profile/cleanup.ts:735: Keep this term and identify the preserved token and stored_tokens files where the destructive scope matters.
• justified — local Ollama inventory at docs/manage-sandboxes/uninstall-nemoclaw.mdx:27: Keep this term for the deletion scope and retain the host-local endpoint constraint in implementation evidence.
• justified — authentication files at docs/inference/choose-local-inference-server.mdx:159: Keep this term only with the token and stored_tokens file names so the preserved credential scope remains explicit.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: inference-routing

Manual-only E2E: managed-image-multiarch-startup, network-policy
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

1 optional E2E recommendation

• ollama-auth-proxy

Workflow run details

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

[cv]

Product scope for #8917 is accepted. Please address these blockers before approval:

• Add a finite timeout to each ollama rm call and test the configured timeout. A stalled request currently blocks later cleanup and failure reporting.
• Align Hugging Face cache deletion with its declared uninstall plan step. The plan places it in Model stores, but execution runs it during Stopping services.
• Update every --delete-models description to state that Hugging Face authentication files remain. The current wording can imply that the command deletes credentials.
• Refactor the conditional mock logic in run-plan-local-model-profile.test.ts so codebase-growth-guardrails passes.

The current CodeRabbit threads identify the affected lines. Local npm run build:cli and npm run typecheck:cli passed. Focused CLI source tests passed.

[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/inference/local-model-profile/cleanup.test.ts`:
- Around line 386-394: Update the test around cleanupHuggingFaceCacheData to
create managed runtime state or another target affected by runtime cleanup, then
capture its original contents and assert they remain unchanged after the call.
Keep the existing Hugging Face cache assertions intact so the test verifies both
cache removal and runtime-cleanup exclusion.

🪄 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: 80f4b4e1-0684-45be-98ad-002eedd8d3d3

📥 Commits

Reviewing files that changed from the base of the PR and between 5b8a492 and a1b8884.

📒 Files selected for processing (10)

• docs/reference/host-files-and-state.mdx
• src/lib/actions/uninstall/run-plan-dual-station.test.ts
• src/lib/actions/uninstall/run-plan-local-model-profile.test.ts
• src/lib/actions/uninstall/run-plan.ts
• src/lib/domain/uninstall/plan.test.ts
• src/lib/domain/uninstall/plan.ts
• src/lib/inference/local-model-profile/cleanup-entry.ts
• src/lib/inference/local-model-profile/cleanup-path-safety.test.ts
• src/lib/inference/local-model-profile/cleanup.test.ts
• src/lib/inference/local-model-profile/cleanup.ts

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

• src/lib/actions/uninstall/run-plan-dual-station.test.ts
• src/lib/domain/uninstall/plan.test.ts
• src/lib/actions/uninstall/run-plan-local-model-profile.test.ts
• docs/reference/host-files-and-state.mdx
• src/lib/domain/uninstall/plan.ts
• src/lib/actions/uninstall/run-plan.ts