@oddessentials/agent-guild 0.23.0 → 0.24.0

package/README.md

@@ -78,6 +78,21 @@ card names the command that reattaches it from a terminal. Stopping or
 restarting the manager detaches them the same way, and the cards come back,
 closed and ready to reattach, when it starts again.
 
+Open **Terminal multiplexers** on the Shell card to install, update or
+uninstall tmux and herdr. Operations run in a terminal so you can read their
+output and answer package-manager prompts. tmux uses Homebrew on macOS and
+Homebrew or apt, dnf, or pacman on Linux; a distribution must offer 3.2 or
+later. Update distro packages with their package manager. Native Windows
+offers herdr instead of tmux.
+
+Herdr updates leave its existing servers and panes running, including
+Homebrew updates. New starts and reattachments wait until the operation
+finishes. Uninstall requires herdr's servers to be stopped and their status
+to be verifiable. tmux asks before changing a copy that attached or detached
+cards depend on. Settings and session data are kept. If a multiplexer is
+missing when the manager starts, its saved cards wait for it and return
+when it is detected again, provided their sessions still exist.
+
 <img src="docs/images/terminal.webp" alt="An open Claude Code session with its helper agents shown in the header">
 
 **Agents and models at work.** Helper agents that a tool starts appear on its
@@ -232,6 +247,8 @@ or prompts:
 | OpenRouter's public model list | Benchmarks | Every 6 hours |
 | Public news feeds, Hacker News, arXiv and GitHub | The newsfeed | Every 30 minutes while the page is open |
 | GitHub's releases API | What's new | Hourly |
+| herdr.dev and formulae.brew.sh | Multiplexer version checks | At most hourly, or on Refresh or a requested operation; disabled by `AGENT_GUILD_NO_UPDATE_CHECK=1` |
+| herdr.dev, GitHub release downloads, and the selected package manager's repositories | Multiplexer installation and updates | When you request the operation |
 | GitHub (sign-in, API, avatars and SSH) | Signing in to GitHub, listing your repositories, adding your SSH key and cloning | When you use **Clone from GitHub…** |
 
 ## Other front ends

package/config/providers.default.json

@@ -138,6 +138,10 @@
       "vendor": "Local",
       "tool": "Shell",
       "command": "@shell",
+      "multiplexers": [
+        { "id": "tmux", "docs": "https://github.com/tmux/tmux/wiki/Installing", "channels": { "brew": { "names": ["tmux"] } } },
+        { "id": "herdr", "docs": "https://herdr.dev/docs/install/", "channels": { "brew": { "names": ["herdr"] } } }
+      ],
       "args": [],
       "color": "#8B5CF6",
       "monogram": ">",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "0.23.0",
+  "version": "0.24.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": {

package/src/manager/install-channels.mjs

@@ -7,6 +7,7 @@ export const CHANNEL_LABELS = {
   native: 'native',
   brew: 'Homebrew',
   winget: 'WinGet',
+  system: 'system package',
   legacy: 'legacy install',
   unknown: 'unknown install',
 };

package/src/manager/multiplexer-paths.mjs

@@ -0,0 +1,81 @@
+import path from 'node:path';
+import { homeDir } from './install-channels.mjs';
+import { expandWindowsVars } from './shell-env.mjs';
+
+export function envValue(env, name) {
+  return env[Object.keys(env).find((key) => key.toUpperCase() === name.toUpperCase())];
+}
+
+export function pathIdentity(file, platform) {
+  const p = platform === 'win32' ? path.win32 : path.posix;
+  const value = p.normalize(file.replace(/^\\\\\?\\/, '')).replace(/[\\/]+$/, '');
+  return platform === 'win32' ? value.toLowerCase() : value;
+}
+
+export function herdrLayout(env, platform) {
+  const p = platform === 'win32' ? path.win32 : path.posix;
+  const home = homeDir(env, platform);
+  if (platform !== 'win32') {
+    const bin = p.join(home, '.local/bin');
+    return { home, bin, launcher: p.join(bin, 'herdr'), remove: [p.join(bin, 'herdr')], links: [] };
+  }
+  const root = p.join(home, '.herdr');
+  const standalone = p.join(root, 'packages/standalone');
+  const bin = p.join(envValue(env, 'LOCALAPPDATA') || p.join(home, 'AppData/Local'), 'Programs/Herdr/bin');
+  const current = p.join(standalone, 'current');
+  const releases = p.join(standalone, 'releases');
+  return {
+    home: root, bin, current, releases, standalone, launcher: p.join(current, 'herdr.exe'),
+    remove: [standalone], links: [bin],
+    pathEntries: { exact: [bin, current], parent: releases },
+  };
+}
+
+export function ownsPathEntry(entry, rules, env = {}) {
+  const normalized = pathIdentity(expandWindowsVars(entry.trim().replace(/^"(.*)"$/, '$1'), env), 'win32');
+  return rules.exact.some((p) => normalized === pathIdentity(p, 'win32'))
+    || pathIdentity(path.win32.dirname(normalized), 'win32') === pathIdentity(rules.parent, 'win32');
+}
+
+/** Only herdr's versioned entries are replaced from the registry; other inherited PATH entries stay. */
+export function reconcileHerdrPath(current, env) {
+  const rules = herdrLayout(env, 'win32').pathEntries;
+  return current.split(';').filter((entry) => !ownsPathEntry(entry, rules, env)).join(';');
+}
+
+// This same filter is tested against strings without changing the user's registry.
+export const WINDOWS_PATH_FILTER = String.raw`
+function Remove-OwnedPathEntries($PathValue, $Rules) {
+  function Normalize-Entry([string]$Value) {
+    $value = [Environment]::ExpandEnvironmentVariables($Value.Trim().Trim('"')).TrimEnd('\')
+    try { [System.IO.Path]::GetFullPath($value).TrimEnd('\') } catch { $value }
+  }
+  $owned = @($Rules.exact | ForEach-Object { Normalize-Entry $_ })
+  $ownedParent = Normalize-Entry $Rules.parent
+  $kept = @($PathValue.Split(';') | Where-Object {
+    $segment = Normalize-Entry $_
+    try { $parent = [System.IO.Path]::GetDirectoryName($segment) } catch { $parent = $null }
+    -not ($owned -icontains $segment) -and $parent -ine $ownedParent
+  })
+  return ($kept -join ';')
+}
+`;
+
+export function windowsPathCleanupScript(rules) {
+  const encoded = Buffer.from(JSON.stringify(rules)).toString('base64');
+  return WINDOWS_PATH_FILTER + String.raw`
+$ErrorActionPreference = 'Stop'
+$rules = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('` + encoded + String.raw`')) | ConvertFrom-Json
+$key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)
+if ($null -ne $key) {
+  try {
+    $value = $key.GetValue('Path', $null, [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
+    if ($null -ne $value) {
+      $kind = $key.GetValueKind('Path')
+      $next = Remove-OwnedPathEntries $value $rules
+      if ($next -cne $value) { $key.SetValue('Path', $next, $kind) }
+    }
+  } finally { $key.Dispose() }
+}
+`;
+}

package/src/manager/multiplexers.mjs

@@ -0,0 +1,364 @@
+// Inventory is separate from launchable shells: old tmux and off-PATH or
+// incomplete herdr installations still need management controls.
+import path from 'node:path';
+import { buildSpawnSpec, resolveCommand, resolveAllCommands, runSpec, pathKey } from './command-resolver.mjs';
+import { classifyInstall, defaultFsx, formatCommand, homeRelative, installationKey, uninstallPlan } from './install-channels.mjs';
+import { parseVersion, parseTmuxVersion, compareVersions, compareTmuxVersions } from './versions.mjs';
+import { tmuxSupported } from './shells.mjs';
+import { herdrLayout, ownsPathEntry, pathIdentity } from './multiplexer-paths.mjs';
+import { RUNNER, encodePlan } from './uninstall.mjs';
+
+const TTL = 60_000;
+const LATEST_TTL = 3_600_000;
+const error = (code, message, status = 409) => Object.assign(new Error(message), { code, status });
+const command = (recipe) => recipe ? formatCommand(recipe.file, recipe.args) : null;
+const posixQuote = (s) => "'" + s.replaceAll("'", "'\\''") + "'";
+
+export function distroCandidate(manager, output) {
+  const value = manager === 'apt'
+    ? output.match(/^\s*Candidate:\s*(\S+)/m)?.[1]
+    : manager === 'pacman' ? output.match(/^Version\s*:\s*(\S+)/m)?.[1] : output.trim().split(/\s+/)[0];
+  return parseTmuxVersion(value);
+}
+
+export function nativeHerdrEnv(env, platform) {
+  const layout = herdrLayout(env, platform);
+  return platform === 'win32'
+    ? { HERDR_HOME: layout.home, HERDR_INSTALL_DIR: layout.bin }
+    : { HERDR_INSTALL_DIR: layout.bin };
+}
+
+export class MultiplexerRegistry {
+  constructor(registry, { run = runSpec, resolve = resolveCommand, resolveAll = resolveAllCommands, fsx = defaultFsx, uid = () => process.getuid?.() } = {}) {
+    Object.assign(this, { registry, run, resolve, resolveAll, fsx, uid });
+    this.inventory = new Map();
+    this.latest = new Map();
+  }
+
+  key(provider, id) { return `${provider.id}:${id}`; }
+  definitions(provider) { return provider.command === '@shell' ? provider.multiplexers || [] : []; }
+  env(provider) { return { ...this.registry.env, ...provider.env }; }
+  get(provider, id) {
+    const found = this.definitions(provider).find((m) => m.id === id);
+    if (!found) throw error('unknown_multiplexer', `Unknown multiplexer "${id}"`, 404);
+    return found;
+  }
+
+  describe(provider) {
+    return this.definitions(provider).map((definition) => {
+      const entry = this.inventory.get(this.key(provider, definition.id));
+      return entry?.public || {
+        id: definition.id, tool: definition.tool, docs: definition.docs, checked: false,
+        available: false, installable: false, installs: [], guidance: 'Checking installation…',
+      };
+    });
+  }
+
+  async execute(file, args, env) {
+    return this.run(buildSpawnSpec(file, args, env, this.registry.platform), { env, timeoutMs: 10_000 });
+  }
+
+  async systemInstall(file, definition, env) {
+    if (definition.id !== 'tmux' || this.registry.platform !== 'linux') return null;
+    const candidates = [
+      ['apt', 'dpkg', ['-S', file], /^tmux(?::[a-z0-9_-]+)?:\s/m, 'apt-get'],
+      ['dnf', 'rpm', ['-qf', '--queryformat', '%{NAME}', file], /^tmux$/, 'dnf'],
+      ['pacman', 'pacman', ['-Qqo', file], /^tmux\s*$/, 'pacman'],
+    ];
+    for (const [manager, query, args, match, binary] of candidates) {
+      const probe = this.resolve(query, env, 'linux');
+      if (!probe) continue;
+      try {
+        if (!match.test((await this.execute(probe, args, { ...env, LC_ALL: 'C' })).stdout.trim())) continue;
+        const executable = this.resolve(binary, env, 'linux');
+        const removal = executable && this.elevated(executable, manager === 'pacman' ? ['-R', 'tmux'] : ['remove', 'tmux'], env);
+        return {
+          channel: 'system', resolvedPath: file, realPath: this.fsx.realpath(file), key: `system:${manager}:tmux`,
+          update: null, uninstall: removal ? { run: removal, remove: [], links: [] } : null,
+          guidance: `Managed by ${manager}. Update tmux with your distribution's package manager.`,
+        };
+      } catch { /* another manager, or no verifiable owner */ }
+    }
+    return null;
+  }
+
+  elevated(file, args, env) {
+    if (this.uid() === 0) return { file, args };
+    const sudo = this.resolve('sudo', env, this.registry.platform);
+    return sudo ? { file: sudo, args: [file, ...args] } : null;
+  }
+
+  nativeOwns(file, env) {
+    const platform = this.registry.platform;
+    const layout = herdrLayout(env, platform);
+    const real = pathIdentity(this.fsx.realpath(file), platform);
+    if (platform !== 'win32') return real === pathIdentity(layout.launcher, platform) && !this.fsx.isLink(file);
+    const p = path.win32;
+    return p.basename(real) === 'herdr.exe'
+      && pathIdentity(p.dirname(p.dirname(real)), platform) === pathIdentity(layout.releases, platform)
+      && pathIdentity(this.fsx.realpath(layout.standalone), platform) === pathIdentity(layout.standalone, platform);
+  }
+
+  nativeCopy(file, env, partial = false) {
+    const platform = this.registry.platform;
+    const layout = herdrLayout(env, platform);
+    return {
+      channel: 'native', resolvedPath: file, realPath: this.fsx.realpath(file), key: `native:${pathIdentity(layout.launcher, platform)}`,
+      partial, update: partial ? null : { file, args: ['update'] },
+      uninstall: { run: null, remove: layout.remove, links: layout.links, launcher: partial ? null : file, pathEntries: layout.pathEntries, strict: true },
+      guidance: partial ? 'An incomplete herdr installation remains. Install again to repair it before checking server status and removing it.' : null,
+    };
+  }
+
+  managedPathsSafe(env) {
+    const platform = this.registry.platform;
+    const p = platform === 'win32' ? path.win32 : path.posix;
+    const layout = herdrLayout(env, platform);
+    const roots = platform === 'win32' ? [layout.standalone, p.dirname(layout.bin)] : [layout.bin];
+    for (const root of roots) {
+      for (let parent = root; ; parent = p.dirname(parent)) {
+        if (this.fsx.isLink(parent) || pathIdentity(this.fsx.realpath(parent), platform) !== pathIdentity(parent, platform)) return false;
+        if (p.dirname(parent) === parent) break;
+      }
+    }
+    if (platform === 'win32' && this.fsx.isLink(layout.bin)) {
+      const target = this.fsx.realpath(layout.bin);
+      if (pathIdentity(p.dirname(target), platform) !== pathIdentity(layout.releases, platform)) return false;
+    }
+    return true;
+  }
+
+  async inspect(definition, env) {
+    const platform = this.registry.platform;
+    const onPath = this.resolveAll(definition.id, env, platform);
+    const files = [...onPath];
+    const layout = herdrLayout(env, platform);
+    if (definition.id === 'herdr') {
+      const known = [layout.launcher, ...(platform === 'win32' ? [path.win32.join(layout.bin, 'herdr.exe')] : [])];
+      for (const file of known) if (this.fsx.isFile(file) && !files.includes(file)) files.push(file);
+    }
+    const copies = new Map();
+    for (const file of files) {
+      // Classify Homebrew first, including symlinks in a user's bin directory.
+      let copy = classifyInstall({ resolvedPath: file, provider: { ...definition, channels: { brew: definition.channels.brew } }, env, platform, fsx: this.fsx });
+      if (copy.channel === 'unknown') {
+        if (definition.id === 'herdr' && this.nativeOwns(file, env)) copy = this.nativeCopy(file, env);
+        else copy = await this.systemInstall(file, definition, env) || copy;
+      }
+      copy.key ??= installationKey(copy, definition, platform, this.fsx);
+      copy.uninstall ??= uninstallPlan(copy, definition, env, platform, this.fsx);
+      copy.onPath = onPath.includes(file);
+      copy.active = file === onPath[0];
+      if (copies.has(copy.key)) continue;
+      try {
+        const { stdout } = await this.execute(file, definition.versionArgs, env);
+        copy.version = definition.id === 'tmux' ? parseTmuxVersion(stdout) : parseVersion(stdout);
+        copy.supported = definition.id !== 'tmux' || tmuxSupported(stdout.trim());
+        copy.versionStatus = copy.version ? 'ok' : 'unavailable';
+        copy.versionError = null;
+      } catch (err) {
+        Object.assign(copy, { version: null, supported: false, versionStatus: 'failed', versionError: String(err.message).slice(0, 200) });
+      }
+      if (copy.channel === 'native' && copy.update) {
+        try {
+          const out = await this.execute(file, ['update', '--help'], { ...env, ...nativeHerdrEnv(env, platform) });
+          if (!/Usage:\s*herdr update/i.test(out.stdout + out.stderr)) copy.update = null;
+        } catch { copy.update = null; }
+      }
+      copies.set(copy.key, copy);
+    }
+    if (definition.id === 'herdr' && ![...copies.values()].some((c) => c.channel === 'native')) {
+      const remnants = layout.remove.some((p) => this.fsx.exists(p))
+        || (platform === 'win32' && (env[pathKey(env, platform)] || '').split(';').some((p) => ownsPathEntry(p, layout.pathEntries, env)));
+      if (remnants && layout.remove.every((p) => pathIdentity(this.fsx.realpath(p), platform) === pathIdentity(p, platform))) {
+        const copy = this.nativeCopy(layout.launcher, env, true);
+        copies.set(copy.key, { ...copy, onPath: false, active: false, supported: false, version: null, versionStatus: 'failed' });
+      }
+    }
+    return [...copies.values()];
+  }
+
+  async installRecipe(definition, env) {
+    const platform = this.registry.platform;
+    const resolve = (name) => this.resolve(name, env, platform);
+    if (definition.id === 'tmux') {
+      if (platform === 'win32') return { guidance: 'Native tmux is not supported on Windows. Install herdr to use a multiplexer here.' };
+      let guidance = 'Install tmux 3.2 or later with Homebrew, or use herdr.';
+      if (platform === 'linux') {
+        for (const [manager, query, args, binary, installArgs] of [
+          ['apt', 'apt-cache', ['policy', 'tmux'], 'apt-get', ['install', 'tmux']],
+          ['dnf', 'dnf', ['repoquery', '--available', '--latest-limit=1', '--queryformat', '%{version}\\n', 'tmux'], 'dnf', ['install', 'tmux']],
+          ['pacman', 'pacman', ['-Si', 'tmux'], 'pacman', ['-S', 'tmux']],
+        ]) {
+          if (!resolve(query) || !resolve(binary)) continue;
+          let candidate = null;
+          try { candidate = distroCandidate(manager, (await this.execute(resolve(query), args, { ...env, LC_ALL: 'C' })).stdout); } catch {}
+          if (candidate && compareTmuxVersions(candidate, '3.2') >= 0) {
+            const recipe = this.elevated(resolve(binary), installArgs, env);
+            if (recipe) return { recipe };
+          }
+          guidance = candidate
+            ? `Your distribution offers tmux ${candidate}; Agent Guild needs 3.2 or later and sudo (unless root). Install with Homebrew, or use herdr.`
+            : 'Could not verify a usable tmux package. Check your package metadata, install tmux 3.2 or later with Homebrew, or use herdr.';
+          break;
+        }
+      }
+      return resolve('brew') ? { recipe: { file: resolve('brew'), args: ['install', 'tmux'] } } : { guidance };
+    }
+    const extraEnv = nativeHerdrEnv(env, platform);
+    if (!this.managedPathsSafe(env)) return { guidance: 'The default herdr installation directory is redirected by a link. Manage this installation with its original installer.' };
+    if (platform === 'win32') {
+      const powershell = resolve('powershell.exe');
+      if (!powershell || !resolve('curl.exe')) return { guidance: 'Install herdr with the Windows installer at https://herdr.dev/docs/install/; PowerShell and curl.exe are required.' };
+      return {
+        recipe: {
+          file: powershell, args: ['-NoLogo', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', "$ErrorActionPreference = 'Stop'; & ([scriptblock]::Create((Invoke-RestMethod 'https://herdr.dev/install.ps1'))) -Channel stable -ManifestUrl 'https://herdr.dev/latest.json' -ExpectedBuildId ''"],
+        },
+        extraEnv: { ...extraEnv, HERDR_CHANNEL: 'stable', HERDR_MANIFEST_URL: '', HERDR_EXPECTED_BUILD_ID: '' },
+      };
+    }
+    if (!['sh', 'curl', 'awk'].every(resolve)) return { guidance: 'Install herdr with https://herdr.dev/install.sh; sh, curl and awk are required.' };
+    // Download first: a failed curl in a pipe must not look like a successful install.
+    return {
+      recipe: { file: resolve('sh'), args: ['-c', `script=$(${posixQuote(resolve('curl'))} -fsSL https://herdr.dev/install.sh) || exit $?; ${posixQuote(resolve('sh'))} -c "$script"`] },
+      extraEnv,
+    };
+  }
+
+  async latestFor(definition, copy, env, force) {
+    if (!this.registry.checkUpdates) return null;
+    let url;
+    if (copy.channel === 'brew') url = `https://formulae.brew.sh/api/formula/${definition.id}.json`;
+    else if (copy.channel === 'native' && !copy.partial) {
+      // Preview identity is not ordinary semver. Do not compare it to stable.
+      try {
+        const { stdout } = await this.execute(copy.resolvedPath, ['channel', 'show'], { ...env, ...nativeHerdrEnv(env, this.registry.platform) });
+        if (stdout.trim() !== 'stable') return null;
+      } catch { return null; }
+      url = 'https://herdr.dev/latest.json';
+    }
+    if (!url || !this.registry.checkUpdates) return null;
+    const cached = this.latest.get(url);
+    if (!force && cached && Date.now() - cached.at < LATEST_TTL) return cached.version;
+    let version = null;
+    try {
+      const response = await (this.registry.fetchImpl || fetch)(url, { signal: AbortSignal.timeout(10_000) });
+      if (response.ok) {
+        const body = await response.json();
+        const raw = copy.channel === 'brew' ? body.versions?.stable : body.version;
+        version = definition.id === 'tmux' ? parseTmuxVersion(raw) : parseVersion(raw);
+      }
+    } catch {}
+    this.latest.set(url, { version, at: Date.now() });
+    return version;
+  }
+
+  async refresh(provider, { force = false } = {}) {
+    let changed = false;
+    await Promise.all(this.definitions(provider).map(async (definition) => {
+      const key = this.key(provider, definition.id);
+      const previous = this.inventory.get(key);
+      if (!force && previous && Date.now() - previous.at < TTL) return;
+      const env = this.env(provider);
+      const unsupported = definition.id === 'tmux' && this.registry.platform === 'win32';
+      const copies = unsupported ? [] : await this.inspect(definition, env);
+      const install = await this.installRecipe(definition, env);
+      const active = copies.find((c) => c.active);
+      const compare = definition.id === 'tmux' ? compareTmuxVersions : compareVersions;
+      const installs = await Promise.all(copies.map(async (copy) => {
+        const latestVersion = await this.latestFor(definition, copy, env, force);
+        const guidance = copy.guidance || (!copy.update ? 'Update this copy the way you installed it.'
+          : !latestVersion ? `Latest version is unknown. You can run ${command(copy.update)} to check for an update using this installation's channel.` : null);
+        return {
+          path: copy.resolvedPath, key: copy.key, displayPath: homeRelative(copy.resolvedPath, env, this.registry.platform),
+          channel: copy.channel, version: copy.version, versionStatus: copy.versionStatus,
+          active: copy.active, onPath: copy.onPath, partial: Boolean(copy.partial), supported: copy.supported,
+          latestVersion, updateAvailable: Boolean(copy.version && latestVersion && compare(latestVersion, copy.version) > 0),
+          updateCommand: command(copy.update), updateGuidance: guidance,
+          uninstall: copy.uninstall && { command: command(copy.uninstall.run), remove: [...copy.uninstall.remove, ...copy.uninstall.links].map((p) => homeRelative(p, env, this.registry.platform)), pathEntries: Boolean(copy.uninstall.pathEntries) },
+          uninstallGuidance: copy.uninstall ? null : 'Remove this copy the way you installed it.',
+        };
+      }));
+      const offPath = copies.some((c) => !c.onPath && !c.partial);
+      const old = active && definition.id === 'tmux' && !active.supported;
+      const publicInfo = {
+        id: definition.id, tool: definition.tool, docs: definition.docs, checked: true,
+        available: Boolean(active?.supported), installable: Boolean(install.recipe && !copies.some((c) => !c.partial)),
+        installCommand: command(install.recipe), installs,
+        guidance: unsupported ? install.guidance : old ? `tmux ${active.version || 'at this path'} cannot be started here; 3.2 or later is required. ${install.guidance || 'Remove the old copy before installing a supported one.'}`
+          : offPath ? `A copy exists off PATH. Add its directory to your shell's PATH, then Refresh to make it available.`
+            : copies.some((c) => c.partial) ? copies.find((c) => c.partial).guidance : copies.length ? null : install.guidance || null,
+        lastInstall: previous?.public.lastInstall ?? null,
+      };
+      changed ||= JSON.stringify(previous?.public) !== JSON.stringify(publicInfo);
+      this.inventory.set(key, { at: Date.now(), copies, install, public: publicInfo });
+    }));
+    return changed;
+  }
+
+  copyFor(provider, id, file) {
+    return this.inventory.get(this.key(provider, id))?.copies.find((c) => pathIdentity(c.resolvedPath, this.registry.platform) === pathIdentity(file, this.registry.platform));
+  }
+
+  identityFor(provider, id, file) {
+    const cached = this.copyFor(provider, id, file);
+    if (cached) return cached.key;
+    const definition = this.definitions(provider).find((m) => m.id === id);
+    if (!definition) return null;
+    const env = this.env(provider);
+    if (id === 'herdr' && this.nativeOwns(file, env)) return this.nativeCopy(file, env).key;
+    const copy = classifyInstall({ resolvedPath: file, provider: definition, env, platform: this.registry.platform, fsx: this.fsx });
+    return copy.channel === 'unknown' ? null : installationKey(copy, definition, this.registry.platform, this.fsx);
+  }
+
+  async prepare(provider, id, kind, copyPath) {
+    this.get(provider, id);
+    await this.registry.refreshVersions({ force: true, ids: [provider.id] });
+    const entry = this.inventory.get(this.key(provider, id));
+    const env = this.env(provider);
+    if (kind === 'install') {
+      if (!entry.public.installable) throw error('not_installable', entry.public.guidance || 'This tool is already installed or has no supported installer.', 400);
+      return { spec: buildSpawnSpec(entry.install.recipe.file, entry.install.recipe.args, env, this.registry.platform), extraEnv: entry.install.extraEnv, copy: null };
+    }
+    if (typeof copyPath !== 'string' || !copyPath) throw error('bad_request', 'path must name the installation to change', 400);
+    const copy = this.copyFor(provider, id, copyPath);
+    if (!copy) throw error('unknown_copy', 'The selected installation is no longer present. Refresh and try again.', 404);
+    const recipe = kind === 'update' ? copy.update : copy.uninstall;
+    if (!recipe) throw error(kind === 'update' ? 'not_updatable' : 'not_removable', copy.guidance || 'Manage this copy with its original installer.', 400);
+    const spec = kind === 'update'
+      ? buildSpawnSpec(recipe.file, recipe.args, env, this.registry.platform)
+      : buildSpawnSpec(process.execPath, [RUNNER, encodePlan(recipe)], env, this.registry.platform);
+    return { spec, copy, extraEnv: copy.channel === 'native' ? nativeHerdrEnv(env, this.registry.platform) : null };
+  }
+
+  async assertHerdrStopped(provider, copy, extraEnv) {
+    try {
+      if (copy.partial) throw new Error('herdr executable is missing');
+      const env = { ...this.env(provider), ...extraEnv };
+      const { stdout } = await this.execute(copy.resolvedPath, ['session', 'list', '--json'], env);
+      const body = JSON.parse(stdout);
+      if (!Array.isArray(body.sessions) || body.sessions.some((s) => typeof s.running !== 'boolean')) throw new Error('invalid session listing');
+      if (body.sessions.some((s) => s.running)) {
+        throw error('herdr_running', 'Stop herdr before uninstalling: herdr server stop (and herdr session stop <name> for other running sessions).');
+      }
+    } catch (err) {
+      if (err.code === 'herdr_running') throw err;
+      throw error('herdr_status_unknown', 'Cannot safely determine whether herdr is running. Repair the installation if necessary, then check herdr session list --json before retrying.');
+    }
+  }
+
+  async finish(provider, id, kind, copy, exitCode) {
+    const key = this.key(provider, id);
+    const before = copy?.version;
+    await this.registry.refreshVersions({ force: true, ids: [provider.id] });
+    const entry = this.inventory.get(key);
+    if (!entry) return;
+    const after = copy && entry.copies.find((c) => c.key === copy.key);
+    const outcome = exitCode !== 0 ? 'failed' : kind === 'uninstall' ? after ? 'remaining' : 'removed'
+      : kind === 'install' ? entry.public.available ? 'installed' : 'missing'
+        : !after || after.partial ? 'missing' : after.version && after.version === before ? 'unchanged' : 'updated';
+    const checked = kind === 'install' ? entry.copies.find((c) => c.active) : after;
+    entry.public.lastInstall = { kind, outcome, exitCode, ...(kind !== 'uninstall' && checked?.versionStatus === 'failed' ? { verification: 'failed' } : {}) };
+    this.registry.emit('updated');
+  }
+}

package/src/manager/providers.mjs

@@ -16,6 +16,8 @@ import { weavePaths } from './shell-env.mjs';
 import { detectShells, fallbackShell } from './shells.mjs';
 import { RUNNER, encodePlan } from './uninstall.mjs';
 import { paths } from './config.mjs';
+import { MultiplexerRegistry } from './multiplexers.mjs';
+import { reconcileHerdrPath } from './multiplexer-paths.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 export const DEFAULTS_FILE = path.resolve(here, '../../config/providers.default.json');
@@ -177,6 +179,17 @@ function normalize(raw, platform, warnings) {
     install: String(merged.install || ''),
     npmNote: merged.npmNote ? String(merged.npmNote) : null,
     channels: normalizeChannels(merged.channels),
+    multiplexers: Array.isArray(merged.multiplexers) ? merged.multiplexers
+      .filter((m) => m && typeof m === 'object' && !Array.isArray(m))
+      .map((m) => ({ ...m, ...m[platform] }))
+      .filter((m) => ['tmux', 'herdr'].includes(m.id) && m.enabled !== false)
+      .map((entry) => {
+        return {
+          id: entry.id, tool: String(entry.tool || entry.id), docs: String(entry.docs || ''),
+          versionArgs: entry.id === 'tmux' ? ['-V'] : ['--version'],
+          channels: normalizeChannels(entry.channels),
+        };
+      }) : [],
     docs: String(merged.docs || ''),
     usageUrl: httpsUrl(merged.usageUrl, 'usageUrl', merged.id, warnings),
     billingUrl: httpsUrl(merged.billingUrl, 'billingUrl', merged.id, warnings),
@@ -241,7 +254,7 @@ export class ProviderRegistry extends EventEmitter {
    * @param {Function} [opts.fetchImpl]
    * @param {string} [opts.accountsDir]  where accounts without a dir get their home folders
    */
-  constructor({ userFile, env, platform = process.platform, iconDir, registryUrl = null, checkUpdates = true, fetchImpl, pathReader = null, accountsDir = paths.accounts } = {}) {
+  constructor({ userFile, env, platform = process.platform, iconDir, registryUrl = null, checkUpdates = true, fetchImpl, pathReader = null, accountsDir = paths.accounts, multiplexerOptions } = {}) {
     super();
     this.userFile = userFile;
     this.accountsDir = accountsDir;
@@ -260,6 +273,8 @@ export class ProviderRegistry extends EventEmitter {
     this._refreshing = null;
     this._npmRegistry = null;
     this.reportingEnabled = null;
+    this.multiplexers = new MultiplexerRegistry(this, multiplexerOptions);
+    this.multiplexerState = null;
     this.reload();
   }
 
@@ -270,6 +285,7 @@ export class ProviderRegistry extends EventEmitter {
     this._npmRegistry = null;
     this._installs.clear();
     this._shells.clear();
+    this.multiplexers.inventory.clear();
     for (const w of warnings) console.warn(`[providers] ${w}`);
     this.emit('updated');
   }
@@ -324,9 +340,10 @@ export class ProviderRegistry extends EventEmitter {
 
   async _readPath() {
     const discovered = await Promise.resolve().then(() => this.pathReader()).catch(() => null);
-    if (!discovered) return false;
+    if (discovered === null || discovered === undefined) return false;
     const key = pathKey(this.env, this.platform);
-    const next = weavePaths(this.env[key] || '', discovered, {
+    const current = this.platform === 'win32' ? reconcileHerdrPath(this.env[key] || '', this.env) : this.env[key] || '';
+    const next = weavePaths(current, discovered, {
       delimiter: this.platform === 'win32' ? ';' : ':',
       caseInsensitive: this.platform === 'win32',
     });
@@ -341,10 +358,18 @@ export class ProviderRegistry extends EventEmitter {
     const now = Date.now();
     let changed = await this.refreshPath({ force });
     const providers = this.providers.filter((p) => !ids || ids.includes(p.id));
-    if (force) for (const provider of providers) this._installs.delete(provider.id);
+    const shellsBefore = JSON.stringify(providers.map((p) => this._shells.get(p.id)?.found ?? null));
+    // Installing into an existing PATH directory does not change PATH itself.
+    for (const provider of providers) {
+      if (force) this._installs.delete(provider.id);
+      if (force) this._shells.delete(provider.id);
+    }
     const lookups = this.checkUpdates && providers.some((p) => p.package);
     const registryUrl = lookups ? await this.npmRegistryUrl() : null;
     await Promise.all(providers.map(async (provider) => {
+      const muxChanged = await this.multiplexers.refresh(provider, { force });
+      if (muxChanged) this._shells.delete(provider.id);
+      changed ||= muxChanged;
       const entry = this.versions.get(provider.id) || {
         installed: null, versionStatus: null, versionError: null, installedPath: null, installedMtime: null, installedAt: 0,
         latest: null, latestAt: 0, probePath: null, probeMtime: null, probeAt: 0, probeOk: null, lastInstall: null, copies: {},
@@ -412,6 +437,7 @@ export class ProviderRegistry extends EventEmitter {
       }
       this.versions.set(provider.id, entry);
     }));
+    changed ||= shellsBefore !== JSON.stringify(providers.map((p) => this.shellsFor(p)));
     if (changed) this.emit('updated');
   }
 
@@ -671,6 +697,7 @@ export class ProviderRegistry extends EventEmitter {
       accounts: provider.accounts.map((account) => ({ id: account.id, label: account.label })),
       shells: shells?.shells.map((shell) => ({ id: shell.id, label: shell.label, path: shell.path, multiplexer: Boolean(shell.multiplexer) })) ?? null,
       defaultShell: shells?.defaultId ?? null,
+      multiplexers: this.multiplexers.describe(provider).map((m) => ({ ...m, ...this.multiplexerState?.(provider.id, m.id) })),
       modelPattern: provider.modelPattern,
       color: provider.color,
       monogram: provider.monogram,

package/src/manager/server.mjs

@@ -285,6 +285,12 @@ export function createManagerServer({
       registry.emit('updated');
       return sendJson(res, 200, { provider: registry.describe(provider) });
     }
+    const multiplexerMatch = route.match(/^\/providers\/([a-z0-9][a-z0-9_-]{0,31})\/multiplexers\/([a-z0-9_-]+)\/(install|update|uninstall)$/);
+    if (multiplexerMatch && method === 'POST') {
+      const body = await readJsonBody(req);
+      const session = await manager.manageMultiplexer(multiplexerMatch[1], multiplexerMatch[2], multiplexerMatch[3], { path: body.path, force: body.force === true });
+      return sendJson(res, 201, { session: session.toJSON() });
+    }
     const installMatch = route.match(/^\/providers\/([a-z0-9][a-z0-9_-]{0,31})\/install$/);
     if (installMatch && method === 'POST') {
       const body = await readJsonBody(req);
@@ -408,6 +414,7 @@ export function createManagerServer({
       if (!res.headersSent) {
         const error = { code: err.code || 'error', message: err.message };
         if (err.running !== undefined) error.running = err.running;
+        if (err.pending !== undefined) error.pending = err.pending;
         if (err.target !== undefined) error.target = err.target;
         sendJson(res, status, { error });
       }

package/src/manager/session-manager.mjs

@@ -14,6 +14,7 @@ import { HerdrAgents, herdrAgentReports, herdrSocket } from './herdr.mjs';
 import { CHANNEL_LABELS } from './install-channels.mjs';
 import { SELF_PROVIDER } from './self-update.mjs';
 import { GITHUB_PROVIDER, dropsFromCloneEnv, parseRepo } from './github.mjs';
+import { pathIdentity } from './multiplexer-paths.mjs';
 
 export const MAX_SESSIONS = 32;
 
@@ -84,6 +85,17 @@ export class SessionManager extends EventEmitter {
     /** Keeps the tmux and herdr cards across restarts: { load(), save(cards) }, or null. */
     this.store = store;
     this.restoring = false;
+    this.pendingCards = new Map();
+    this.multiplexerOperations = new Set();
+    this.multiplexerStarts = new Map();
+    this.pendingRestore = null;
+    if (this.registry) this.registry.multiplexerState = (provider, id) => ({
+      busy: this.multiplexerOperations.has(id),
+      pendingCards: [...this.pendingCards.values()].filter((c) => c.provider === provider && c.shell === id).length,
+    });
+    this.registry?.on?.('updated', () => {
+      this._restorePending().catch((err) => console.warn('[sessions] pending cards:', err.message));
+    });
   }
 
   list() {
@@ -129,7 +141,7 @@ export class SessionManager extends EventEmitter {
       || (provider.accounts.length > 1 ? `${provider.tool} · ${signIn.label}` : null)
       || (runShell && this.registry.shellsFor(provider).shells.length > 1 ? `${provider.tool} · ${runShell.label}` : null);
     const options = { provider, cwd: workDir, cols, rows, name: sessionName, resume: resumeId, account: signIn, reporting: hooks.reporting, extraEnv: runShell?.env };
-    if (runShell?.multiplexer) return this._startMultiplexer(options, runShell, args || []);
+    if (runShell?.multiplexer) return this._withMultiplexerStart(provider.id, runShell.id, () => this._startMultiplexer(options, runShell, args || []));
     const spawnSpec = this.registry.spawnSpec(provider, args || [], resumeId, hooks.args, runShell);
     const session = this._spawn({ ...options, spawnSpec });
     const model = modelFromArgs([...provider.args, ...(args || [])]);
@@ -177,7 +189,13 @@ export class SessionManager extends EventEmitter {
       if (shell.id === 'tmux') mux.run(['kill-session', '-t', `=${muxName}`]).catch(() => {});
       throw err;
     }
-    this._track(session, { spawnSpec, mux, shell, card: { id, reportToken, provider: provider.id, account: account.id, shell: shell.id, muxName, name: session.name, cwd: session.cwd, createdAt: session.createdAt } });
+    this._track(session, { spawnSpec, mux, shell, card: {
+      id, reportToken, provider: provider.id, account: account.id, shell: shell.id,
+      muxName, name: session.name, cwd: session.cwd, createdAt: session.createdAt,
+      // Herdr's request arguments belong to its client and must survive rebinding.
+      // Tmux's request arguments belong to the already-running inner session.
+      ...(shell.id === 'herdr' ? { args: [...args] } : {}),
+    } });
     this._watchHerdr(session);
     return session;
   }
@@ -197,12 +215,17 @@ export class SessionManager extends EventEmitter {
 
   /** Keep a tmux or herdr card for Reattach, here and, through the store, across restarts. */
   _track(session, { spawnSpec, mux, shell, card }) {
-    this.multiplexers.set(session.id, { spawnSpec, alive: mux.alive, herdr: shell.id === 'herdr' ? { path: shell.path, env: mux.clientEnv } : null, card });
+    const installationKey = this.registry.multiplexers?.identityFor(this.registry.get(card.provider), shell.id, shell.path);
+    const shellPath = shell.path;
+    // Keep old stores readable. Newly known installations carry a stable key,
+    // since an update can change a Cellar or Windows release realpath.
+    card.shellPath = shellPath;
+    if (installationKey) card.installationKey = installationKey;
+    const tracked = { spawnSpec, alive: mux.alive, shellPath, checking: false, herdr: shell.id === 'herdr' ? { path: shell.path, env: mux.clientEnv } : null, card };
+    this.multiplexers.set(session.id, tracked);
+    this.pendingCards.delete(session.id);
     this._saveCards();
-    session.on('exit', async () => {
-      session.multiplexer.reattachable = await mux.alive();
-      session._changed();
-    });
+    session.on('exit', () => this._checkMultiplexer(session, tracked));
     session.on('changed', () => {
       if (card.name === session.name) return;
       card.name = session.name;
@@ -214,7 +237,7 @@ export class SessionManager extends EventEmitter {
     // A stopping manager leaves the file as it is, for the next one to bring the cards back.
     if (!this.store || this.restoring || this.closing) return;
     try {
-      this.store.save([...this.multiplexers.values()].map(({ card }) => card));
+      this.store.save([...this.multiplexers.values()].map(({ card }) => card).concat([...this.pendingCards.values()]));
     } catch (err) {
       console.warn(`[sessions] could not save the tmux and herdr cards: ${err.message}`);
     }
@@ -229,7 +252,8 @@ export class SessionManager extends EventEmitter {
     this.restoring = true;
     try {
       // All at once, so a multiplexer slow to answer holds up the start once, not once a card.
-      await Promise.all((this.store?.load() ?? []).map((card) => this._restoreCard(card).catch((err) => {
+      await Promise.all((this.store?.load() ?? []).map((card) => this._withMultiplexerStart(card?.provider, card?.shell, () => this._restoreCard(card)).catch((err) => {
+        if (['too_many_sessions', 'install_in_progress'].includes(err.code)) this.pendingCards.set(card.id, card);
         console.warn(`[sessions] did not bring back the card ${card?.name ?? card?.id}: ${err.message}`);
       })));
     } finally {
@@ -243,12 +267,25 @@ export class SessionManager extends EventEmitter {
     if (typeof card.reportToken !== 'string' || !/^[a-f0-9]{32}$/.test(card.reportToken)) return;
     if (typeof card.muxName !== 'string' || !/^guild-[0-9a-f]{6}$/.test(card.muxName)) return;
     const provider = this.registry.get(String(card.provider));
-    const shell = provider && this.registry.shellsFor(provider)?.shells.find((s) => s.id === card.shell && s.multiplexer);
-    if (!shell) return;
+    if (!provider || !['tmux', 'herdr'].includes(card.shell)) return;
+    if (card.shell === 'herdr' && card.args !== undefined && (!Array.isArray(card.args) || card.args.some((arg) => typeof arg !== 'string'))) return;
+    const shells = this.registry.shellsFor(provider)?.shells || [];
+    const shell = shells.find((s) => s.id === card.shell && s.multiplexer);
+    if (!shell) {
+      this.pendingCards.set(card.id, card);
+      return;
+    }
+    if (this.multiplexerOperations.has(card.shell)) {
+      this.pendingCards.set(card.id, card);
+      return;
+    }
     const account = this.registry.account(provider, card.account);
     const mux = this._multiplexer({ provider, account, shell, id: card.id, reportToken: card.reportToken, muxName: card.muxName });
-    if (!(await mux.alive()) || this.closing) return;
-    const spawnSpec = this.registry.spawnSpec(provider, [], null, [], mux.named);
+    if (!(await mux.alive()) || this.closing) {
+      if (!this.closing) this.pendingCards.delete(card.id);
+      return;
+    }
+    const spawnSpec = this.registry.spawnSpec(provider, shell.id === 'herdr' ? card.args ?? [] : [], null, [], mux.named);
     const session = this._spawn({
       provider, spawnSpec: null, cwd: typeof card.cwd === 'string' ? card.cwd : os.homedir(), name: card.name, account,
       id: card.id, reportToken: card.reportToken, dropEnv: mux.dropEnv, extraEnv: shell.env,
@@ -260,6 +297,43 @@ export class SessionManager extends EventEmitter {
 
   /** Attach a stopped tmux or herdr session's card to its multiplexer session again, keeping its id and report token. */
   async reattach(id) {
+    const tracked = this.multiplexers.get(id);
+    if (!tracked) return this._reattach(id);
+    return this._withMultiplexerStart(tracked.card.provider, tracked.card.shell, () => this._reattach(id));
+  }
+
+  _rebindMultiplexer(mux) {
+    const provider = this.registry.get(mux.card.provider);
+    const shell = provider && this.registry.shellsFor(provider)?.shells.find((s) => s.id === mux.card.shell && s.multiplexer);
+    if (!shell) return false;
+    const fresh = this._multiplexer({ provider, account: this.registry.account(provider, mux.card.account), shell, id: mux.card.id, reportToken: mux.card.reportToken, muxName: mux.card.muxName });
+    mux.spawnSpec = this.registry.spawnSpec(provider, shell.id === 'herdr' ? mux.card.args ?? [] : [], null, [], fresh.named);
+    mux.alive = fresh.alive;
+    mux.shellPath = shell.path;
+    mux.card.shellPath = shell.path;
+    const key = this.registry.multiplexers?.identityFor(provider, shell.id, shell.path);
+    if (key) mux.card.installationKey = key;
+    else delete mux.card.installationKey;
+    if (mux.herdr) mux.herdr = { path: shell.path, env: fresh.clientEnv };
+    this._saveCards();
+    return true;
+  }
+
+  async _checkMultiplexer(session, tracked) {
+    const sequence = tracked.checkSequence = (tracked.checkSequence || 0) + 1;
+    tracked.checking = true;
+    let alive = false;
+    try {
+      this._rebindMultiplexer(tracked);
+      alive = await tracked.alive();
+    } catch {}
+    if (tracked.checkSequence !== sequence) return;
+    session.multiplexer.reattachable = alive;
+    tracked.checking = false;
+    session._changed();
+  }
+
+  async _reattach(id) {
     const session = this.get(id);
     const mux = this.multiplexers.get(id);
     if (!mux) throw httpError(400, `${session.name} is not in tmux or herdr`, 'not_reattachable');
@@ -267,6 +341,9 @@ export class SessionManager extends EventEmitter {
     if (session.status === 'running') throw httpError(409, `${session.name} is still attached`, 'session_running');
     // As the page offers it: only once the manager has found, after the client closed or at a restart, that the multiplexer still has the session.
     if (!session.multiplexer.reattachable) throw httpError(409, `${session.multiplexer.label} no longer has the session ${session.name} ran in`, 'multiplexer_session_gone');
+    // Refresh closures as well as the spawn spec: the previous executable
+    // may have disappeared in a native or Homebrew update.
+    if (!this._rebindMultiplexer(mux)) throw httpError(409, 'Install the multiplexer and refresh this page before reattaching.', 'shell_unavailable');
     const alive = await mux.alive();
     if (this.sessions.get(id) !== session || session.status === 'running') throw httpError(409, `${session.name} changed meanwhile`, 'session_running');
     if (!alive) {
@@ -368,10 +445,123 @@ export class SessionManager extends EventEmitter {
 
   installsRunningFor(providerId) {
     let n = 0;
-    for (const s of [...this.sessions.values(), ...this.exiting]) 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.multiplexerInstall && s.provider.id === providerId) n++;
     return n;
   }
 
+  async _withMultiplexerStart(providerId, id, start) {
+    // Multiple @shell providers can share the same executable.
+    const key = id;
+    if (this.multiplexerOperations.has(key)) throw httpError(409, `${id} is being installed, updated or removed; try again when it finishes.`, 'install_in_progress');
+    this.multiplexerStarts.set(key, (this.multiplexerStarts.get(key) || 0) + 1);
+    try { return await start(); }
+    finally {
+      const count = this.multiplexerStarts.get(key) - 1;
+      if (count) this.multiplexerStarts.set(key, count);
+      else this.multiplexerStarts.delete(key);
+    }
+  }
+
+  dependentsOf(providerId, id, copy = null) {
+    const platform = this.registry.platform;
+    const same = (a, b) => pathIdentity(a, platform) === pathIdentity(b, platform);
+    let running = 0;
+    for (const [sessionId, tracked] of this.multiplexers) {
+      if (tracked.card.shell !== id) continue;
+      if (copy && tracked.card.installationKey && tracked.card.installationKey !== copy.key) continue;
+      if (copy && !tracked.card.installationKey && tracked.shellPath
+        && !same(tracked.shellPath, copy.resolvedPath)
+        && !same(this.registry.multiplexers.fsx.realpath(tracked.shellPath), copy.realPath)) continue;
+      const session = this.sessions.get(sessionId);
+      if (session?.status === 'running' || session?.multiplexer?.reattachable || tracked.checking) running++;
+    }
+    const pending = [...this.pendingCards.values()].filter((c) => c.provider === providerId && c.shell === id).length;
+    return { running, pending };
+  }
+
+  async manageMultiplexer(providerId, id, kind, { path: copyPath = null, force = false } = {}) {
+    const provider = this.registry.get(providerId);
+    if (!provider) throw httpError(404, 'Unknown provider', 'unknown_provider');
+    this.registry.multiplexers.get(provider, id);
+    if (!['install', 'update', 'uninstall'].includes(kind)) throw httpError(400, 'Unknown operation', 'bad_request');
+    this._assertCanSpawn();
+    const key = id;
+    if (this.multiplexerOperations.has(key) || this.multiplexerStarts.has(key)) throw httpError(409, `${id} has another operation in progress. Try again shortly.`, 'install_in_progress');
+    this.multiplexerOperations.add(key);
+    this.registry.emit('updated');
+    let started = false;
+    try {
+      const prepared = await this.registry.multiplexers.prepare(provider, id, kind, copyPath);
+      if (id === 'herdr' && kind === 'uninstall') await this.registry.multiplexers.assertHerdrStopped(provider, prepared.copy, prepared.extraEnv);
+      // Herdr supports updates with servers and panes running, including brew.
+      // Uninstall's server check is never bypassed by force.
+      if (id === 'tmux') {
+        const { running, pending } = this.dependentsOf(providerId, id, prepared.copy);
+        if (running && !force) throw Object.assign(httpError(409, `${running} tmux card(s) depend on this installation. Changing it may prevent reattachment.`, 'multiplexer_in_use'), { running, pending });
+      }
+      this._assertCanSpawn();
+      const session = this._spawn({
+        provider, spawnSpec: prepared.spec, extraEnv: prepared.extraEnv, cwd: os.homedir(),
+        name: `${{ install: 'Install', update: 'Update', uninstall: 'Uninstall' }[kind]} ${id}`,
+        task: 'install', multiplexerInstall: { id, kind },
+      });
+      started = true;
+      // Keep the lock through refresh, and even if the installer card is removed.
+      session.exited.then(async () => {
+        try {
+          await this.registry.multiplexers.finish(provider, id, kind, prepared.copy, session.exitCode);
+          if (kind === 'update') {
+            // A detach during replacement may have probed a vanished release.
+            // Recheck closed cards once discovery has the new executable.
+            await Promise.all([...this.multiplexers].map(([cardId, tracked]) => {
+              const card = this.sessions.get(cardId);
+              return tracked.card.shell === id && card?.status === 'exited'
+                ? this._checkMultiplexer(card, tracked) : null;
+            }));
+          }
+        }
+        catch (err) { console.warn('[multiplexers] could not refresh:', err.message); }
+        finally {
+          this.multiplexerOperations.delete(key);
+          this.registry.emit('updated');
+          await this._restorePending();
+        }
+      }).catch((err) => console.warn('[multiplexers]', err.message));
+      return session;
+    } finally {
+      if (!started) {
+        this.multiplexerOperations.delete(key);
+        this.registry.emit('updated');
+      }
+    }
+  }
+
+  _restorePending() {
+    if (this.pendingRestore) {
+      this.pendingRestoreAgain = true;
+      return this.pendingRestore;
+    }
+    if (this.restoring || this.closing || !this.pendingCards.size) return Promise.resolve();
+    this.pendingRestore = (async () => {
+      const before = this.pendingCards.size;
+      do {
+        this.pendingRestoreAgain = false;
+        for (const card of [...this.pendingCards.values()]) {
+          if (this.closing) break;
+          if (this.multiplexerOperations.has(card.shell)) continue;
+          try { await this._withMultiplexerStart(card.provider, card.shell, () => this._restoreCard(card)); }
+          catch (err) {
+            // A capacity limit is temporary; never discard a recoverable card.
+            if (!['too_many_sessions', 'install_in_progress'].includes(err.code)) this.pendingCards.delete(card.id);
+          }
+        }
+      } while (this.pendingRestoreAgain && !this.closing);
+      this._saveCards();
+      if (before !== this.pendingCards.size) this.registry.emit?.('updated');
+    })().finally(() => { this.pendingRestore = null; });
+    return this.pendingRestore;
+  }
+
   /**
    * Upgrade the manager itself: a visible session running npm. Sessions
    * keep running; the new version is used once the manager is restarted.
@@ -470,7 +660,7 @@ export class SessionManager extends EventEmitter {
   _spawn({
     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, multiplexer = null,
-    id = newId(), reportToken = crypto.randomBytes(16).toString('hex'), createdAt,
+    id = newId(), reportToken = crypto.randomBytes(16).toString('hex'), createdAt, multiplexerInstall = null,
   }) {
     this._assertCanSpawn();
     const env = this._sessionEnv({ id, reportToken, provider, account, extraEnv, dropEnv });
@@ -504,7 +694,8 @@ export class SessionManager extends EventEmitter {
       if (this.sessions.has(id)) this.emit('event', { type: 'session.updated', session: session.toJSON() });
     });
     session.on('warning', (msg) => console.warn(`[session ${id}] ${msg}`));
-    if (task === 'install') {
+    session.multiplexerInstall = multiplexerInstall;
+    if (task === 'install' && !multiplexerInstall) {
       session.on('exit', () => {
         this.registry.finishInstall(provider.id, { exitCode: session.exitCode, kind: installKind, path: installPath }).catch(() => {});
       });

package/src/manager/uninstall.mjs

@@ -4,6 +4,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { buildSpawnSpec } from './command-resolver.mjs';
 import { formatCommand } from './install-channels.mjs';
+import { windowsPathCleanupScript } from './multiplexer-paths.mjs';
 
 export const RUNNER = fileURLToPath(import.meta.url);
 
@@ -72,9 +73,24 @@ function removeFile(file) {
 }
 
 export function runPlan(
-  { run = null, remove = [], links = [], launcher = null },
-  { env = process.env, platform = process.platform, log = console.log, rm = removeFile } = {},
+  { run = null, remove = [], links = [], launcher = null, pathEntries = null, strict = false },
+  { env = process.env, platform = process.platform, log = console.log, rm = removeFile, cleanPath = cleanWindowsPath } = {},
 ) {
+  if (strict) {
+    // An ancestor junction/symlink must not redirect deletion outside the
+    // server's allowlisted locations. The final launcher alias is handled below.
+    for (const file of [...remove, ...links]) {
+      if (!path.isAbsolute(file) || firstLink(path.dirname(file))) {
+        log(`Refused to remove ${file}: its parent is a link or the path is not absolute.`);
+        return 1;
+      }
+      const target = linkTarget(file);
+      if ((target && !within(target, remove, platform)) || (links.includes(file) && exists(file) && !target)) {
+        log(`Refused to remove ${file}: it is not an owned installation link.`);
+        return 1;
+      }
+    }
+  }
   if (run) {
     log(`> ${formatCommand(run.file, run.args)}`);
     const spec = buildSpawnSpec(run.file, run.args, env, platform);
@@ -133,6 +149,10 @@ export function runPlan(
       if (exists(file)) del(file);
       log(`Removed ${file}`);
     }
+    if (pathEntries && platform === 'win32') {
+      cleanPath(pathEntries, env);
+      log('Removed the installation’s entries from the user PATH.');
+    }
   } 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;
@@ -142,6 +162,13 @@ export function runPlan(
   return 0;
 }
 
+function cleanWindowsPath(rules, env) {
+  const powershell = path.win32.join(env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows', 'System32/WindowsPowerShell/v1.0/powershell.exe');
+  const encoded = Buffer.from(windowsPathCleanupScript(rules), 'utf16le').toString('base64');
+  const result = spawnSync(powershell, ['-NoLogo', '-NoProfile', '-EncodedCommand', encoded], { env, encoding: 'utf8', windowsHide: true, timeout: 10000 });
+  if (result.error || result.status !== 0) throw new Error(result.error?.message || result.stderr || 'Could not update user PATH. Retry Uninstall.');
+}
+
 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/src/manager/versions.mjs

@@ -10,6 +10,18 @@ export function parseVersion(text) {
   return match ? match[1] : null;
 }
 
+/** tmux uses two numbers and a patch letter; distributions add an epoch/revision. */
+export function parseTmuxVersion(text) {
+  return String(text || '').trim().match(/^(?:tmux\s+)?(?:\d+:)?(\d+\.\d+(?:_?[a-z])?)(?=$|[-+~\s])/i)?.[1]?.replace('_', '') ?? null;
+}
+
+export function compareTmuxVersions(a, b) {
+  const parts = (v) => /^(\d+)\.(\d+)([a-z]?)$/i.exec(parseTmuxVersion(v) || '');
+  const aa = parts(a), bb = parts(b);
+  if (!aa || !bb) return null;
+  return Number(aa[1]) - Number(bb[1]) || Number(aa[2]) - Number(bb[2]) || aa[3].localeCompare(bb[3]);
+}
+
 /** Semantic-version order: negative when a < b, positive when a > b. */
 export function compareVersions(a, b) {
   const [aMain, aPre] = String(a).split('-');

package/web/app.js

@@ -759,6 +759,8 @@ let dealt = false;
 
 function renderProviders() {
   const list = $('providers');
+  const focused = document.activeElement;
+  const focusKey = focused?.dataset?.muxFocus;
   const tpl = $('provider-template');
   list.replaceChildren(...state.providers.map((provider) => {
     const node = tpl.content.firstElementChild.cloneNode(true);
@@ -798,11 +800,20 @@ function renderProviders() {
     renderVendorLinks(node, provider);
     renderAccounts(node, provider);
     renderShells(node, provider);
+    renderMultiplexers(node, provider);
     renderUsage(node, provider);
     renderReportingSetup(node, provider);
     renderModelStats(node, provider);
     return node;
   }));
+  if (focusKey) {
+    const controls = [...list.querySelectorAll('[data-mux-focus]')];
+    const fallback = focusKey.split(':').slice(0, 2).join(':') + ':copies';
+    const replacement = controls.find((node) => node.dataset.muxFocus === focusKey && !node.disabled)
+      || controls.find((node) => node.dataset.muxFocus === fallback && !node.closest('[hidden]'))
+      || controls.find((node) => node.dataset.muxFocus === focusKey.split(':')[0] + ':multiplexers');
+    replacement?.focus({ preventScroll: true });
+  }
   if (!dealt && state.providers.length) {
     dealt = true;
     if (!reducedMotion.matches) list.classList.add('deal');
@@ -811,19 +822,21 @@ function renderProviders() {
 
 const openCopies = new Set();
 
-function renderCopies(box, provider, card) {
+function renderCopies(box, provider, card, actions = null) {
   const installs = provider.installs || [];
   const warnings = provider.warnings || [];
-  box.hidden = warnings.length === 0 && !installs.some((i) => i.uninstall);
+  box.hidden = actions ? installs.length === 0 : 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
+  box.querySelector('summary').textContent = installs.every((i) => i.partial) ? 'Incomplete installation' : !inUse
     ? 'A copy exists off PATH'
     : 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 key = actions?.key || provider.id;
+  box.open = openCopies.has(key);
+  box.addEventListener('toggle', () => (box.open ? openCopies.add(key) : openCopies.delete(key)));
+  if (actions) box.querySelector('summary').dataset.muxFocus = key + ':copies';
   const line = (className, ...content) => {
     const span = document.createElement('span');
     span.className = className;
@@ -842,6 +855,17 @@ function renderCopies(box, provider, card) {
     const where = line('copy-path', install.displayPath);
     where.title = install.path;
     item.append(head, where);
+    if (actions && install.updateCommand && (install.updateAvailable || install.versionStatus === 'failed')) {
+      const update = document.createElement('button');
+      update.type = 'button';
+      update.className = 'btn copy-update';
+      update.textContent = 'Update';
+      update.title = `Run ${install.updateCommand}`;
+      update.disabled = actions.busy;
+      update.dataset.muxFocus = key + ':update:' + install.path;
+      update.addEventListener('click', () => actions.update(install));
+      head.append(update);
+    } else if (actions && install.updateGuidance) item.append(line('copy-remove', install.updateGuidance));
     if (install.uninstall) {
       const button = document.createElement('button');
       button.type = 'button';
@@ -851,7 +875,11 @@ function renderCopies(box, provider, card) {
       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));
+      if (actions) {
+        button.disabled = actions.busy;
+        button.dataset.muxFocus = key + ':uninstall:' + install.path;
+      }
+      button.addEventListener('click', () => actions ? actions.uninstall(install) : uninstallCopy(provider, card, install));
       head.append(button);
     } else {
       item.append(line('copy-remove', install.uninstallGuidance));
@@ -860,6 +888,102 @@ function renderCopies(box, provider, card) {
   }));
 }
 
+const openMultiplexers = new Set();
+
+function renderMultiplexers(card, provider) {
+  const host = card.querySelector('.multiplexers');
+  const tools = provider.multiplexers || [];
+  host.hidden = tools.length === 0;
+  if (host.hidden) return;
+  host.open = openMultiplexers.has(provider.id);
+  host.querySelector('summary').dataset.muxFocus = provider.id + ':multiplexers';
+  host.addEventListener('toggle', () => host.open ? openMultiplexers.add(provider.id) : openMultiplexers.delete(provider.id));
+  const refresh = host.querySelector('.multiplexer-refresh');
+  refresh.dataset.muxFocus = provider.id + ':refresh';
+  refresh.addEventListener('click', async () => {
+    refresh.disabled = true;
+    try {
+      const result = await api('POST', '/providers/reload', {});
+      state.providers = result.providers;
+      renderProviders();
+    } catch (err) {
+      if (err instanceof AuthError) showAuth(err.message);
+      else toast(err.message, 10000);
+    } finally { refresh.disabled = false; }
+  });
+  host.querySelector('.multiplexer-list').replaceChildren(...tools.map((tool) => {
+    const row = document.createElement('section');
+    row.className = 'multiplexer-row';
+    const title = document.createElement('strong');
+    title.textContent = tool.tool;
+    row.append(title);
+    const key = provider.id + ':' + tool.id;
+    if (tool.installable) {
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.className = 'btn primary';
+      button.textContent = 'Install';
+      button.disabled = tool.busy;
+      button.title = tool.installCommand || '';
+      button.dataset.muxFocus = key + ':install';
+      button.addEventListener('click', () => manageMultiplexer(provider, tool, 'install'));
+      row.append(button);
+    }
+    const note = document.createElement('p');
+    note.className = 'multiplexer-note';
+    note.textContent = [
+      tool.busy ? 'Installation operation in progress…' : tool.guidance,
+      tool.pendingCards ? `${tool.pendingCards} detached ${tool.tool} card(s) are waiting to be restored. Check the installation or remove finished cards, then Refresh.` : '',
+      installNote(tool),
+    ].filter(Boolean).join(' ');
+    if (note.textContent) row.append(note);
+    const copies = document.createElement('details');
+    copies.className = 'copies';
+    copies.append(document.createElement('summary'), document.createElement('ul'));
+    row.append(copies);
+    renderCopies(copies, { ...tool, id: key, warnings: [] }, card, {
+      key, busy: tool.busy,
+      update: (copy) => manageMultiplexer(provider, tool, 'update', copy),
+      uninstall: (copy) => {
+        const plan = copy.uninstall;
+        const lines = [
+          `Uninstall ${tool.tool} from ${copy.displayPath}?`,
+          plan.command && `Runs: ${plan.command}`,
+          ...plan.remove.map((p) => `Removes: ${p}`),
+          plan.pathEntries && 'Removes only this installation’s entries from your user PATH.',
+          'Your settings and session data are kept.',
+        ].filter(Boolean);
+        if (confirm(lines.join('\n'))) return manageMultiplexer(provider, tool, 'uninstall', copy);
+      },
+    });
+    return row;
+  }));
+}
+
+async function manageMultiplexer(provider, tool, kind, copy = null, force = false) {
+  // Busy state also comes from the manager, covering other tabs and refreshes.
+  tool.busy = true;
+  renderProviders();
+  try {
+    const { session } = await api('POST', `/providers/${provider.id}/multiplexers/${tool.id}/${kind}`, { path: copy?.path, force });
+    upsertSession(session);
+    openPanel(session.id);
+  } catch (err) {
+    if (err instanceof AuthError) return showAuth(err.message);
+    if (err.code === 'multiplexer_in_use' && !force) {
+      const waiting = err.pending ? ` ${err.pending} detached cards are also waiting for the tool.` : '';
+      if (confirm(`${err.message}${waiting} Continue anyway?`)) return manageMultiplexer(provider, tool, kind, copy, true);
+    } else toast(err.message, 10000);
+  } finally {
+    // A successful operation stays busy until the manager sends fresh state.
+    try {
+      const result = await api('GET', '/providers');
+      state.providers = result.providers;
+    } catch { tool.busy = false; }
+    renderProviders();
+  }
+}
+
 function renderHint(hint, provider) {
   let text = '';
   if (!provider.available) text = provider.installable ? '' : provider.install || `${provider.command} was not found on PATH.`;
@@ -1887,7 +2011,7 @@ function renderChangelog() {
 }
 
 const CHANNEL_LABELS = {
-  npm: 'npm', native: 'native', brew: 'Homebrew', winget: 'WinGet', legacy: 'legacy install', unknown: 'unknown install',
+  npm: 'npm', native: 'native', brew: 'Homebrew', winget: 'WinGet', system: 'system package', legacy: 'legacy install', unknown: 'unknown install',
 };
 
 function installNote(provider) {

package/web/index.html

@@ -304,6 +304,11 @@
         <summary></summary>
         <ul></ul>
       </details>
+      <details class="multiplexers" hidden>
+        <summary>Terminal multiplexers</summary>
+        <button class="btn multiplexer-refresh" type="button">Refresh</button>
+        <div class="multiplexer-list"></div>
+      </details>
       <div class="provider-actions">
         <button class="btn primary new" type="button">New</button>
         <button class="btn existing" type="button">Existing…</button>

package/web/styles.css

@@ -736,3 +736,13 @@ a.news-link:visited { color: var(--muted); }
   .history-row .session-id { grid-row: 2; justify-self: start; }
   .history-form { flex-wrap: wrap; }
 }
+/* Installation controls share each skin's card colors and button styles. */
+.multiplexers { margin: .6rem 0; }
+.multiplexers > summary { cursor: pointer; font-size: .85rem; }
+.multiplexer-refresh { margin: .5rem 0; }
+.multiplexer-row { padding: .65rem 0; border-top: 1px solid var(--border); }
+.multiplexer-row > strong { margin-right: .6rem; }
+.multiplexer-note { font-size: .8rem; line-height: 1.5; overflow-wrap: anywhere; margin: .4rem 0; }
+.multiplexer-row .copies { margin-top: .4rem; }
+.multiplexer-row .copy-head { flex-wrap: wrap; }
+.multiplexer-row .copy-name { flex: 1 0 100%; }