fix(uninstall): ignore desktop metadata in the gateway scan

[Dongni-Yang]

Summary

The gateway-directory scan counted any non-directory entry under ~/.nemoclaw/gateways as an unidentified sibling gateway, which scopes the uninstall to the selected gateway. That path skips CLI and shell-shim removal entirely and still exits 0, so nemoclaw, nemohermes, and nemo-deepagents stayed on PATH after a run that reported success. A .DS_Store, which macOS writes into a directory it displays, was enough to trigger it. The scan now skips a regular file whose name is desktop metadata.

Related Issue

Refs #7905

Changes

• src/lib/actions/uninstall/run-plan.ts: add isDesktopMetadataEntry and skip a regular file named .DS_Store, .localized, or ._<name> before the conservative non-directory branch in discoverOtherGatewayEnvironments.
• The conservatism is deliberate and stays intact for every other shape. Only entry.isFile() matches, so a directory or a symlink with the same name still sets unidentified, and an unrecognized entry such as not-a-port still scopes the uninstall.
• src/lib/actions/uninstall/run-plan-gateway-scan-entries.test.ts (new): cover the reported metadata-file behavior and guard conservative handling for unidentified entries, the bare ._ boundary, metadata-named directories, and metadata-named symlinks. A new focused file rather than an addition to run-plan-gateway-segregation.test.ts, which is at 1392 of the 1500-line budget.

No new abstraction: isDesktopMetadataEntry is a single local predicate with one call site. src/lib/build-context.ts:33 filters .DS_Store and ._ for a different purpose and with a different contract (no symlink conservatism, no .localized), so the two are deliberately not shared.

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: The published contract already says uninstall removes the shared CLI when no sibling gateway remains (docs/manage-sandboxes/uninstall-nemoclaw.mdx:88, docs/reference/commands.mdx), and no page ever defined a stray file as a sibling gateway. This makes the code match the documented contract rather than changing a documented surface. rg over docs/ for "Sibling gateways remain", "shell shims", and ".DS_Store" returns zero hits. Per docs/CONTRIBUTING.md:83-102 a dated changelog entry belongs to the pre-tag release-note PR.
• 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: Maintainer security review PASS at a8c993902. The change skips only recognized regular metadata files. Directories, symlinks, malformed names, and unknown entries remain conservative. The nine-category review found no secrets, unsafe input handling, authorization changes, dependency risk, sensitive logging, cryptography changes, insecure configuration, test regressions, or broader security-posture degradation. The added symlink regression strengthens negative coverage for the resource-retention boundary.
• 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: no-docs-needed
• Evidence: Independent review of the completed branch confirmed the focused symlink regression does not change user-visible behavior or documentation requirements. The existing contract pages remain accurate and no docs/ file changed.
• Agent: Codex documentation writer

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 — focused gateway-scan tests pass 7/7. npm run build:cli, npm run typecheck:cli, Biome, source-shape, test-size, test-title, and Vitest project-overlap checks pass.
• 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)

---

Scope note

Refs #7905 rather than Closes, because this is very likely not the reporter's cause. Their steps describe a default-port onboard, and ~/.nemoclaw/gateways/ is only created for a non-default gateway port (src/lib/state/state-root.ts:16), so on that host the directory would not exist and this scan returns early. Reaching this bug needs a host that used a non-default port at some point, leaving the directory behind for a desktop environment to write into.

The reporter is on v0.0.97, whose scan lacked the port === GATEWAY_PORT guard, so the selected gateway counted itself a sibling and took the same retention path. That is #7987, fixed by #7993 and shipped in v0.0.101, after this report. A separate follow-up on the issue asks for the uninstall output to confirm which path they hit.

Signed-off-by: Dongni Yang dongniy@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved uninstall scanning by ignoring common desktop metadata files.
  • Prevents managed CLI shims from being removed when only harmless metadata is present.
  • Continues to protect unidentified entries and metadata directories or symlinks from removal.

• Tests

  • Added coverage for uninstall scanning and safe shim cleanup behavior.

[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: 620aaa20-3e71-44d4-b604-cc6e1a0b8e60

📥 Commits

Reviewing files that changed from the base of the PR and between 2bf71d0 and a8c9939.

📒 Files selected for processing (1)

• src/lib/actions/uninstall/run-plan-gateway-scan-entries.test.ts

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

• src/lib/actions/uninstall/run-plan-gateway-scan-entries.test.ts

---

📝 Walkthrough

Walkthrough

Gateway uninstall scanning ignores regular .DS_Store, .localized, and non-empty ._* files. Tests verify shim removal for metadata-only entries and retention for unknown entries or metadata directories.

Changes

Gateway metadata filtering

Layer / File(s)	Summary
Desktop metadata detection and validation src/lib/actions/uninstall/run-plan.ts, src/lib/actions/uninstall/run-plan-gateway-scan-entries.test.ts	The scanner skips regular macOS desktop metadata files. Directories and symlinks with matching names remain unidentified. Tests verify shim removal and scoped retention logging.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: area: install, bug-fix

Suggested reviewers: apurvvkumaria, cv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: ignoring desktop metadata during the uninstall gateway scan.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ 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/7905-gateway-scan-inert-entries

---

_{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 a8c9939 in the fix/7905-gateway-sca... branch remains at 96%, unchanged from commit e323de1 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit a8c9939 in the fix/7905-gateway-sca... branch remains at 81%, unchanged from commit e323de1 in the main branch.

Show a code coverage summary of the most impacted files.

File	main e323de1	fix/7905-gateway-sca... a8c9939	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/platform.ts	89%	84%	-5%
src/lib/credentials/store.ts	56%	55%	-1%
src/lib/actions...air-approval.ts	90%	89%	-1%
src/lib/actions...all/run-plan.ts	85%	85%	0%
src/lib/inferen...ompatibility.ts	94%	94%	0%
src/lib/core/immutable.ts	97%	97%	0%
src/lib/domain/...dbox/destroy.ts	84%	89%	+5%
src/lib/adapter...regular-file.ts	93%	98%	+5%
src/lib/inferen...a/model-size.ts	83%	96%	+13%

---

_{Updated August 06, 2026 14:38 UTC}

[coderabbitai]

Actionable comments posted: 2

🤖 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/uninstall/run-plan-gateway-scan-entries.test.ts`:
- Around line 89-96: Update the uninstall plan tests around runUninstallPlan to
use the real fs.rmSync for the temporary fixture while keeping process and
external-command dependencies mocked. After runUninstallPlan returns, assert
each shim’s actual filesystem state with fs.existsSync(), verifying removed
shims are absent and retained shims remain; remove reliance on the removed array
and rmSync mock-call assertions.

In `@src/lib/actions/uninstall/run-plan.ts`:
- Around line 1657-1659: Update isDesktopMetadataEntry to recognize AppleDouble
files only when the name starts with "._" and contains at least one character
after the prefix, while preserving the existing .DS_Store and .localized
matches. Add regression coverage for .localized, ._name, and the exact ._
boundary.

🪄 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: 67a63897-a12c-4355-9f92-5dcf42cdb030

📥 Commits

Reviewing files that changed from the base of the PR and between 52cfe61 and 09bcb73.

📒 Files selected for processing (2)

• src/lib/actions/uninstall/run-plan-gateway-scan-entries.test.ts
• src/lib/actions/uninstall/run-plan.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): 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.

2 semantic terminology decisions

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

• justified — desktop metadata at src/lib/actions/uninstall/run-plan.ts:1734: Keep “desktop metadata” for this constrained filename class and retain the regular-file contrast.
• define — resource fork at src/lib/actions/uninstall/run-plan.ts:1655: Keep the inline explanation that defines the term in its filesystem context.

E2E guidance

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

Recommended E2E: None

Workflow run details

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

[Dongni-Yang]

Both findings were valid and are addressed in 2bf71d0.

._ boundary. Correct — startsWith("._") also matched the bare filename ._, which carries no name and so is not a resource-fork companion. It now requires at least one character after the prefix, keeping the conservative treatment for ._ itself.

Filesystem assertions. Also correct: asserting on the paths an rmSync double recorded proves the call, not the outcome. Removal now runs the real fs.rmSync, restricted to the temporary home, and each case reports which shims actually survived — expect(survivors).toEqual([]) for removal and toEqual(shims) for retention.

Coverage is now six cases across two tables: .DS_Store, .localized, and ._sandboxes.json must remove the shims; not-a-port, the bare ._, and a directory named .DS_Store must keep them.

Red/green re-proved against the parent source: with upstream/main's run-plan.ts restored, exactly the three removal cases fail and the three conservative cases pass, so the latter are guard cases rather than repros. Full uninstall suite 163 passed, typecheck and Biome clean.

One note on the earlier suggestion to share this with src/lib/build-context.ts, in case a reviewer raises it: that helper filters .DS_Store and ._ for build-context exclusion, with no symlink conservatism and no .localized. The contracts differ, so they are deliberately kept separate rather than merged into one predicate.

[apurvvkumaria]

Addressed the PR Review Advisor warning in the current branch revision (a8c993902). The focused regression now creates a .DS_Store symlink and verifies that uninstall keeps all managed CLI shims and emits the sibling-retention message, preserving the conservative boundary for metadata-named symlinks.

Validation: focused gateway-scan tests pass 7/7; CLI build and typecheck, Biome, source-shape, test-size, test-title, and Vitest project-overlap checks pass. The completed nine-category security review is clean, and the independent documentation review found no documentation changes needed. The PR description now records both receipts for this revision.

[apurvvkumaria]

CI follow-up for the current branch revision:

• The initial CLI shard failure was confined to three assertions in the untouched MCP lifecycle-lock suite: one stale-token observation and two lock-timeout races. The targeted retry passed all eight CLI shards, the aggregate CLI suite, and the final checks rollup, confirming transient timing interference rather than an uninstall regression.
• The Nemotron second-opinion job failed again during advisor analysis execution, while the trusted Terra advisor completed successfully and the advisor publication workflow completed. This is external advisor infrastructure, not actionable PR feedback.

All PR-related tests and required CI are now green. Independent approval remains the merge gate.