feat(uninstall): complete agents uninstall that restores adopted configs

[tenxxor]

Problem

There is no way to fully uninstall agents-cli. Setup adopts the user's real config: switchConfigSymlink / importAgent move ~/.<agent> aside and replace it with a symlink into the version homes. But no code path ever restores the backup — getBackupsDir() is only ever written to. So npm uninstall -g @phnx-labs/agents-cli leaves ~/.agents behind, ~/.claude a dangling symlink, and the user's original config stranded under ~/.agents/.history/backups/. Removing the CLI actively disturbs the user's local setup.

What this adds

A first-class agents uninstall — the reverse of agents setup. It removes agents-cli and restores the machine to its pre-install state.

Flow (restore before disposal, since the backups live inside ~/.agents):

1. Restore each adopted ~/.<agent> — newest timestamped backup if present, else the symlink target (the importAgent case, where the original was renamed into the version home). A real, un-adopted directory is left untouched.
2. Restore owned home files (~/.claude.json, …).
3. Release adopted launchers — restore native binaries on PATH (releaseAdoptedLauncher).
4. Strip the shim dir from every shell rc file (reuses stripShimPathLines).
5. Dispose of ~/.agents — moved aside to ~/.agents.removed-<timestamp> (recoverable) by default, or hard-deleted with --purge.
6. Print the final npm uninstall -g … — a running CLI can't reliably delete its own binary.

Safety

• Never touches an un-adopted config. Ownership is decided structurally by getConfigSymlinkVersion() (non-null only for a symlink into the versions dir) — the exact check removeVersion already uses. A real ~/.claude agents-cli never adopted is classified leave-real and never modified.
• --dry-run prints the full plan (restored / left-untouched / removed) and changes nothing.
• Refuses to run non-interactively without --yes.
• Recoverable by default (~/.agents moved aside, not deleted).
• Exempt from the setup gate, so it runs even from a broken/half-initialized state.
• Silences the event log for the run so a late emit() (whose events path is memoized) can't re-create ~/.agents after it is moved.

Implementation

• lib/uninstall.ts — read-only planUninstall() + mutating executeUninstall() so --dry-run and the real run share one path.
• commands/uninstall.ts — thin command (plan → confirm → execute → print npm step).
• Exports getAgentConfigPath + stripShimPathLines from shims.ts for reuse (no duplication).
• Registers the command (command-registry.ts, index.ts) and adds it to SETUP_EXEMPT_COMMANDS.

Tests

Subprocess tests against a real temp HOME (repo's no-mocking convention): restore-from-backup, restore-from-version-home, un-adopted dir left untouched, PATH strip, and planUninstall being read-only. bun run build clean; existing shims suite passes.

Verified end-to-end: a pre-existing real ~/.claude adopted by a normal install is restored to its original content on uninstall; an un-adopted ~/.codex is untouched; the shim PATH line is removed; ~/.agents is moved aside; and --purge hard-deletes while still restoring.

Scope note

macOS Keychain items created by agents secrets are managed by the signed helper app and are not removed even under --purge (documented in the notes). Bulk-Keychain teardown could be a follow-up.

🤖 Generated with Claude Code

[muqsitnawaz]

Review — NEEDS WORK ⚠️

Architecture is sound (read-only planUninstall + mutating executeUninstall, structural ownership via getConfigSymlinkVersion, restore-before-dispose ordering, move-aside default, well commented). But there are real data-loss defects under --purge plus a dangling-symlink restore, none of which the current tests can catch.

BLOCKER 1 — --purge hard-deletes ~/.agents even when a restore errored (sole-copy loss). executeUninstall swallows a failed restore into result.errors (catch (err) { result.errors.push(...) }) and step 6 still runs fs.rmSync(plan.agentsDir, { recursive: true, force: true }) unconditionally. For the restore-version-home case the original config is the sole copy — importAgentConfig MOVED it in with renameSync (import.ts:81) and restore only cpSyncs it back. A partial cpSync failure (ENOSPC/EACCES) → error swallowed → ~/.agents purged → only good copy destroyed. Fix: if result.errors.length > 0, downgrade --purge to move-aside; and/or use renameSync for restore-version-home.

BLOCKER 2 — EXDEV on restore-backup rename + --purge destroys the backup. if (c.kind === 'restore-backup') { fs.unlinkSync(c.realPath); fs.renameSync(c.source, c.realPath); }. c.source is under ~/.agents/.history/backups/…, c.realPath is $HOME/.<agent>. If ~/.agents is a symlink to another volume, renameSync throws EXDEV (Node has no copy-fallback); the symlink is already unlinked, the backup still sits inside ~/.agents, and step-6 --purge deletes it → ~/.<agent> gone AND backup gone. Same fix (error-gate purge; or copy-then-unlink / EXDEV fallback to cpSync).

HIGH — restore-version-home leaves dangling symlinks. Adoption syncs managed resource symlinks into the version-home config dir (skills at <versionHome>/<configDir>/skills/<name> → symlinkSync(centralPath, …, 'dir') into ~/.agents/skills/, skills.ts:305; commands likewise commands.ts:350). Restore does cpSync(c.source, c.realPath, { recursive: true }), which preserves symlinks. After ~/.agents is moved aside/purged, the restored ~/.claude/skills/* and ~/.claude/commands/* are dangling links into a dir that no longer exists — a degraded restore. restore-backup avoids this (backups predate resource sync). Fix: strip ~/.agents-pointing symlinks while copying (cpSync filter, or post-restore prune).

HIGH — tests can't catch any of the above. uninstall.test.ts is genuinely real-fs/no-mock (good), but the fixture's adopt() writes only a plain marker file — it never creates the resource symlinks-into-~/.agents that real adoption produces. So the restore-version-home test copies a symlink-free dir and the dangling-symlink bug is structurally unreachable. Also missing: --purge; dangling-after-move; ~/.claude.json home-file restore; launcher release; remove-dangling; a real leave-foreign symlink; any error path; double-run idempotency.

MEDIUM — ~/.claude.json restores merged content, not the user's original. Adoption via switchHomeFileSymlinks never backs up the original; it merges + writes the merged JSON then symlinks in place. Uninstall's cpSync restores agents-cli's merged file, not the pristine pre-adoption one. Usually harmless (auth preserved) but not a true byte-for-byte reversal — worth a doc note since the doc claims the machine is "left as it was before agents-cli was installed."

MEDIUM — --purge --yes nukes everything with no purge-specific guard. Confirm lives in the command layer and is skipped by --yes, so agents uninstall --purge --yes in a script irreversibly deletes ~/.agents (sessions, binaries, secrets metadata, backups, trash safety-net) with zero prompt. Consider a distinct --confirm-purge / typed confirmation that --yes does not satisfy.

Verified correct: ordering (restore-backup renames the backup out of ~/.agents before disposal); second-run idempotency is a safe no-op; numeric backup sort in newestBackupDir; the two shims.ts exports are minimal; uninstall correctly added to SETUP_EXEMPT_COMMANDS.

Bottom line: fix the two --purge data-loss paths (error-gate disposal + prefer rename/copy-then-unlink) and the dangling-symlink restore, and make the test fixture create real resource symlinks so these are actually covered. The rest is nits/docs.

[muqsitnawaz]

Closing in favor of #1310, which supersedes this and carries the same agents uninstall feature with the data-loss defects from my earlier review fixed (error-gated --purge disposal, EXDEV-safe backup restore, dangling-symlink pruning, and a fixture that creates real resource symlinks so those paths are actually covered). Thanks for the original architecture here, @tenxxor — the read-only planUninstall + mutating executeUninstall split carried straight over into #1310. This also has an unaddressed test-windows failure. Continuing the work in #1310.