@oddessentials/agent-guild 0.23.0 → 0.24.1

package/README.md

@@ -60,6 +60,11 @@ and come back to the same screens. Drag a session card by its grip, with a
 mouse or a finger, to put the cards in the order you want; this browser
 remembers it, and new sessions join at the end.
 
+On a touchscreen, **Copy…** opens a still copy of the terminal text. Touch and
+hold to select, then use **Copy selection** or the browser's Copy menu. **Done**
+returns to the live terminal; the session keeps running while you copy. The
+view includes retained scrollback, or the current screen of a full-screen tool.
+
 **Pick your shell.** The Shell card offers the shells installed on your
 computer and remembers your choice in this browser. On Windows it defaults
 to PowerShell 7 when installed, then Windows PowerShell; Git Bash and Command
@@ -78,6 +83,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 +252,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.1",
   "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 });
       }