@oddessentials/agent-guild 0.14.0 → 0.15.0

package/README.md

@@ -34,6 +34,10 @@ agent-guild
 The page opens in your browser. Pick a provider, press **New**, and you are
 in a live terminal.
 
+Want to look around first? The [interactive web demo](https://oddessentials.github.io/agent-guild/)
+uses simulated sessions and usage data in your browser; it never runs commands
+or connects to a local session manager.
+
 **You need** Node.js 22 or newer on Windows 10 1809+, macOS 11+ or Linux
 (x64 or arm64), and each coding tool you want to use, signed in on its own.
 Agent Guild installs the tools for you but never handles your sign-in. No

package/config/providers.default.json

@@ -21,10 +21,10 @@
       "install": "curl -fsSL https://claude.ai/install.sh | bash",
       "npmNote": "npm installs the same native build as Anthropic's installer.",
       "channels": {
-        "native": { "paths": ["~/.local/bin/claude", "~/.local/share/claude"], "update": ["update"], "uninstall": "rm -f ~/.local/bin/claude && rm -rf ~/.local/share/claude" },
+        "native": { "paths": ["~/.local/bin/claude", "~/.local/share/claude"], "update": ["update"], "remove": ["~/.local/bin/claude", "~/.local/share/claude"] },
         "brew": { "names": ["claude-code", "claude-code@latest"] },
         "winget": { "id": "Anthropic.ClaudeCode" },
-        "legacy": { "paths": ["~/.claude/local"], "guidance": "This copy comes from an older Claude Code installer. Remove ~/.claude/local and reinstall with the current installer.", "uninstall": "rm -rf ~/.claude/local" }
+        "legacy": { "paths": ["~/.claude/local"], "guidance": "This copy comes from an older Claude Code installer. Remove ~/.claude/local and reinstall with the current installer.", "remove": ["~/.claude/local"] }
       },
       "docs": "https://code.claude.com/docs/en/setup",
       "usageUrl": "https://claude.ai/settings/usage",
@@ -33,9 +33,9 @@
       "win32": {
         "install": "irm https://claude.ai/install.ps1 | iex",
         "channels": {
-          "native": { "paths": ["~/.local/bin/claude", "~/.local/share/claude"], "update": ["update"], "uninstall": "Remove-Item -Path \"$env:USERPROFILE\\.local\\bin\\claude.exe\" -Force; Remove-Item -Path \"$env:USERPROFILE\\.local\\share\\claude\" -Recurse -Force" },
+          "native": { "paths": ["~/.local/bin/claude", "~/.local/share/claude"], "update": ["update"], "remove": ["~/.local/bin/claude.exe", "~/.local/share/claude"] },
           "winget": { "id": "Anthropic.ClaudeCode" },
-          "legacy": { "paths": ["~/.claude/local"], "guidance": "This copy comes from an older Claude Code installer. Remove ~/.claude/local and reinstall with the current installer.", "uninstall": "Remove-Item -Recurse -Force \"$env:USERPROFILE\\.claude\\local\"" }
+          "legacy": { "paths": ["~/.claude/local"], "guidance": "This copy comes from an older Claude Code installer. Remove ~/.claude/local and reinstall with the current installer.", "remove": ["~/.claude/local"] }
         }
       }
     },
@@ -59,7 +59,7 @@
       "install": "curl -fsSL https://chatgpt.com/codex/install.sh | sh",
       "npmNote": "npm installs the native Codex binary.",
       "channels": {
-        "native": { "paths": ["~/.local/bin/codex", "~/.codex/packages/standalone"], "update": ["update"] },
+        "native": { "paths": ["~/.local/bin/codex", "~/.codex/packages/standalone"], "update": ["update"], "remove": ["~/.local/bin/codex", "~/.local/bin/codex-code-mode-host", "~/.codex/packages/standalone"] },
         "brew": { "names": ["codex"] },
         "winget": { "id": "OpenAI.Codex" }
       },
@@ -70,7 +70,7 @@
       "win32": {
         "install": "powershell -ExecutionPolicy ByPass -c \"irm https://chatgpt.com/codex/install.ps1 | iex\"",
         "channels": {
-          "native": { "paths": ["~/AppData/Local/Programs/OpenAI/Codex/bin", "~/.codex/packages/standalone"], "update": ["update"] },
+          "native": { "paths": ["~/AppData/Local/Programs/OpenAI/Codex/bin", "~/.codex/packages/standalone"], "update": ["update"], "remove": ["~/AppData/Local/Programs/OpenAI/Codex/bin", "~/.codex/packages/standalone"] },
           "winget": { "id": "OpenAI.Codex" }
         }
       }
@@ -90,7 +90,8 @@
       "monogram": "G",
       "install": "curl -fsSL https://antigravity.google/cli/install.sh | bash",
       "channels": {
-        "native": { "paths": ["~/.local/bin/agy"], "update": ["update"], "uninstall": "rm -f ~/.local/bin/agy" }
+        "native": { "paths": ["~/.local/bin/agy"], "update": ["update"], "remove": ["~/.local/bin/agy"] },
+        "brew": { "names": ["antigravity-cli"], "autoUpdates": true }
       },
       "docs": "https://antigravity.google/docs/cli/install",
       "billingUrl": "https://one.google.com/settings",
@@ -98,7 +99,7 @@
       "win32": {
         "install": "irm https://antigravity.google/cli/install.ps1 | iex",
         "channels": {
-          "native": { "paths": ["~/AppData/Local/agy/bin"], "update": ["update"], "uninstall": "Remove-Item -Path \"$env:LOCALAPPDATA\\agy\" -Recurse -Force" }
+          "native": { "paths": ["~/AppData/Local/agy/bin"], "update": ["update"], "remove": ["~/AppData/Local/agy"] }
         }
       }
     },
@@ -121,7 +122,8 @@
       "install": "curl -fsSL https://x.ai/cli/install.sh | bash",
       "npmNote": "npm installs the native grok binary into ~/.grok/bin.",
       "channels": {
-        "native": { "paths": ["~/.grok/bin", "~/.grok/downloads"], "update": ["update"], "sharedWithNpm": true }
+        "native": { "paths": ["~/.grok/bin", "~/.grok/downloads"], "update": ["update"], "remove": ["~/.grok/bin", "~/.grok/downloads", "~/.grok/completions"], "links": ["~/.local/bin/grok", "~/.local/bin/agent", "/usr/local/bin/grok", "/usr/local/bin/agent"], "sharedWithNpm": true },
+        "brew": { "names": ["grok-build"] }
       },
       "docs": "https://docs.x.ai/build/overview",
       "usageUrl": "https://grok.com/?_s=usage",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Launch and watch AI coding-assistant terminal sessions from one local web page. A bundled session manager owns the terminals so the page can close and reconnect.",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,8 @@
     "manager": "node bin/agent-guild.mjs start",
     "stop": "node bin/agent-guild.mjs stop",
     "status": "node bin/agent-guild.mjs status",
+    "demo:build": "node docs/demo/build.mjs",
+    "demo:check": "node docs/demo/check.mjs",
     "test": "node --test --test-concurrency=1"
   },
   "dependencies": {

package/src/manager/install-channels.mjs

@@ -35,6 +35,12 @@ export function homeDir(env, platform) {
   return (platform === 'win32' ? env.USERPROFILE : env.HOME) || os.homedir();
 }
 
+export function homeRelative(p, env, platform) {
+  const m = pathModule(platform);
+  const home = homeDir(env, platform);
+  return isInside(p, home, platform) ? `~${m.sep}${m.relative(home, p)}` : p;
+}
+
 export function expandHome(p, env, platform) {
   const m = pathModule(platform);
   if (p === '~') return homeDir(env, platform);
@@ -150,17 +156,6 @@ export function formatCommand(file, args) {
   return [file, ...args].map((a) => (/\s/.test(a) ? `"${a}"` : a)).join(' ');
 }
 
-function shellQuote(arg, platform) {
-  if (platform === 'win32') return /^[\w\\/.:=+-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, "''")}'`;
-  return /^[\w/.:=,+@%-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, "'\\''")}'`;
-}
-
-export function shellCommand(file, args, platform) {
-  const command = shellQuote(file, platform);
-  const line = [command, ...args.map((arg) => shellQuote(arg, platform))].join(' ');
-  return platform === 'win32' && command !== file ? `& ${line}` : line;
-}
-
 export function classifyInstall({
   resolvedPath, provider, env = process.env, platform = process.platform, fsx = defaultFsx, npmOnPath = null, wingetOnPath = null,
 }) {
@@ -180,8 +175,9 @@ export function classifyInstall({
 
   const brew = brewOwner({ realPath, names: channels.brew?.names || [], platform, fsx });
   if (brew) {
-    const owned = { brewPrefix: brew.prefix, token: brew.token, cask: brew.cask };
+    const owned = { brewPrefix: brew.prefix, token: brew.token, cask: brew.cask, brewFile: brew.brew };
     if (!brew.brew) return result('brew', { ...owned, guidance: `Installed by Homebrew under ${brew.prefix}, but brew was not found at ${brew.prefix}/bin/brew.` });
+    if (channels.brew.autoUpdates) return result('brew', { ...owned, guidance: `${provider.tool} updates itself; Homebrew does not upgrade it.` });
     return result('brew', { ...owned, update: { file: brew.brew, args: brew.cask ? ['upgrade', '--cask', brew.token] : ['upgrade', brew.token] } });
   }
 
@@ -227,18 +223,48 @@ export function installationKey(install, provider, platform, fsx = defaultFsx) {
   }
 }
 
-export function removalCommand(install, provider, platform) {
+function ownedPaths(entries, env, platform) {
+  const m = pathModule(platform);
+  const home = homeDir(env, platform);
+  return (entries || []).map((entry) => expandHome(entry, env, platform))
+    .filter((p) => m.isAbsolute(p) && isInside(p, home, platform) && m.relative(home, p).split(/[\\/]+/).length >= 2)
+    .map((p) => m.normalize(p));
+}
+
+// Links may sit outside home, e.g. /usr/local/bin: the runner deletes one only
+// when it is a symlink into the removed paths, which stay inside home.
+function linkPaths(entries, env, platform) {
+  const m = pathModule(platform);
+  return (entries || []).map((entry) => expandHome(entry, env, platform))
+    .filter((p) => (platform === 'win32' ? /^(?:[a-z]:[\\/]|[\\/]{2})/i.test(p) : m.isAbsolute(p)))
+    .map((p) => m.normalize(p));
+}
+
+function removalFor(channel, env, platform) {
+  const remove = ownedPaths(channel?.remove, env, platform);
+  return remove.length > 0 ? { remove, links: linkPaths(channel.links, env, platform) } : null;
+}
+
+export function uninstallPlan(install, provider, env, platform, fsx = defaultFsx) {
+  const channels = provider.channels || {};
+  const plan = (run, removal = null, launcher = null) => ({ run, remove: removal?.remove || [], links: removal?.links || [], launcher });
   switch (install.channel) {
-    case 'npm':
-      return install.update ? shellCommand(install.update.file, ['uninstall', '-g', '--prefix', install.prefix, provider.package], platform) : null;
+    case 'npm': {
+      if (!install.update) return null;
+      const run = { file: install.update.file, args: ['uninstall', '-g', '--prefix', install.prefix, provider.package] };
+      const removal = channels.native?.sharedWithNpm ? removalFor(channels.native, env, platform) : null;
+      const launcher = removal ? knownLaunchers({ provider, command: provider.command, env, platform, fsx })[0] : null;
+      return plan(run, removal, launcher);
+    }
     case 'brew':
-      return install.update ? shellCommand(install.update.file, install.cask ? ['uninstall', '--cask', install.token] : ['uninstall', install.token], platform) : null;
+      return install.brewFile ? plan({ file: install.brewFile, args: install.cask ? ['uninstall', '--cask', install.token] : ['uninstall', install.token] }) : null;
     case 'winget':
-      return shellCommand('winget', ['uninstall', '--id', install.wingetId, '--exact'], platform);
+      return install.update ? plan({ file: install.update.file, args: ['uninstall', '--id', install.wingetId, '--exact'] }) : null;
     case 'native':
-      return provider.channels?.native?.uninstall || null;
-    case 'legacy':
-      return provider.channels?.legacy?.uninstall || null;
+    case 'legacy': {
+      const removal = removalFor(channels[install.channel], env, platform);
+      return removal ? plan(null, removal, install.resolvedPath) : null;
+    }
     default:
       return null;
   }
@@ -267,7 +293,13 @@ export function listInstallations({
   const add = (file, isOnPath) => {
     const install = classifyInstall({ resolvedPath: file, provider, env, platform, fsx, npmOnPath, wingetOnPath });
     const key = installationKey(install, provider, platform, fsx);
-    if (!installs.has(key)) installs.set(key, { ...install, key, onPath: isOnPath, removeCommand: removalCommand(install, provider, platform) });
+    const existing = installs.get(key);
+    if (!existing) installs.set(key, { ...install, key, onPath: isOnPath, uninstall: uninstallPlan(install, provider, env, platform, fsx) });
+    // A shared native copy also needs its npm owner removed, whichever comes first on PATH.
+    else if (install.channel === 'npm' && !existing.uninstall?.run) {
+      existing.uninstall = uninstallPlan(install, provider, env, platform, fsx);
+      if (!existing.uninstall) existing.guidance = install.guidance;
+    }
   };
   for (const file of onPath) add(file, true);
   for (const file of known) add(file, false);

package/src/manager/providers.mjs

@@ -11,8 +11,9 @@ import { EventEmitter } from 'node:events';
 import { fileURLToPath } from 'node:url';
 import { resolveCommand, resolveAllCommands, pathKey, buildSpawnSpec, runSpec } from './command-resolver.mjs';
 import { compareVersions, probeVersion, fetchManifest, latestVersion, DEFAULT_NPM_REGISTRY } from './versions.mjs';
-import { CHANNEL_LABELS, classifyInstall, expandHome, formatCommand, knownLaunchers, listInstallations, platformDependency, updateHelpAccepted } from './install-channels.mjs';
+import { CHANNEL_LABELS, classifyInstall, expandHome, formatCommand, homeRelative, knownLaunchers, listInstallations, platformDependency, updateHelpAccepted } from './install-channels.mjs';
 import { weavePaths } from './shell-env.mjs';
+import { RUNNER, encodePlan } from './uninstall.mjs';
 import { paths } from './config.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -81,17 +82,18 @@ function normalizeChannels(raw) {
     out.native = {
       paths: stringList(raw.native.paths),
       update: stringList(raw.native.update),
-      uninstall: raw.native.uninstall ? String(raw.native.uninstall) : null,
+      remove: stringList(raw.native.remove),
+      links: stringList(raw.native.links),
       sharedWithNpm: raw.native.sharedWithNpm === true,
     };
   }
-  if (raw.brew && typeof raw.brew === 'object') out.brew = { names: stringList(raw.brew.names) };
+  if (raw.brew && typeof raw.brew === 'object') out.brew = { names: stringList(raw.brew.names), autoUpdates: raw.brew.autoUpdates === true };
   if (raw.winget && typeof raw.winget === 'object' && raw.winget.id) out.winget = { id: String(raw.winget.id) };
   if (raw.legacy && typeof raw.legacy === 'object') {
     out.legacy = {
       paths: stringList(raw.legacy.paths),
       guidance: raw.legacy.guidance ? String(raw.legacy.guidance) : null,
-      uninstall: raw.legacy.uninstall ? String(raw.legacy.uninstall) : null,
+      remove: stringList(raw.legacy.remove),
     };
   }
   return out;
@@ -225,6 +227,12 @@ export function loadProviders({ userFile, platform = process.platform } = {}) {
   return { providers, warnings };
 }
 
+// Why a copy cannot be removed here. An unrecognised copy's own guidance is about updating it.
+function removalGuidance(provider, install, where) {
+  if (install.channel !== 'unknown' && install.guidance) return install.guidance;
+  return `Agent Guild does not know how ${provider.tool} at ${where} was installed. Remove it the way you installed it.`;
+}
+
 export class ProviderRegistry extends EventEmitter {
   /**
    * @param {object} opts
@@ -408,7 +416,7 @@ export class ProviderRegistry extends EventEmitter {
     if (changed) this.emit('updated');
   }
 
-  async finishInstall(id, { exitCode = null, kind = 'update' } = {}) {
+  async finishInstall(id, { exitCode = null, kind = 'update', path: removed = null } = {}) {
     const provider = this.get(id);
     if (!provider) return;
     const before = this.versions.get(id)?.installed ?? null;
@@ -418,6 +426,7 @@ export class ProviderRegistry extends EventEmitter {
     if (!entry) return;
     let outcome;
     if (exitCode !== 0) outcome = 'failed';
+    else if (kind === 'uninstall') outcome = this.installsFor(provider).some((i) => i.resolvedPath === removed) ? 'remaining' : 'removed';
     else if (kind === 'install') outcome = this.resolve(provider) ? 'installed' : 'missing';
     else if (entry.installed === null) outcome = 'done';
     else outcome = entry.installed !== before ? 'updated' : 'unchanged';
@@ -509,13 +518,13 @@ export class ProviderRegistry extends EventEmitter {
   installWarnings(provider, installs) {
     const label = (i) => [CHANNEL_LABELS[i.channel], i.version && `v${i.version}`].filter(Boolean).join(' ');
     const active = installs.find((i) => i.active);
-    if (!active) return installs.map((i) => `A copy of ${provider.tool} exists at ${i.path}, but its folder is not on PATH.`);
+    if (!active) return installs.map((i) => `A copy of ${provider.tool} exists at ${i.displayPath}, but its folder is not on PATH.`);
     const warnings = [];
     if (installs.length > 1) {
-      warnings.push(`${installs.length} copies of ${provider.tool} are installed. The one in use is ${label(active)} at ${active.path}.`);
+      warnings.push(`${installs.length} copies of ${provider.tool} are installed. The one in use is ${label(active)} at ${active.displayPath}.`);
     }
     const newer = installs.find((i) => i.newer);
-    if (newer) warnings.push(`An older copy comes first on PATH: ${label(active)} is in use while ${label(newer)} is installed at ${newer.path}.`);
+    if (newer) warnings.push(`An older copy comes first on PATH: ${label(active)} is in use while ${label(newer)} is installed at ${newer.displayPath}.`);
     return warnings;
   }
 
@@ -587,17 +596,23 @@ export class ProviderRegistry extends EventEmitter {
     const latest = versions?.latest ?? null;
     const channel = this.channelFor(provider, resolvedPath);
     const update = this.updateFor(provider, channel);
+    const shown = (file) => homeRelative(file, { ...this.env, ...provider.env }, this.platform);
     const installs = this.installsFor(provider, resolvedPath).map((install) => {
       const active = install.resolvedPath === resolvedPath;
       const copy = active ? { version: installed, status: versions?.versionStatus ?? null } : versions?.copies?.[install.resolvedPath];
       return {
         path: install.resolvedPath,
+        displayPath: shown(install.resolvedPath),
         channel: install.channel,
         version: copy?.version ?? null,
         versionStatus: copy?.status ?? null,
         active,
         onPath: install.onPath,
-        removeCommand: install.removeCommand,
+        uninstall: install.uninstall && {
+          command: install.uninstall.run ? formatCommand(install.uninstall.run.file, install.uninstall.run.args) : null,
+          remove: install.uninstall.remove.map(shown),
+        },
+        uninstallGuidance: install.uninstall ? null : removalGuidance(provider, install, shown(install.resolvedPath)),
       };
     });
     const inUse = installs.find((i) => i.active)?.version;
@@ -683,6 +698,18 @@ export class ProviderRegistry extends EventEmitter {
     return { spec: buildSpawnSpec(update.file, args, this.env, this.platform), channel: channel.channel };
   }
 
+  uninstallSpec(provider, copyPath) {
+    const install = this.listInstalls(provider).find((i) => i.resolvedPath === copyPath);
+    if (!install) throw refusal(404, 'unknown_copy', `${provider.tool} has no copy at ${copyPath}`);
+    if (!install.uninstall) {
+      throw refusal(400, 'not_removable', removalGuidance(provider, install, copyPath));
+    }
+    return {
+      spec: buildSpawnSpec(process.execPath, [RUNNER, encodePlan(install.uninstall)], this.env, this.platform),
+      channel: install.channel,
+    };
+  }
+
   async installSpec(provider) {
     if (!provider.package) {
       const err = new Error(`${provider.tool} has no npm package configured; install it by hand: ${provider.install || provider.docs || 'see its documentation'}`);

package/src/manager/server.mjs

@@ -290,6 +290,12 @@ export function createManagerServer({
       const session = await manager.install(installMatch[1], { force: body.force === true });
       return sendJson(res, 201, { session: session.toJSON() });
     }
+    const uninstallMatch = route.match(/^\/providers\/([a-z0-9][a-z0-9_-]{0,31})\/uninstall$/);
+    if (uninstallMatch && method === 'POST') {
+      const body = await readJsonBody(req);
+      const session = manager.uninstall(uninstallMatch[1], body.path, { force: body.force === true });
+      return sendJson(res, 201, { session: session.toJSON() });
+    }
     if (route === '/sessions' && method === 'GET') {
       return sendJson(res, 200, { sessions: manager.list() });
     }

package/src/manager/session-manager.mjs

@@ -104,6 +104,10 @@ export class SessionManager extends EventEmitter {
     const workDir = this.resolveCwd(cwd);
     const signIn = this.registry.account(provider, account);
     const hooks = this.sessionHooks ? await this.sessionHooks.launch(provider) : { args: [], reporting: null };
+    // Checked after the await, so an install that started meanwhile is seen.
+    if (this.installing.has(provider.id) || this.installsRunningFor(provider.id) > 0) {
+      throw httpError(409, `${provider.tool} is being installed, updated or removed; start it once that finishes`, 'install_in_progress');
+    }
     const spawnSpec = this.registry.spawnSpec(provider, args || [], resumeId, hooks.args);
     this.prepareAccount(provider, signIn, { hooksSupplied: hooks.args.length > 0 });
     const sessionName = cleanName(name) || (provider.accounts.length > 1 ? `${provider.tool} · ${signIn.label}` : null);
@@ -132,21 +136,7 @@ export class SessionManager extends EventEmitter {
    * set, because replacing a tool under a running process can break it.
    */
   async install(providerId, { force = false } = {}) {
-    const provider = this.registry.get(String(providerId || ''));
-    if (!provider) throw httpError(404, `unknown provider "${providerId}"`, 'unknown_provider');
-    if (this.closing) throw httpError(503, 'the session manager is stopping', 'manager_stopping');
-    const guard = () => {
-      const running = this.runningFor(provider.id);
-      if (running > 0 && !force) {
-        const err = httpError(409, `${running} ${provider.tool} session(s) are running; updating the tool now may break them`, 'provider_in_use');
-        err.running = running;
-        throw err;
-      }
-    };
-    guard();
-    if (this.installing.has(provider.id) || this.installsRunningFor(provider.id) > 0) {
-      throw httpError(409, `${provider.tool} is already being installed or updated`, 'install_in_progress');
-    }
+    const { provider, guard } = this._installGuard(providerId, force, 'updating the tool now may break them');
     this.installing.add(provider.id);
     try {
       if (this.registry.resolve(provider)) {
@@ -163,9 +153,37 @@ export class SessionManager extends EventEmitter {
     }
   }
 
+  uninstall(providerId, copyPath, { force = false } = {}) {
+    if (typeof copyPath !== 'string' || !copyPath) throw httpError(400, 'path must name the copy to remove', 'bad_request');
+    const { provider, guard } = this._installGuard(providerId, force, 'removing the tool now may break them');
+    const { spec, channel } = this.registry.uninstallSpec(provider, copyPath);
+    guard();
+    const name = `Uninstall ${provider.tool} (${CHANNEL_LABELS[channel]})`;
+    return this._spawn({ provider, spawnSpec: spec, cwd: os.homedir(), name, task: 'install', installKind: 'uninstall', installPath: copyPath });
+  }
+
+  _installGuard(providerId, force, risk) {
+    const provider = this.registry.get(String(providerId || ''));
+    if (!provider) throw httpError(404, `unknown provider "${providerId}"`, 'unknown_provider');
+    if (this.closing) throw httpError(503, 'the session manager is stopping', 'manager_stopping');
+    const guard = () => {
+      const running = this.runningFor(provider.id);
+      if (running > 0 && !force) {
+        const err = httpError(409, `${running} ${provider.tool} session(s) are running; ${risk}`, 'provider_in_use');
+        err.running = running;
+        throw err;
+      }
+    };
+    guard();
+    if (this.installing.has(provider.id) || this.installsRunningFor(provider.id) > 0) {
+      throw httpError(409, `${provider.tool} is already being installed, updated or removed`, 'install_in_progress');
+    }
+    return { provider, guard };
+  }
+
   installsRunningFor(providerId) {
     let n = 0;
-    for (const s of this.sessions.values()) if (s.status === 'running' && s.task === 'install' && s.provider.id === providerId) n++;
+    for (const s of [...this.sessions.values(), ...this.exiting]) if (s.status === 'running' && s.task === 'install' && s.provider.id === providerId) n++;
     return n;
   }
 
@@ -214,7 +232,7 @@ export class SessionManager extends EventEmitter {
 
   runningFor(providerId) {
     let n = 0;
-    for (const s of this.sessions.values()) if (s.status === 'running' && s.task === null && s.provider.id === providerId) n++;
+    for (const s of [...this.sessions.values(), ...this.exiting]) if (s.status === 'running' && s.task === null && s.provider.id === providerId) n++;
     return n;
   }
 
@@ -226,7 +244,7 @@ export class SessionManager extends EventEmitter {
   }
 
   _spawn({
-    provider, description = this.registry.describe(provider), spawnSpec, cwd, cols, rows, name, resume = null, task = null, installKind = null, account = null,
+    provider, description = this.registry.describe(provider), spawnSpec, cwd, cols, rows, name, resume = null, task = null, installKind = null, installPath = null, account = null,
     extraEnv = null, dropEnv = null, clone = null, reporting = null,
   }) {
     if (this.closing) throw httpError(503, 'the session manager is stopping', 'manager_stopping');
@@ -285,7 +303,7 @@ export class SessionManager extends EventEmitter {
     session.on('warning', (msg) => console.warn(`[session ${id}] ${msg}`));
     if (task === 'install') {
       session.on('exit', () => {
-        this.registry.finishInstall(provider.id, { exitCode: session.exitCode, kind: installKind }).catch(() => {});
+        this.registry.finishInstall(provider.id, { exitCode: session.exitCode, kind: installKind, path: installPath }).catch(() => {});
       });
     }
     this.sessions.set(id, session);

package/src/manager/uninstall.mjs

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { buildSpawnSpec } from './command-resolver.mjs';
+import { formatCommand } from './install-channels.mjs';
+
+export const RUNNER = fileURLToPath(import.meta.url);
+
+export function encodePlan(plan) {
+  return Buffer.from(JSON.stringify(plan)).toString('base64url');
+}
+
+function comparable(p, platform) {
+  const m = platform === 'win32' ? path.win32 : path.posix;
+  const out = m.normalize(p.replace(/^\\\\\?\\/, ''));
+  return platform === 'win32' ? out.toLowerCase() : out;
+}
+
+function inside(file, dir, platform) {
+  const m = platform === 'win32' ? path.win32 : path.posix;
+  const f = comparable(file, platform);
+  const d = comparable(dir, platform);
+  return f === d || f.startsWith(d + m.sep);
+}
+
+function within(file, dirs, platform) {
+  return dirs.some((dir) => inside(file, dir, platform));
+}
+
+function linkTarget(file) {
+  try {
+    return fs.lstatSync(file).isSymbolicLink() ? path.resolve(path.dirname(file), fs.readlinkSync(file).replace(/^\\\\\?\\/, '')) : null;
+  } catch {
+    return null;
+  }
+}
+
+function exists(file) {
+  try {
+    fs.lstatSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function firstLink(file) {
+  const steps = [];
+  for (let p = file; ; p = path.dirname(p)) {
+    steps.unshift(p);
+    if (path.dirname(p) === p) break;
+  }
+  return steps.find((p) => linkTarget(p) !== null) ?? null;
+}
+
+function launchChain(launcher) {
+  const chain = [];
+  let file = launcher;
+  for (let hops = 0; hops < 40 && exists(file); hops++) {
+    chain.push(file);
+    const link = firstLink(file);
+    if (!link) break;
+    chain.push(link);
+    file = path.join(linkTarget(link), path.relative(link, file));
+  }
+  return chain;
+}
+
+function removeFile(file) {
+  fs.rmSync(file, { recursive: true, force: true, maxRetries: 3 });
+}
+
+export function runPlan(
+  { run = null, remove = [], links = [], launcher = null },
+  { env = process.env, platform = process.platform, log = console.log, rm = removeFile } = {},
+) {
+  if (run) {
+    log(`> ${formatCommand(run.file, run.args)}`);
+    const spec = buildSpawnSpec(run.file, run.args, env, platform);
+    const verbatim = typeof spec.args === 'string';
+    const result = spawnSync(spec.file, verbatim ? [spec.args] : spec.args, { stdio: 'inherit', env, windowsVerbatimArguments: verbatim });
+    if (result.error) {
+      log(`Could not run ${run.file}: ${result.error.message}`);
+      return 1;
+    }
+    if (result.status !== 0) return result.status ?? 1;
+  }
+  const chain = launcher ? launchChain(launcher) : [];
+  const holdsChain = (file) => chain.some((kept) => inside(kept, file, platform));
+  const inChain = (file) => chain.some((kept) => comparable(kept, platform) === comparable(file, platform));
+  const del = (file) => {
+    try {
+      rm(file);
+    } catch (err) {
+      throw Object.assign(err, { file });
+    }
+  };
+  const prune = (dir) => {
+    for (const name of fs.readdirSync(dir)) {
+      const file = path.join(dir, name);
+      if (!holdsChain(file)) del(file);
+      else if (!inChain(file) && linkTarget(file) === null) prune(file);
+    }
+  };
+  const owned = [];
+  const deferred = [];
+  try {
+    for (const file of [...remove, ...links]) {
+      const target = linkTarget(file);
+      if (target === null && !exists(file)) continue;
+      if (target !== null && !within(target, remove, platform)) {
+        log(`Kept ${file}: it links to ${target}, outside this installation.`);
+        continue;
+      }
+      if (target === null && links.includes(file)) {
+        log(`Kept ${file}: it is not a link to this installation.`);
+        continue;
+      }
+      owned.push(file);
+      if (!holdsChain(file)) {
+        del(file);
+        log(`Removed ${file}`);
+        continue;
+      }
+      deferred.push(file);
+      if (target === null && fs.lstatSync(file).isDirectory()) prune(file);
+    }
+    for (const file of [...new Set([...chain].reverse())]) {
+      if (within(file, owned, platform) && exists(file)) del(file);
+    }
+    for (const file of deferred.sort((a, b) => b.length - a.length)) {
+      if (exists(file)) del(file);
+      log(`Removed ${file}`);
+    }
+  } catch (err) {
+    const code = err.code === 'ENOTDIR' && err.syscall === 'scandir' ? 'EPERM' : err.code;
+    const reason = { EBUSY: 'it is in use', EPERM: 'it is in use or protected', EACCES: 'permission was denied' }[code] || err.message;
+    log(`Could not remove ${err.path || err.file}: ${reason}. Stopped there. Close any program using it, then uninstall again.`);
+    return 1;
+  }
+  return 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === RUNNER) {
+  const plan = JSON.parse(Buffer.from(process.argv[2] || '', 'base64url').toString('utf8') || '{}');
+  process.exitCode = runPlan(plan);
+}

package/web/app.js

@@ -556,7 +556,7 @@ function renderProviders() {
     update.title = provider.updateCommand ? `Run "${provider.updateCommand}" in a session` : '';
     update.addEventListener('click', () => installProvider(provider, node));
     renderHint(hint, provider);
-    renderCopies(node.querySelector('.copies'), provider);
+    renderCopies(node.querySelector('.copies'), provider, node);
     renderVendorLinks(node, provider);
     renderAccounts(node, provider);
     renderUsage(node, provider);
@@ -572,16 +572,17 @@ function renderProviders() {
 
 const openCopies = new Set();
 
-function renderCopies(box, provider) {
+function renderCopies(box, provider, card) {
   const installs = provider.installs || [];
   const warnings = provider.warnings || [];
-  box.hidden = warnings.length === 0;
+  box.hidden = warnings.length === 0 && !installs.some((i) => i.uninstall);
   if (box.hidden) return;
+  box.classList.toggle('warned', warnings.length > 0);
   const inUse = installs.some((i) => i.active);
   const older = installs.some((i) => i.newer);
   box.querySelector('summary').textContent = !inUse
     ? 'A copy exists off PATH'
-    : `${installs.length} copies installed${older ? ' · older copy in use' : ''}`;
+    : installs.length === 1 ? 'Installation' : `${installs.length} copies installed${older ? ' · older copy in use' : ''}`;
   box.open = openCopies.has(provider.id);
   box.addEventListener('toggle', () => (box.open ? openCopies.add(provider.id) : openCopies.delete(provider.id)));
   const line = (className, ...content) => {
@@ -596,14 +597,25 @@ function renderCopies(box, provider) {
     return item;
   }), ...installs.map((install) => {
     const item = document.createElement('li');
-    const name = [CHANNEL_LABELS[install.channel] || install.channel, install.version && `v${install.version}`, install.active ? 'in use' : 'not in use'];
-    item.append(line('copy-name', name.filter(Boolean).join(' · ')), line('copy-path', install.path));
-    if (install.removeCommand) {
-      const code = document.createElement('code');
-      code.textContent = install.removeCommand;
-      item.append(line('copy-remove', 'To remove it: ', code));
+    const channel = CHANNEL_LABELS[install.channel] || install.channel;
+    const name = [channel, install.version && `v${install.version}`, installs.length > 1 && (install.active ? 'in use' : 'not in use')];
+    const head = line('copy-head', line('copy-name', name.filter(Boolean).join(' · ')));
+    const where = line('copy-path', install.displayPath);
+    where.title = install.path;
+    item.append(head, where);
+    if (install.uninstall) {
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.className = 'btn danger copy-uninstall';
+      button.textContent = 'Uninstall';
+      button.setAttribute('aria-label', `Uninstall the ${channel} copy of ${provider.tool} at ${install.displayPath}`);
+      button.title = install.uninstall.command
+        ? [`Runs ${install.uninstall.command}`, ...install.uninstall.remove.map((p) => `then deletes ${p}`)].join('\n')
+        : ['Deletes', ...install.uninstall.remove].join('\n');
+      button.addEventListener('click', () => uninstallCopy(provider, card, install));
+      head.append(button);
     } else {
-      item.append(line('copy-remove', 'No removal command is known for this copy.'));
+      item.append(line('copy-remove', install.uninstallGuidance));
     }
     return item;
   }));
@@ -1643,9 +1655,10 @@ function installNote(provider) {
   const last = provider.lastInstall;
   if (!last) return '';
   if (last.outcome === 'failed') {
-    const what = last.kind === 'install' ? 'Install' : 'Update';
+    const what = { install: 'Install', uninstall: 'Uninstall' }[last.kind] || 'Update';
     return last.exitCode === null ? `${what} failed` : `${what} failed (exit ${last.exitCode})`;
   }
+  if (last.kind === 'uninstall') return last.outcome === 'remaining' ? 'Uninstalled copy is still present' : '';
   if (last.verification === 'failed') return `Installation completed, but ${provider.tool} verification failed`;
   if (last.outcome === 'missing') return 'Installed, but not found on PATH';
   if (last.outcome === 'unchanged') return 'No version change after update';
@@ -1671,10 +1684,20 @@ function providerState(provider) {
   return parts.join(' · ');
 }
 
-async function installProvider(provider, card, { force = false } = {}) {
+function uninstallCopy(provider, card, install) {
+  const what = install.uninstall.command
+    ? [`Runs: ${install.uninstall.command}`, ...install.uninstall.remove.map((p) => `Then deletes: ${p}`)]
+    : install.uninstall.remove.map((p) => `Deletes: ${p}`);
+  if (!confirm([`Uninstall ${provider.tool} from ${install.displayPath}?`, '', ...what, '', 'Your sign-in, settings and history are kept.'].join('\n'))) return;
+  return installProvider(provider, card, { path: install.path });
+}
+
+async function installProvider(provider, card, { force = false, path = null } = {}) {
   card.classList.add('busy');
   try {
-    const { session } = await api('POST', `/providers/${provider.id}/install`, { force });
+    const { session } = path
+      ? await api('POST', `/providers/${provider.id}/uninstall`, { path, force })
+      : await api('POST', `/providers/${provider.id}/install`, { force });
     upsertSession(session);
     openPanel(session.id);
   } catch (err) {
@@ -1683,8 +1706,9 @@ async function installProvider(provider, card, { force = false } = {}) {
       card.classList.remove('busy');
       const n = err.running;
       const what = `${n} ${provider.tool} session${n === 1 ? ' is' : 's are'} running`;
-      if (confirm(`${what}. Updating ${provider.tool} while it runs can break ${n === 1 ? 'that session' : 'those sessions'}. Update anyway?`)) {
-        return installProvider(provider, card, { force: true });
+      const [doing, verb] = path ? ['Removing', 'Uninstall'] : ['Updating', 'Update'];
+      if (confirm(`${what}. ${doing} ${provider.tool} while it runs can break ${n === 1 ? 'that session' : 'those sessions'}. ${verb} anyway?`)) {
+        return installProvider(provider, card, { force: true, path });
       }
       return;
     }

package/web/index.html

@@ -272,6 +272,10 @@
         <a class="console-link usage-link" target="_blank" rel="noopener noreferrer">Usage</a>
         <a class="console-link billing-link" target="_blank" rel="noopener noreferrer">Billing</a>
       </div>
+      <details class="copies" hidden>
+        <summary></summary>
+        <ul></ul>
+      </details>
       <div class="provider-actions">
         <button class="btn primary new" type="button">New</button>
         <button class="btn existing" type="button">Existing…</button>
@@ -279,10 +283,6 @@
         <button class="btn update" type="button"></button>
         <span class="hint"></span>
       </div>
-      <details class="copies" hidden>
-        <summary></summary>
-        <ul></ul>
-      </details>
     </article>
   </template>
 

package/web/styles.css

@@ -209,14 +209,17 @@ main { max-width: 1200px; margin: 0 auto; padding: 26px 16px 56px; display: grid
 .provider-actions { margin-top: auto; display: flex; gap: 8px; flex-wrap: wrap; align-items: center; }
 .provider .hint { font-size: 0.78rem; color: var(--muted); overflow-wrap: anywhere; }
 .provider .copies { font-size: 0.78rem; color: var(--muted); overflow-wrap: anywhere; }
-.provider .copies summary { cursor: pointer; color: var(--warn); list-style: none; }
+.provider .copies summary { cursor: pointer; list-style: none; }
+.provider .copies.warned summary { color: var(--warn); }
 .provider .copies summary::-webkit-details-marker { display: none; }
 .provider .copies summary::before { margin: 0 0.3em 0 0; transition: transform 0.15s var(--ease); }
 .provider .copies[open] summary::before { transform: rotate(90deg); }
 .provider .copies ul { margin: 6px 0 0; padding: 0; list-style: none; display: grid; gap: 8px; }
 .provider .copies li span { display: block; }
-.provider .copies .copy-name { color: var(--text); }
-.provider .copies code { font-family: ui-monospace, "Cascadia Code", "SF Mono", Menlo, Consolas, monospace; color: var(--text); }
+.provider .copies .copy-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; min-height: 24px; }
+.provider .copies .copy-name { color: var(--text); min-width: 0; }
+.provider .copies .copy-path { font-family: var(--font-mono); font-size: 0.72rem; }
+.provider .copies .copy-uninstall { flex: none; padding: 2px 10px; font-size: 0.75rem; }
 .provider.busy { opacity: 0.6; pointer-events: none; }
 
 .provider-icon {