@oddessentials/agent-guild 0.1.0

package/node_modules/ws/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "ws",
+  "version": "8.22.0",
+  "description": "Simple to use, blazing fast and thoroughly tested websocket client and server for Node.js",
+  "keywords": [
+    "HyBi",
+    "Push",
+    "RFC-6455",
+    "WebSocket",
+    "WebSockets",
+    "real-time"
+  ],
+  "homepage": "https://github.com/websockets/ws",
+  "bugs": "https://github.com/websockets/ws/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/websockets/ws.git"
+  },
+  "author": "Einar Otto Stangvik <einaros@gmail.com> (http://2x.io)",
+  "license": "MIT",
+  "main": "index.js",
+  "exports": {
+    ".": {
+      "browser": "./browser.js",
+      "import": "./wrapper.mjs",
+      "require": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "browser": "browser.js",
+  "engines": {
+    "node": ">=10.0.0"
+  },
+  "files": [
+    "browser.js",
+    "index.js",
+    "lib/*.js",
+    "wrapper.mjs"
+  ],
+  "scripts": {
+    "test": "nyc --reporter=lcov --reporter=text mocha --throw-deprecation test/*.test.js",
+    "integration": "mocha --throw-deprecation test/*.integration.js",
+    "lint": "eslint . && prettier --check --ignore-path .gitignore \"**/*.{json,md,yaml,yml}\""
+  },
+  "peerDependencies": {
+    "bufferutil": "^4.0.1",
+    "utf-8-validate": ">=5.0.2"
+  },
+  "peerDependenciesMeta": {
+    "bufferutil": {
+      "optional": true
+    },
+    "utf-8-validate": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "benchmark": "^2.1.4",
+    "bufferutil": "^4.0.1",
+    "eslint": "^10.0.1",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.0.0",
+    "globals": "^17.0.0",
+    "mocha": "^8.4.0",
+    "nyc": "^15.0.0",
+    "prettier": "^3.0.0",
+    "utf-8-validate": "^6.0.0"
+  },
+  "allowScripts": {
+    "bufferutil": true,
+    "utf-8-validate": true
+  }
+}

package/node_modules/ws/wrapper.mjs

@@ -0,0 +1,21 @@
+import createWebSocketStream from './lib/stream.js';
+import extension from './lib/extension.js';
+import PerMessageDeflate from './lib/permessage-deflate.js';
+import Receiver from './lib/receiver.js';
+import Sender from './lib/sender.js';
+import subprotocol from './lib/subprotocol.js';
+import WebSocket from './lib/websocket.js';
+import WebSocketServer from './lib/websocket-server.js';
+
+export {
+  createWebSocketStream,
+  extension,
+  PerMessageDeflate,
+  Receiver,
+  Sender,
+  subprotocol,
+  WebSocket,
+  WebSocketServer
+};
+
+export default WebSocket;

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@oddessentials/agent-guild",
+  "version": "0.1.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": {
+    "type": "git",
+    "url": "git+https://github.com/oddessentials/agent-guild.git"
+  },
+  "homepage": "https://github.com/oddessentials/agent-guild#readme",
+  "bugs": {
+    "url": "https://github.com/oddessentials/agent-guild/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "agent-guild": "bin/agent-guild.mjs",
+    "agent-guild-report": "bin/agent-guild-report.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "web/",
+    "config/",
+    "examples/"
+  ],
+  "scripts": {
+    "start": "node bin/agent-guild.mjs open",
+    "manager": "node bin/agent-guild.mjs start",
+    "stop": "node bin/agent-guild.mjs stop",
+    "status": "node bin/agent-guild.mjs status",
+    "test": "node --test --test-concurrency=1"
+  },
+  "dependencies": {
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-serialize": "^0.14.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/headless": "^6.0.0",
+    "@xterm/xterm": "^6.0.0",
+    "node-pty": "^1.2.0-beta.15",
+    "ws": "^8.22.0"
+  },
+  "bundleDependencies": true,
+  "publishConfig": {
+    "access": "public"
+  },
+  "allowScripts": {
+    "node-pty@1.2.0-beta.15": true
+  }
+}

package/src/manager/command-resolver.mjs

@@ -0,0 +1,140 @@
+// Locate a provider's command on PATH and turn it into something node-pty can
+// spawn on every platform.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+
+function isExecutableFile(file, platform) {
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile()) return false;
+    if (platform === 'win32') return true;
+    fs.accessSync(file, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function windowsExtensions(env) {
+  const raw = env.PATHEXT || '.COM;.EXE;.BAT;.CMD';
+  const exts = raw.split(';').map((e) => e.trim().toLowerCase()).filter(Boolean);
+  // npm installs PowerShell shims too; accept them as a last resort.
+  if (!exts.includes('.ps1')) exts.push('.ps1');
+  return exts;
+}
+
+export function pathKey(env, platform = process.platform) {
+  // Windows environment keys are case-insensitive ("Path" is common).
+  return Object.keys(env).find((k) => k.toUpperCase() === 'PATH') || (platform === 'win32' ? 'Path' : 'PATH');
+}
+
+function getPath(env) {
+  return env[pathKey(env)] || '';
+}
+
+function candidateGroups(command, env, platform) {
+  const p = platform === 'win32' ? path.win32 : path.posix;
+  const hasExt = platform === 'win32' && p.extname(command) !== '';
+  const withExts = (base) =>
+    platform === 'win32' && !hasExt ? windowsExtensions(env).map((e) => base + e) : [base];
+
+  if (command.includes('/') || (platform === 'win32' && command.includes('\\'))) return [withExts(p.resolve(command))];
+  const groups = [];
+  const delimiter = platform === 'win32' ? ';' : ':';
+  for (const dir of getPath(env).split(delimiter)) {
+    if (!dir) continue;
+    const clean = dir.replace(/^"(.*)"$/, '$1');
+    groups.push(withExts(p.join(clean, command)));
+  }
+  return groups;
+}
+
+/**
+ * Resolve `command` to an absolute path, or return null when it is not
+ * installed. Commands that already contain a path separator are checked as-is.
+ * `isExecutable` is injectable so tests can simulate another platform.
+ */
+export function resolveCommand(command, env = process.env, platform = process.platform, {
+  isExecutable = (file) => isExecutableFile(file, platform),
+} = {}) {
+  if (!command) return null;
+  for (const group of candidateGroups(command, env, platform)) {
+    const hit = group.find((c) => isExecutable(c));
+    if (hit) return hit;
+  }
+  return null;
+}
+
+export function resolveAllCommands(command, env = process.env, platform = process.platform, {
+  isExecutable = (file) => isExecutableFile(file, platform),
+} = {}) {
+  if (!command) return [];
+  const seen = new Set();
+  const hits = [];
+  for (const group of candidateGroups(command, env, platform)) {
+    const hit = group.find((c) => isExecutable(c));
+    const id = hit && (platform === 'win32' ? hit.toLowerCase() : hit);
+    if (!hit || seen.has(id)) continue;
+    seen.add(id);
+    hits.push(hit);
+  }
+  return hits;
+}
+
+/** Quote one argument for a cmd.exe command line. */
+export function quoteForCmd(arg) {
+  const s = String(arg);
+  if (s !== '' && !/[\s"&|<>^()%!,;=]/.test(s)) return s;
+  return '"' + s.replace(/"/g, '""') + '"';
+}
+
+/**
+ * Build the file/args pair passed to node-pty. On Windows, batch shims
+ * (claude.cmd, codex.cmd, ...) must run through cmd.exe and PowerShell shims
+ * through powershell.exe; ConPTY cannot execute them directly.
+ */
+export function buildSpawnSpec(resolvedPath, args = [], env = process.env, platform = process.platform) {
+  if (platform !== 'win32') return { file: resolvedPath, args: [...args] };
+  const ext = path.win32.extname(resolvedPath).toLowerCase();
+  // Absolute paths: a bare name is looked up on the child's PATH, which a
+  // provider's own env may not carry.
+  const system32 = path.win32.join(env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows', 'System32');
+  if (ext === '.cmd' || ext === '.bat') {
+    const comspec = env.ComSpec || env.COMSPEC || path.win32.join(system32, 'cmd.exe');
+    const inner = [resolvedPath, ...args].map(quoteForCmd).join(' ');
+    // A raw command-line string: /s strips the outer quotes and keeps the rest.
+    return { file: comspec, args: `/d /s /c "${inner}"` };
+  }
+  if (ext === '.ps1') {
+    return {
+      file: path.win32.join(system32, 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
+      args: ['-NoLogo', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', resolvedPath, ...args],
+    };
+  }
+  return { file: resolvedPath, args: [...args] };
+}
+
+/**
+ * Run a spawn spec to completion without a terminal. Resolves with its
+ * output; rejects with the error carrying stdout and stderr.
+ */
+export function runSpec(spec, { env, timeoutMs = 15000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const opts = { env, timeout: timeoutMs, windowsHide: true, maxBuffer: 1024 * 1024 };
+    let args = spec.args;
+    if (typeof args === 'string') {
+      opts.windowsVerbatimArguments = true;
+      args = [args];
+    }
+    try {
+      execFile(spec.file, args, opts, (err, stdout, stderr) => {
+        if (err) reject(Object.assign(err, { stdout, stderr }));
+        else resolve({ stdout, stderr });
+      });
+    } catch (err) {
+      reject(err);
+    }
+  });
+}

package/src/manager/config.mjs

@@ -0,0 +1,94 @@
+// Filesystem locations, the auth token, and the runtime discovery file.
+//
+// Everything lives in one per-user directory so that other clients (the
+// launcher CLI, the agent reporter, a future Unreal Engine front end) can find
+// a running manager without being told its port or token.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const DEFAULT_PORT = 47821;
+export const DEFAULT_HOST = '127.0.0.1';
+export const VERSION = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+
+/** Per-user data directory. Override with AGENT_GUILD_HOME (used by tests). */
+export function dataDir() {
+  if (process.env.AGENT_GUILD_HOME) return path.resolve(process.env.AGENT_GUILD_HOME);
+  if (process.platform === 'win32') {
+    const base = process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
+    return path.join(base, 'AgentGuild');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'AgentGuild');
+  }
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'agent-guild');
+}
+
+export function ensureDataDir() {
+  const dir = dataDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+export const paths = {
+  get token() { return path.join(dataDir(), 'auth-token'); },
+  get runtime() { return path.join(dataDir(), 'manager.json'); },
+  get providers() { return path.join(dataDir(), 'providers.json'); },
+  get log() { return path.join(dataDir(), 'manager.log'); },
+  /** Launchers for agent-guild-report, put first on every session's PATH. */
+  get shims() { return path.join(dataDir(), 'bin'); },
+};
+
+function writePrivate(file, contents) {
+  fs.writeFileSync(file, contents, { mode: 0o600 });
+  // writeFileSync only applies mode on creation; tighten an existing file too.
+  try { fs.chmodSync(file, 0o600); } catch { /* not supported on Windows */ }
+}
+
+/**
+ * The API token guards every endpoint except /health. It persists across
+ * manager restarts so a bookmarked page keeps working. Delete the file to
+ * rotate it.
+ */
+export function loadOrCreateToken() {
+  ensureDataDir();
+  try {
+    const existing = fs.readFileSync(paths.token, 'utf8').trim();
+    if (/^[a-f0-9]{32,}$/.test(existing)) return existing;
+  } catch { /* create below */ }
+  const token = crypto.randomBytes(24).toString('hex');
+  writePrivate(paths.token, token + '\n');
+  return token;
+}
+
+export function writeRuntimeFile(info) {
+  ensureDataDir();
+  writePrivate(paths.runtime, JSON.stringify(info, null, 2) + '\n');
+}
+
+export function readRuntimeFile() {
+  try {
+    return JSON.parse(fs.readFileSync(paths.runtime, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function removeRuntimeFile(pid = process.pid) {
+  const current = readRuntimeFile();
+  if (current && current.pid !== pid) return; // another manager owns it
+  try { fs.unlinkSync(paths.runtime); } catch { /* already gone */ }
+}
+
+export function resolvePort() {
+  const raw = process.env.AGENT_GUILD_PORT;
+  if (raw === undefined || raw === '') return DEFAULT_PORT;
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error(`AGENT_GUILD_PORT must be an integer between 0 and 65535, got "${raw}"`);
+  }
+  return port;
+}

package/src/manager/install-channels.mjs

@@ -0,0 +1,268 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const CHANNEL_LABELS = {
+  npm: 'npm',
+  native: 'native',
+  brew: 'Homebrew',
+  winget: 'WinGet',
+  legacy: 'legacy install',
+  unknown: 'unknown install',
+};
+
+export const defaultFsx = {
+  exists: (file) => fs.existsSync(file),
+  realpath: (file) => {
+    try { return fs.realpathSync.native(file); } catch { return file; }
+  },
+  readText: (file) => {
+    try { return fs.readFileSync(file, 'utf8').slice(0, 8192); } catch { return ''; }
+  },
+  isFile: (file) => {
+    try { return fs.statSync(file).isFile(); } catch { return false; }
+  },
+  isLink: (file) => {
+    try { return fs.lstatSync(file).isSymbolicLink(); } catch { return false; }
+  },
+};
+
+function pathModule(platform) {
+  return platform === 'win32' ? path.win32 : path.posix;
+}
+
+export function homeDir(env, platform) {
+  return (platform === 'win32' ? env.USERPROFILE : env.HOME) || os.homedir();
+}
+
+export function expandHome(p, env, platform) {
+  const m = pathModule(platform);
+  if (p === '~') return homeDir(env, platform);
+  if (p.startsWith('~/') || p.startsWith('~\\')) return m.join(homeDir(env, platform), p.slice(2));
+  return p;
+}
+
+function normalize(p, platform) {
+  const m = pathModule(platform);
+  let out = m.normalize(p);
+  if (platform === 'win32') out = out.toLowerCase();
+  return out.length > 1 ? out.replace(/[\\/]+$/, '') : out;
+}
+
+function isInside(file, dir, platform) {
+  const m = pathModule(platform);
+  return normalize(file, platform).startsWith(normalize(dir, platform) + m.sep);
+}
+
+function samePath(a, b, platform) {
+  return normalize(a, platform) === normalize(b, platform);
+}
+
+function ownsLocation({ resolvedPath, realPath }, entries, env, platform, fsx) {
+  const exts = platform === 'win32' ? ['', '.exe', '.cmd'] : [''];
+  return entries.some((entry) => {
+    const expanded = expandHome(entry, env, platform);
+    const inside = (dir) => isInside(resolvedPath, dir, platform) || isInside(realPath, dir, platform);
+    if (inside(expanded) || inside(fsx.realpath(expanded))) return true;
+    return exts.map((ext) => expanded + ext)
+      .filter((launcher) => fsx.isFile(launcher) && !fsx.isLink(launcher))
+      .some((launcher) => samePath(resolvedPath, launcher, platform) || samePath(realPath, fsx.realpath(launcher), platform));
+  });
+}
+
+function npmPrefixAt(prefix, segments, platform, fsx) {
+  const m = pathModule(platform);
+  const win = platform === 'win32';
+  const pkgDir = win ? m.join(prefix, 'node_modules', ...segments) : m.join(prefix, 'lib', 'node_modules', ...segments);
+  if (!fsx.exists(m.join(pkgDir, 'package.json'))) return null;
+  const npm = win ? m.join(prefix, 'npm.cmd') : m.join(prefix, 'bin', 'npm');
+  return { prefix, pkgDir, npm: fsx.exists(npm) ? npm : null };
+}
+
+function npmBeside({ resolvedPath, realPath, pkg, platform, fsx }) {
+  const m = pathModule(platform);
+  const segments = pkg.split('/');
+  const dir = m.dirname(resolvedPath);
+  const beside = npmPrefixAt(platform === 'win32' ? dir : m.resolve(dir, '..'), segments, platform, fsx);
+  if (!beside) return null;
+  if (isInside(realPath, beside.pkgDir, platform) || isInside(realPath, fsx.realpath(beside.pkgDir), platform)) return beside;
+  if (fsx.isLink(resolvedPath)) return null;
+  const text = fsx.readText(resolvedPath).toLowerCase().replace(/\\/g, '/');
+  return text.includes(['node_modules', ...segments].join('/').toLowerCase()) ? beside : null;
+}
+
+function npmLinkedInto({ realPath, pkg, platform, fsx }) {
+  const m = pathModule(platform);
+  const win = platform === 'win32';
+  const segments = pkg.split('/');
+  const inner = m.sep + m.join(...(win ? [] : ['lib']), 'node_modules', ...segments) + m.sep;
+  const at = (win ? realPath.toLowerCase() : realPath).lastIndexOf(win ? inner.toLowerCase() : inner);
+  return at > 0 ? npmPrefixAt(realPath.slice(0, at), segments, platform, fsx) : null;
+}
+
+function brewOwner({ realPath, names, platform, fsx }) {
+  if (platform === 'win32') return null;
+  const segments = realPath.split('/');
+  const index = segments.findIndex((s, i) => i > 0 && (s === 'Caskroom' || s === 'Cellar'));
+  if (index === -1 || !names.includes(segments[index + 1])) return null;
+  const prefix = segments.slice(0, index).join('/') || '/';
+  const brew = `${prefix}/bin/brew`;
+  return { prefix, token: segments[index + 1], cask: segments[index] === 'Caskroom', brew: fsx.exists(brew) ? brew : null };
+}
+
+function wingetOwner({ realPath, id, platform }) {
+  if (platform !== 'win32' || !id) return null;
+  const segments = realPath.split(/[\\/]/);
+  const index = segments.findIndex((s, i) => i > 0
+    && s.toLowerCase() === 'winget'
+    && segments[i - 1].toLowerCase() === 'microsoft'
+    && (segments[i + 1] || '').toLowerCase() === 'packages');
+  if (index === -1) return null;
+  const folder = (segments[index + 2] || '').toLowerCase();
+  return folder.startsWith(`${id.toLowerCase()}_`) ? { id } : null;
+}
+
+export function helpDescribes(text, args) {
+  const words = args.map((a) => a.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  const named = new RegExp(`(?<![\\w-])${words.join('(?![\\w-]).*(?<![\\w-])')}(?![\\w-])`, 'i');
+  const lines = String(text || '').split(/\r?\n/);
+  return lines.some((line, i) => (/usage/i.test(line) && named.test(line))
+    || (/^\s*usage:?\s*$/i.test(line) && named.test(lines[i + 1] || '')));
+}
+
+const EXACT_VERSION = String.raw`\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?`;
+const ALIASED_BUILD = new RegExp(`^npm:((?:@[^/@\\s]+/)?[^/@\\s]+)@(${EXACT_VERSION})$`);
+
+export function platformDependency(manifest, pkg, platform, arch) {
+  const spec = manifest?.optionalDependencies?.[`${pkg}-${platform}-${arch}`];
+  const alias = typeof spec === 'string' ? spec.match(ALIASED_BUILD) : null;
+  return alias ? { name: alias[1], version: alias[2] } : null;
+}
+
+export function formatCommand(file, args) {
+  return [file, ...args].map((a) => (/\s/.test(a) ? `"${a}"` : a)).join(' ');
+}
+
+function shellQuote(arg, platform) {
+  if (platform === 'win32') return /^[\w\\/.:=+-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, "''")}'`;
+  return /^[\w/.:=,+@%-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
+export function shellCommand(file, args, platform) {
+  const command = shellQuote(file, platform);
+  const line = [command, ...args.map((arg) => shellQuote(arg, platform))].join(' ');
+  return platform === 'win32' && command !== file ? `& ${line}` : line;
+}
+
+export function classifyInstall({
+  resolvedPath, provider, env = process.env, platform = process.platform, fsx = defaultFsx, npmOnPath = null, wingetOnPath = null,
+}) {
+  const realPath = fsx.realpath(resolvedPath);
+  const channels = provider.channels || {};
+  const result = (channel, extra = {}) => ({ channel, resolvedPath, realPath, update: null, probe: false, guidance: null, ...extra });
+
+  const ownedByNpm = (owner) => {
+    const npm = owner.npm || npmOnPath;
+    if (!npm) return result('npm', { prefix: owner.prefix, guidance: `Installed by npm under ${owner.prefix}, but npm was not found.` });
+    return result('npm', { prefix: owner.prefix, update: { file: npm, args: ['install', '-g', '--prefix', owner.prefix], package: provider.package } });
+  };
+  const npmArgs = { resolvedPath, realPath, pkg: provider.package, platform, fsx };
+
+  const beside = provider.package ? npmBeside(npmArgs) : null;
+  if (beside) return ownedByNpm(beside);
+
+  const brew = brewOwner({ realPath, names: channels.brew?.names || [], platform, fsx });
+  if (brew) {
+    const owned = { brewPrefix: brew.prefix, token: brew.token, cask: brew.cask };
+    if (!brew.brew) return result('brew', { ...owned, guidance: `Installed by Homebrew under ${brew.prefix}, but brew was not found at ${brew.prefix}/bin/brew.` });
+    return result('brew', { ...owned, update: { file: brew.brew, args: brew.cask ? ['upgrade', '--cask', brew.token] : ['upgrade', brew.token] } });
+  }
+
+  const linked = provider.package ? npmLinkedInto(npmArgs) : null;
+  if (linked) return ownedByNpm(linked);
+
+  const native = channels.native;
+  if (native && ownsLocation({ resolvedPath, realPath }, native.paths, env, platform, fsx)) {
+    if (native.update.length === 0) {
+      return result('native', { guidance: `${provider.tool} at ${resolvedPath} has no update command configured. Update it the way you installed it.` });
+    }
+    return result('native', { update: { file: resolvedPath, args: [...native.update] }, probe: true });
+  }
+
+  const winget = wingetOwner({ realPath, id: channels.winget?.id, platform });
+  if (winget) {
+    if (!wingetOnPath) return result('winget', { wingetId: winget.id, guidance: 'Installed by WinGet, but winget was not found on PATH.' });
+    return result('winget', { wingetId: winget.id, update: { file: wingetOnPath, args: ['upgrade', '--id', winget.id, '--exact'] } });
+  }
+
+  const legacy = channels.legacy;
+  if (legacy && ownsLocation({ resolvedPath, realPath }, legacy.paths, env, platform, fsx)) {
+    return result('legacy', { guidance: legacy.guidance || `Installed by an older installer at ${resolvedPath}. Update it the way you installed it.` });
+  }
+
+  return result('unknown', { guidance: `Installed at ${resolvedPath} by a method Agent Guild does not recognise. Update it the way you installed it.` });
+}
+
+export function installationKey(install, provider, platform, fsx = defaultFsx) {
+  switch (install.channel) {
+    case 'npm':
+      return provider.channels?.native?.sharedWithNpm ? 'native' : `npm:${normalize(fsx.realpath(install.prefix), platform)}`;
+    case 'native':
+      return 'native';
+    case 'legacy':
+      return 'legacy';
+    case 'brew':
+      return `brew:${install.brewPrefix}:${install.token}`;
+    case 'winget':
+      return `winget:${install.wingetId.toLowerCase()}`;
+    default:
+      return `path:${normalize(install.realPath, platform)}`;
+  }
+}
+
+export function removalCommand(install, provider, platform) {
+  switch (install.channel) {
+    case 'npm':
+      return install.update ? shellCommand(install.update.file, ['uninstall', '-g', '--prefix', install.prefix, provider.package], platform) : null;
+    case 'brew':
+      return install.update ? shellCommand(install.update.file, install.cask ? ['uninstall', '--cask', install.token] : ['uninstall', install.token], platform) : null;
+    case 'winget':
+      return shellCommand('winget', ['uninstall', '--id', install.wingetId, '--exact'], platform);
+    case 'native':
+      return provider.channels?.native?.uninstall || null;
+    case 'legacy':
+      return provider.channels?.legacy?.uninstall || null;
+    default:
+      return null;
+  }
+}
+
+export function knownLaunchers({ provider, command, env = process.env, platform = process.platform, fsx = defaultFsx }) {
+  if (!command || /[\\/]/.test(command)) return [];
+  const m = pathModule(platform);
+  const exts = platform === 'win32' ? ['.exe', '.cmd', ''] : [''];
+  const firstFile = (base) => exts.map((ext) => base + ext).find((file) => fsx.isFile(file)) || null;
+  const found = [];
+  for (const channel of [provider.channels?.native, provider.channels?.legacy]) {
+    for (const entry of channel?.paths || []) {
+      const base = expandHome(entry, env, platform);
+      const hit = firstFile(base) || firstFile(m.join(base, command));
+      if (hit) found.push(hit);
+    }
+  }
+  return found;
+}
+
+export function listInstallations({
+  onPath = [], known = [], provider, env = process.env, platform = process.platform, fsx = defaultFsx, npmOnPath = null, wingetOnPath = null,
+}) {
+  const installs = new Map();
+  const add = (file, isOnPath) => {
+    const install = classifyInstall({ resolvedPath: file, provider, env, platform, fsx, npmOnPath, wingetOnPath });
+    const key = installationKey(install, provider, platform, fsx);
+    if (!installs.has(key)) installs.set(key, { ...install, key, onPath: isOnPath, removeCommand: removalCommand(install, provider, platform) });
+  };
+  for (const file of onPath) add(file, true);
+  for (const file of known) add(file, false);
+  return [...installs.values()];
+}