@levr-one/cli 0.11.3 → 0.11.5

package/dist/{addHandler-Dh4elBBV.js → addHandler-BL1e6anD.js}

@@ -143,7 +143,10 @@ const CLAUDE_CODE_COMMAND = [
 	"{name}",
 	"{url}"
 ];
-/** `~/.claude.json` on every platform — read for detection, never written by us. */
+/**
+* `~/.claude.json` on every platform — read for detection, never written by us.
+* `~` is `$CLAUDE_CONFIG_DIR` when that is set (see `configDirEnv`).
+*/
 const CLAUDE_CODE_LOCATIONS = [
 	{
 		platform: "darwin",
@@ -232,6 +235,7 @@ const HARNESSES = [
 		docsUrl: "https://docs.anthropic.com/en/docs/claude-code/mcp",
 		verifiedVersion: UNVERIFIED_LEGACY,
 		verifiedOn: UNVERIFIED_LEGACY,
+		configDirEnv: "CLAUDE_CONFIG_DIR",
 		detectSignals: [
 			{
 				platform: "darwin",
@@ -275,7 +279,7 @@ const HARNESSES = [
 				installKind: "cli-command",
 				locations: CLAUDE_CODE_LOCATIONS,
 				command: CLAUDE_CODE_COMMAND,
-				cwdKeyedUnder: "projects"
+				projectKeyedUnder: "projects"
 			}
 		]
 	},
@@ -775,9 +779,20 @@ function defaultEnv() {
 		platform: process.platform,
 		homedir: homedir(),
 		pathVar: process.env.PATH ?? "",
-		cwd: process.cwd()
+		cwd: process.cwd(),
+		vars: process.env
 	};
 }
+/**
+* The directory `~` means for this harness's config paths and signals: the
+* harness's `configDirEnv` when that variable is set, else the home directory
+* (ENG-6696). A relative value resolves against `env.cwd`, the directory a
+* spawned client CLI runs in, so the probe and the client read one file.
+*/
+function configHome(harness, env) {
+	const dir = harness.configDirEnv ? env.vars?.[harness.configDirEnv] : void 0;
+	return dir ? resolve(env.cwd, dir) : env.homedir;
+}
 /** Expand a leading `~` / `~/…` to the given home directory. */
 function expandTilde(p, home) {
 	if (p === "~") return home;
@@ -807,7 +822,7 @@ function resolveConfigPath(harness, env, scope = defaultScope(harness)) {
 	if (def.projectPath) return join(resolveProjectRoot(env).root, ...def.projectPath.split("/"));
 	const loc = locationFor(harness, env.platform, scope);
 	if (!loc) return void 0;
-	return expandTilde(loc.configPath, env.homedir);
+	return expandTilde(loc.configPath, configHome(harness, env));
 }
 /**
 * Nearest ancestor of `cwd` containing `.git`, or `undefined`.
@@ -846,25 +861,75 @@ function resolveProjectRoot(env) {
 	};
 }
 /**
+* The key Claude Code files a `local`-scope entry under, in `projects[...]`,
+* for a client run from `env.cwd` (ENG-6696, observed on 2.1.296).
+*
+* It is the PROJECT, not the directory: from `repo/sub` the key is `repo`.
+* A linked git worktree keys to its MAIN checkout (the parent of the common
+* `.git`), a worktree of a bare repository to the bare directory, and a
+* submodule or `--separate-git-dir` checkout to its own work tree. Outside a
+* repository it is the directory itself. Always a real path, with `/`
+* separators on Windows (unverified there: drive-letter case). Claude reads
+* only this key, so an entry under any other key is invisible to it, and a
+* probe that looked elsewhere missed the entry and let `claude mcp add`
+* refuse.
+*/
+function projectKeyFor(env) {
+	return configKey(projectDir(env), env.platform);
+}
+/** Claude Code writes `projects` keys with `/` on Windows too. */
+function configKey(dir, platform) {
+	return platform === "win32" ? dir.replaceAll("\\", "/") : dir;
+}
+function projectDir(env) {
+	const cwd = realOrResolved(env.cwd);
+	const workTree = findRepoRoot(cwd);
+	if (!workTree) return cwd;
+	const dotGit = join(workTree, ".git");
+	let gitDir = dotGit;
+	try {
+		if (statSync(dotGit).isFile()) {
+			const m = /^gitdir:\s*([^\r\n]+)/.exec(readFileSync(dotGit, "utf8").trim());
+			if (!m?.[1]) return workTree;
+			gitDir = resolve(workTree, m[1].trim());
+		}
+	} catch {
+		return workTree;
+	}
+	const commonFile = readTextOrNull(join(gitDir, "commondir"));
+	if (commonFile === null) return workTree;
+	const common = realOrResolved(resolve(gitDir, commonFile.trim()));
+	if (!existsSync(common)) return workTree;
+	if (realOrResolved(dirname(gitDir)) !== join(common, "worktrees")) return workTree;
+	const back = readTextOrNull(join(gitDir, "gitdir"));
+	if (back === null || realOrResolved(dirname(resolve(gitDir, back.trim()))) !== workTree) return workTree;
+	if (basename(common) === ".git") return dirname(common);
+	return existsSync(join(common, ".git")) ? workTree : common;
+}
+function realOrResolved(p) {
+	try {
+		return realpathSync(p);
+	} catch {
+		return resolve(p);
+	}
+}
+/**
 * Where our server entry sits INSIDE a scope's config file.
 *
 * Usually `[<serverProperty>, 'levr']` at the top level. A scope declaring
-* `cwdKeyedUnder` nests one level deeper, keyed by the launch directory:
-* Claude Code's `local` scope lives at
-* `projects[<cwd>].mcpServers.levr` in `~/.claude.json`.
+* `projectKeyedUnder` nests one level deeper, under the project key: Claude
+* Code's `local` scope lives at `projects[<key>].mcpServers.levr` in
+* `~/.claude.json`, with `<key>` from {@link projectKeyFor}.
 *
-* `cwdKey` is passed in rather than read off the env because the key is
-* specifically the directory the CLIENT was launched in — which is NOT the
-* repo root, and callers should have to say which directory they mean.
 * Shared by detect and install so the two can never disagree about where an
 * entry lives.
 */
-function entryPathFor(harness, scope, cwdKey, serverName = DEFAULT_SERVER_NAME) {
+function entryPathFor(harness, scope, projectKey, serverName = DEFAULT_SERVER_NAME) {
 	const tail = [serverPropertyFor(harness, scope), serverName];
-	const nest = scopeDef(harness, scope)?.cwdKeyedUnder;
+	const nest = scopeDef(harness, scope)?.projectKeyedUnder;
 	return nest ? [
 		nest,
-		cwdKey,
+		projectKey,
 		...tail
 	] : tail;
 }
@@ -916,13 +981,14 @@ function collidingScope(harness, env, scope) {
 	if (!scopeDef(harness, scope)?.projectPath) return void 0;
 	const target = resolveConfigPath(harness, env, scope);
 	if (!target) return void 0;
-	const targetEntry = entryPathFor(harness, scope, env.cwd).join("\0");
+	const key = projectKeyFor(env);
+	const targetEntry = entryPathFor(harness, scope, key).join("\0");
 	for (const other of harness.scopes) {
 		if (other.scope === scope) continue;
 		const otherPath = resolveConfigPath(harness, env, other.scope);
 		if (!otherPath) continue;
 		if (!pathsResolveSame(target, otherPath, env.platform)) continue;
-		if (entryPathFor(harness, other.scope, env.cwd).join("\0") === targetEntry) return other.scope;
+		if (entryPathFor(harness, other.scope, key).join("\0") === targetEntry) return other.scope;
 	}
 }
 const WIN_EXTS = [
@@ -958,22 +1024,42 @@ function whichSync(bin, env) {
 	return whichPathSync(bin, env) !== void 0;
 }
 /** Does one `installSignals` entry match on this machine? Supports
-* `which:<bin>`, `~`-prefixed paths, and absolute (app-bundle) paths. */
-function signalMatches(signal, env) {
+* `which:<bin>`, `~`-prefixed paths, and absolute (app-bundle) paths. `home`
+* is what `~` means for the harness — see {@link configHome}. */
+function signalMatches(signal, env, home = env.homedir) {
 	if (signal.startsWith("which:")) return whichSync(signal.slice(6), env);
-	return existsSync(signal.startsWith("~") ? expandTilde(signal, env.homedir) : signal);
+	return existsSync(signal.startsWith("~") ? expandTilde(signal, home) : signal);
 }
 /**
 * The value our server key currently holds for this scope, or `undefined`.
 *
-* Presence alone is not enough for a `cli-command` scope: `claude mcp add` is
-* a no-op when the key exists, so telling "already correct" from "present but
-* pointing somewhere else" needs the value.
+* Presence alone is not enough for a `cli-command` scope: `claude mcp add`
+* refuses when the key exists and never updates its URL, so telling "already
+* correct" from "present but pointing somewhere else" needs the value.
 */
-function readServerEntry(harness, scope, configPath, cwdKey, parseJsonc, serverName = DEFAULT_SERVER_NAME) {
+function readServerEntry(harness, scope, configPath, projectKey, parseJsonc, serverName = DEFAULT_SERVER_NAME) {
 	const text = readTextOrNull(configPath);
 	if (!text) return void 0;
-	return getAtPath(parseJsonc(text), entryPathFor(harness, scope, cwdKey, serverName));
+	return getAtPath(parseJsonc(text), entryPathFor(harness, scope, projectKey, serverName));
+}
+/**
+* The http(s) URL an entry points at, read in every shape the catalog writes:
+* the harness's declared HTTP key (`url`, Antigravity's `serverUrl`), the last
+* argv of an `mcp-remote` spawn, or Zed's nested `command.args`. Anything that
+* is not an http(s) URL is not one — a script path in `args` must never be
+* mistaken for the server the entry points at.
+*/
+function entryUrl(harness, entry) {
+	if (entry === null || typeof entry !== "object") return void 0;
+	const e = entry;
+	const urlKey = harness.nativeHttpEntry?.urlKey ?? "url";
+	const command = e["command"];
+	const args = Array.isArray(e["args"]) ? e["args"] : command !== null && typeof command === "object" && Array.isArray(command.args) ? command.args : [];
+	return [
+		e[urlKey],
+		e["url"],
+		args[args.length - 1]
+	].find((c) => typeof c === "string" && /^https?:\/\//i.test(c));
 }
 /** Read a text file, or `null` if it doesn't exist / can't be read. */
 function readTextOrNull(path$1) {
@@ -1418,36 +1504,44 @@ function adapterFor(harness) {
 //#endregion
 //#region ../mcp-harnesses/dist/node/detect.js
 /**
-* Is our server key present for this scope?
+* Our server key's entry for this scope, or undefined when it is absent.
 *
 * Claude Code shares one file (`~/.claude.json`) between its `user` and
 * `local` scopes, so the two are told apart by WHERE in the file they sit,
 * not by which file is read — hence the entry path rather than a bare
 * top-level lookup.
 */
-function isServerConfigured(harness, scope, configPath, cwdKey) {
+function serverEntry(harness, scope, configPath, projectKey, serverName) {
 	const text = readTextOrNull(configPath);
-	if (!text) return false;
-	const read = adapterFor(harness).readAt(text, entryPathFor(harness, scope, cwdKey));
-	return read.kind === "value" && read.value !== null;
+	if (!text) return void 0;
+	const read = adapterFor(harness).readAt(text, entryPathFor(harness, scope, projectKey, serverName));
+	return read.kind === "value" && read.value !== null ? read.value : void 0;
 }
-function detectScope(harness, env, def) {
+function detectScope(harness, env, def, opts) {
 	const configPath = resolveConfigPath(harness, env, def.scope);
 	const inRepo = def.projectPath ? resolveProjectRoot(env).isRepo : true;
 	const collides = collidingScope(harness, env, def.scope) !== void 0;
 	const available = Boolean(configPath) && inRepo && !collides;
+	const read = (name) => available && configPath && name ? serverEntry(harness, def.scope, configPath, projectKeyFor(env), name) : void 0;
+	const entry = read(opts.serverName);
+	const currentUrl = entry === void 0 ? void 0 : entryUrl(harness, entry);
+	const beside = read(opts.besideName);
+	const besideUrl = beside === void 0 ? void 0 : entryUrl(harness, beside);
 	return {
 		scope: def.scope,
 		installKind: def.installKind,
 		configPath: available ? configPath ?? "" : "",
 		available,
-		alreadyConfigured: available && configPath ? isServerConfigured(harness, def.scope, configPath, env.cwd) : false
+		alreadyConfigured: entry !== void 0,
+		...currentUrl === void 0 ? {} : { currentUrl },
+		...besideUrl === void 0 ? {} : { besideUrl },
+		...beside === void 0 ? {} : { besideConfigured: true }
 	};
 }
-function detectOne(harness, env) {
-	const scopes = harness.scopes.map((def) => detectScope(harness, env, def));
+function detectOne(harness, env, opts) {
+	const scopes = harness.scopes.map((def) => detectScope(harness, env, def, opts));
 	const available = scopes.some((s) => s.available);
-	const installed = detectSignalsFor(harness, env.platform).some((s) => signalMatches(s, env)) || scopes.some((s) => s.configPath !== "" && existsSync(s.configPath));
+	const installed = detectSignalsFor(harness, env.platform).some((s) => signalMatches(s, env, configHome(harness, env))) || scopes.some((s) => s.configPath !== "" && existsSync(s.configPath));
 	const fallback = scopes.find((s) => s.scope === defaultScope(harness));
 	return {
 		id: harness.id,
@@ -1460,8 +1554,12 @@ function detectOne(harness, env) {
 	};
 }
 /** Synchronous detection over the whole catalog. Exported for tests. */
-function detectSync(env = defaultEnv()) {
-	return HARNESSES.map((h) => detectOne(h, env));
+function detectSync(env = defaultEnv(), opts = {}) {
+	const resolved = {
+		...opts,
+		serverName: opts.serverName ?? DEFAULT_SERVER_NAME
+	};
+	return HARNESSES.map((h) => detectOne(h, env, resolved));
 }
 
 //#endregion
@@ -1472,6 +1570,21 @@ const COMMAND_TIMEOUT_MS = 3e4;
 /** Keep a failing client's diagnostics readable in a multi-client report. */
 const MAX_STDERR = 2e3;
 /**
+* The variables a client CLI is spawned with: the real environment minus every
+* catalog `configDirEnv`, then `env.vars` on top (ENG-6696). A config
+* directory therefore reaches the child only when the caller's env carries it
+* — the one the probe read — so `claude` never writes a file the installer
+* did not look at, while PATH and the rest still come through.
+*/
+function childVars(env) {
+	const vars = { ...process.env };
+	for (const h of HARNESSES) if (h.configDirEnv) delete vars[h.configDirEnv];
+	return {
+		...vars,
+		...env.vars
+	};
+}
+/**
 * Windows batch launchers (`.cmd` / `.bat`) cannot be spawned directly.
 *
 * Since the CVE-2024-27980 fix (Node 18.20.2 / 20.12.2 / 21.7.2),
@@ -1532,7 +1645,7 @@ function runHarnessCommandSync(argv, opts = {}) {
 			],
 			timeout: COMMAND_TIMEOUT_MS,
 			env: {
-				...process.env,
+				...childVars(env),
 				HOME: env.homedir,
 				USERPROFILE: env.homedir
 			},
@@ -1587,7 +1700,7 @@ function currentEntry(harness, env, scope, serverName) {
 	const configPath = resolveConfigPath(harness, env, scope);
 	if (!configPath) return { present: false };
 	const adapter = adapterFor(harness);
-	const entry = readServerEntry(harness, scope, configPath, env.cwd, (t) => {
+	const entry = readServerEntry(harness, scope, configPath, projectKeyFor(env), (t) => {
 		const read = adapter.readAt(t, []);
 		return read.kind === "value" ? read.value : void 0;
 	}, serverName);
@@ -1598,25 +1711,6 @@ function currentEntry(harness, env, scope, serverName) {
 		url
 	};
 }
-/**
-* The http(s) URL an entry points at, read in every shape the catalog writes:
-* the harness's declared HTTP key (`url`, Antigravity's `serverUrl`), the last
-* argv of an `mcp-remote` spawn, or Zed's nested `command.args`. Anything that
-* is not an http(s) URL is not one — a script path in `args` must never be
-* mistaken for the server the entry points at.
-*/
-function entryUrl(harness, entry) {
-	if (entry === null || typeof entry !== "object") return void 0;
-	const e = entry;
-	const urlKey = harness.nativeHttpEntry?.urlKey ?? "url";
-	const command = e["command"];
-	const args = Array.isArray(e["args"]) ? e["args"] : command !== null && typeof command === "object" && Array.isArray(command.args) ? command.args : [];
-	return [
-		e[urlKey],
-		e["url"],
-		args[args.length - 1]
-	].find((c) => typeof c === "string" && /^https?:\/\//i.test(c));
-}
 /** `claude mcp remove` argv — the inverse of the catalog's add command. */
 function removeCommandArgv(scope, serverName) {
 	return [
@@ -1729,7 +1823,7 @@ function installHarnessSync(harness, mcpUrl, opts = {}) {
 	};
 	const { path: path$1 } = target;
 	const entryValue = buildServerEntry(harness, mcpUrl, scope, serverName)[serverName];
-	const modPath = entryPathFor(harness, scope, env.cwd, serverName);
+	const modPath = entryPathFor(harness, scope, projectKeyFor(env), serverName);
 	const adapter = adapterFor(harness);
 	const existing = readTextOrNull(path$1);
 	const baseText = existing && existing.trim() ? existing : adapter.empty;
@@ -2008,6 +2102,16 @@ function servedBySessionApi(mcpUrl) {
 }
 /** `…/v1/mcp/w/<url_key>`: the URL already names one workspace (ENG-6300). */
 const SCOPED_SUFFIX = /\/w\/[^/]+$/;
+/** The workspace a scoped MCP URL names (`…/w/<url_key>`), if any. */
+function workspaceKeyOf(url) {
+	const m = /\/w\/([^/]+)$/.exec(stripSlash(url));
+	if (!m?.[1]) return void 0;
+	try {
+		return decodeURIComponent(m[1]);
+	} catch {
+		return m[1];
+	}
+}
 /** Does this MCP URL already name a workspace? */
 function isScopedMcpUrl(url) {
 	return SCOPED_SUFFIX.test(stripSlash(url));
@@ -2068,14 +2172,54 @@ function findWorkspaceByKeyOrName(sites, input) {
 * what someone running an installer once expects: available in every project.
 */
 const DEFAULT_SCOPE = "user";
-/** Harness ids to pre-select in interactive mode: detected + installable +
-* not-already-configured. "Already configured" is judged in the scope we are
-* about to install into, not the harness's default one. */
-function autoSelectIds(detected, scope) {
+function entryState(s, url) {
+	if (s?.alreadyConfigured && s.currentUrl === url) return "same-url";
+	if (s?.besideUrl === url) return "beside";
+	if (!s?.alreadyConfigured) return "absent";
+	return s.currentUrl === void 0 ? "unrecognized" : "other-url";
+}
+/**
+* Allowed client entry names: 1-64 of `A-Za-z0-9_-`, and never starting with
+* `-`. The name is passed as an argv element to the client's own CLI
+* (`claude mcp add … <name> <url>`), so a leading `-` would be read there as a
+* flag — the ENG-4159 argument-injection family.
+*/
+const ENTRY_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+function isValidEntryName(name) {
+	return ENTRY_NAME.test(name) && !name.startsWith("-");
+}
+/**
+* The scope an install would land in: the requested one, or, for a harness
+* that cannot do it, its own default, which is where the fallback goes.
+*/
+function landingScope(d, scope) {
+	const inScope = scope ? d.scopes.find((s) => s.scope === scope) : void 0;
+	if (inScope) return inScope;
+	const harness = getHarness(d.id);
+	return harness ? d.scopes.find((s) => s.scope === defaultScope(harness)) : void 0;
+}
+/** Where an entry points, in the user's terms: the workspace, else the URL. */
+function describeTarget(url) {
+	const key = workspaceKeyOf(url);
+	return key ? `workspace ${key}` : url;
+}
+/**
+* Harness ids to pre-select in interactive mode, and to take under `--yes`:
+* detected + installable + not already set up for THIS url. Judged in the
+* scope we are about to install into, not the harness's default one.
+*
+* An entry pointing at another URL is selected (ENG-6736): it is not set up
+* for the workspace asked for, and skipping it would report success while
+* leaving the client on the old one. Interactively the user is then asked
+* what to do with it; under `--yes` the installer refuses it (url-mismatch,
+* exit 1) unless `--replace` or `--name` was given. An entry with no URL we
+* can read is someone else's, and is never picked on the user's behalf.
+*/
+function autoSelectIds(detected, scope, url) {
 	return detected.filter((d) => {
 		if (!d.available || !d.installed) return false;
-		const inScope = scope ? d.scopes.find((s) => s.scope === scope) : void 0;
-		return !(inScope ? inScope.alreadyConfigured : d.alreadyConfigured);
+		const state = entryState(landingScope(d, scope), url);
+		return state === "absent" || state === "other-url";
 	}).map((d) => d.id);
 }
 /**
@@ -2087,14 +2231,18 @@ function autoSelectIds(detected, scope) {
 * NOT configured at `project`, and labelling it "already set up" while
 * installing to `project` is simply wrong.
 */
-function clientChoices(detected, scope) {
-	const preselect = new Set(autoSelectIds(detected, scope));
+function clientChoices(detected, scope, url, serverName = DEFAULT_SERVER_NAME) {
+	const preselect = new Set(autoSelectIds(detected, scope, url));
+	const beside = besideName(serverName, url);
 	return detected.filter((d) => d.available).map((d) => {
 		const inScope = d.scopes.find((s) => s.scope === scope);
 		const harness = getHarness(d.id);
 		let hint;
 		if (!inScope) hint = `no ${scope} scope — will use ${harness ? defaultScope(harness) : DEFAULT_SCOPE}`;
-		else if (inScope.alreadyConfigured) hint = `already set up (${scope})`;
+		else if (entryState(inScope, url) === "same-url") hint = `already set up (${scope})`;
+		else if (entryState(inScope, url) === "beside") hint = `already set up as ${beside ?? "a second entry"} (${scope})`;
+		else if (inScope.currentUrl !== void 0) hint = `points at ${describeTarget(inScope.currentUrl)} (${scope})`;
+		else if (inScope.alreadyConfigured) hint = `its ${serverName} entry holds no Levr URL (${scope})`;
 		else hint = d.installed ? "detected" : "not detected";
 		return {
 			value: d.id,
@@ -2104,6 +2252,49 @@ function clientChoices(detected, scope) {
 		};
 	});
 }
+/** Claude Code tool names are `mcp__<entry>__<tool>`; keep that well short. */
+const BESIDE_NAME_MAX = 30;
+/**
+* The name for a second entry beside `serverName`: `<serverName>-<url_key>`,
+* so it says which workspace it is. Undefined — and "Add beside it" is not
+* offered — when the target URL names no workspace, or when that name would
+* be too long or not a valid entry name. It is never shortened: a cut name
+* could drop the workspace, or give two workspaces the same entry.
+*/
+function besideName(serverName, url) {
+	const key = workspaceKeyOf(url);
+	if (!key) return void 0;
+	const name = `${serverName}-${key}`;
+	return name.length <= BESIDE_NAME_MAX && isValidEntryName(name) ? name : void 0;
+}
+/**
+* The selected clients whose entry is not this URL's: each needs a decision —
+* switch it, add beside it, or leave it — before anything is installed
+* (ENG-6736). A client already set up beside it is listed too, as `beside`,
+* so it is installed under that name (and reads as already set up) rather
+* than refused under the main one. Pure, so it is testable without a TTY.
+*/
+function entryConflicts(selection, detected, scope, url, serverName) {
+	const conflicts = [];
+	const beside = besideName(serverName, url);
+	for (const id of selection) {
+		const d = detected.find((x) => x.id === id);
+		if (!d) continue;
+		const landing = landingScope(d, scope);
+		const state = entryState(landing, url);
+		if (state === "absent" || state === "same-url") continue;
+		const offer = state === "beside" || !landing?.besideConfigured;
+		conflicts.push({
+			id,
+			label: d.label,
+			state,
+			...landing?.currentUrl ? { currentUrl: landing.currentUrl } : {},
+			...beside && offer ? { besideName: beside } : {},
+			...beside && !offer ? { besideTaken: beside } : {}
+		});
+	}
+	return conflicts;
+}
 /** Scopes worth offering for a selection: any scope at least one selected
 * client can actually use here. Availability already accounts for "are we
 * inside a repo", so project scope disappears outside one. */
@@ -2146,11 +2337,13 @@ function installSelected(ids, plan, install) {
 		const canHonor = supportsScope(harness, plan.scope);
 		const named = plan.namedIds.has(id);
 		const effective = canHonor || named ? plan.scope : defaultScope(harness);
+		const override = plan.overrides?.get(id);
 		outcomes.push({
 			id,
 			label: harness.label,
-			result: install(harness, plan.mcpUrl, plan.dryRun, effective),
-			...canHonor ? {} : named ? {} : { fallbackFrom: plan.scope }
+			result: install(harness, plan.mcpUrl, plan.dryRun, effective, override),
+			...canHonor ? {} : named ? {} : { fallbackFrom: plan.scope },
+			...override?.serverName ? { entryName: override.serverName } : {}
 		});
 	}
 	return outcomes;
@@ -2161,7 +2354,7 @@ function installSelected(ids, plan, install) {
 * report. No console output — the caller formats it.
 */
 function runNonInteractive(options, url, urlSource, deps) {
-	const detected = deps.detect();
+	const detected = deps.detect(url);
 	const scope = options.scope ?? DEFAULT_SCOPE;
 	let ids;
 	let unknown = [];
@@ -2170,7 +2363,7 @@ function runNonInteractive(options, url, urlSource, deps) {
 		const requested = resolveRequestedIds(options, detected);
 		ids = requested.ids;
 		unknown = requested.unknown;
-	} else ids = autoSelectIds(detected, scope);
+	} else ids = autoSelectIds(detected, scope, url);
 	return {
 		url,
 		urlSource,
@@ -2186,22 +2379,45 @@ function runNonInteractive(options, url, urlSource, deps) {
 	};
 }
 /** Why an install was refused, in the user's terms rather than the enum's. */
-function failureText(o, switchCommand) {
+function failureText(o, switchCommand, entryName) {
 	const r = o.result;
 	const harness = getHarness(o.id);
 	switch (r.reason) {
 		case "unsupported-scope": return `no ${r.scope} scope` + (harness ? ` (supports: ${supportedScopes(harness).join(", ")})` : "");
 		case "not-a-repo": return "project scope needs a git repository (run from inside one)";
 		case "scope-collision": return `${r.scope} scope resolves to the same file as ${r.collidesWith ?? "another"} scope here — refusing rather than overwriting it`;
-		case "url-mismatch": return "already configured with a different URL" + (r.currentUrl ? ` (${r.currentUrl})` : "") + (switchCommand ? `; run \`${switchCommand}\` to switch it, or add --name <other> to keep both` : "; remove it first, then re-run");
+		case "url-mismatch": return "already configured with a different URL" + (r.currentUrl ? ` (${r.currentUrl})` : "") + (switchCommand ? `; run \`${switchCommand}\` to switch it, or add --name <other> to keep both` : `; ${removeHow(o, entryName)}, then re-run`);
 		case "unrecognized-entry": return "an entry of that name already exists but holds no Levr URL we can read; remove it from the client's config by hand, or add this one with --name <other>";
 		case "write-failed": return `its config could not be written` + (r.detail ? ` (${r.detail})` : "") + `; check the file's permissions and re-run`;
 		case "unsupported-config-shape": return `its config could not be edited safely` + (r.detail ? ` (${r.detail})` : "") + `; fix the file or add the entry by hand`;
 		default:
-			if (r.commandError) return `\`${r.command}\` (${r.commandError})${restoreText(r)}`;
+			if (r.commandError) return `\`${r.command}\` (${r.commandError})${restoreText(r)}` + alreadyExistsHint(o, r.commandError, entryName);
 			return "no config location on this platform";
 	}
 }
+/**
+* The client's CLI refused because the entry already exists, in a config the
+* installer did not read — otherwise it would have reported already set up,
+* or a url-mismatch naming --replace. --replace cannot reach an entry it
+* cannot see, so the way out is another name, or removing that entry with the
+* client's own CLI (ENG-6696).
+*/
+function alreadyExistsHint(o, commandError, entryName) {
+	if (!/already exists/i.test(commandError)) return "";
+	const name = entryName ?? DEFAULT_SERVER_NAME;
+	const scope = /already exists in (user|project|local) config/i.exec(commandError)?.[1]?.toLowerCase() ?? o.result.scope;
+	return `; to keep it, add this one beside it with --name <other>; to switch it, remove it with ${o.id === "claude-code" ? `\`claude mcp remove --scope ${scope} ${name}\`` : "the client's own CLI"} and re-run`;
+}
+/**
+* Where to remove an entry by hand: the exact command for Claude Code, else
+* the config file it sits in (ENG-6736).
+*/
+function removeHow(o, entryName) {
+	const name = entryName ?? DEFAULT_SERVER_NAME;
+	const r = o.result;
+	if (o.id === "claude-code") return `remove it with \`claude mcp remove --scope ${r.scope} ${name}\``;
+	return r.path ? `remove the ${name} entry from ${r.path}` : `remove the ${name} entry from the client's config`;
+}
 /** What happened to the entry a failed `--replace` removed (ENG-6300 D6). */
 function restoreText(r) {
 	if (r.restored === void 0) return "";
@@ -2209,13 +2425,16 @@ function restoreText(r) {
 	return `; the previous entry (${r.replacedUrl}) could NOT be restored` + (r.restoreError ? ` (${r.restoreError})` : "") + " — this client has no Levr entry of that name now";
 }
 /** One human-readable status line per outcome. */
-function outcomeLine(o, dryRun, switchCommand) {
+function outcomeLine(o, dryRun, switchCommand, entryName) {
 	const r = o.result;
-	const note = o.fallbackFrom ? ` [${o.fallbackFrom} scope unsupported — used ${r.scope}]` : "";
+	const note = (o.entryName ? ` [as ${o.entryName}]` : "") + (o.fallbackFrom ? ` [${o.fallbackFrom} scope unsupported — used ${r.scope}]` : "");
 	const where = r.path ? ` → ${r.path}` : "";
 	const backup = r.backupPath ? dryRun ? ` [original would be backed up to ${r.backupPath}]` : ` [original backed up to ${r.backupPath}]` : "";
 	const replaced = r.replacedUrl ? dryRun ? ` [would replace ${r.replacedUrl}]` : ` [replaced ${r.replacedUrl}]` : "";
-	if (!r.ok) return `${o.label}: failed — ${failureText(o, switchCommand)}`;
+	if (!r.ok) {
+		if (o.entryName) return `${o.label}: failed [as ${o.entryName}] — ${failureText(o, void 0, o.entryName)}`;
+		return `${o.label}: failed — ${failureText(o, switchCommand, entryName)}`;
+	}
 	if (r.alreadyConfigured) return `${o.label}: already set up (${r.scope})${where}${note}`;
 	if (r.command) {
 		if (r.executed) return `${o.label}: installed (${r.scope}) via \`${r.command}\`${replaced}${note}`;
@@ -2229,8 +2448,13 @@ function outcomeLine(o, dryRun, switchCommand) {
 function formatReport(report) {
 	const lines = [];
 	lines.push(`MCP URL: ${report.url} (${report.urlSource})`);
-	if (report.outcomes.length === 0) lines.push("No clients selected.");
-	else for (const o of report.outcomes) lines.push(outcomeLine(o, report.dryRun, report.switchCommand));
+	if (report.outcomes.length === 0 && (report.left ?? []).length === 0) lines.push("No clients selected.");
+	else for (const o of report.outcomes) lines.push(outcomeLine(o, report.dryRun, report.switchCommand, report.entryName));
+	for (const l of report.left ?? []) {
+		const why = l.currentUrl ? `points at ${describeTarget(l.currentUrl)}` : `its ${report.entryName ?? DEFAULT_SERVER_NAME} entry holds no Levr URL`;
+		const taken = l.besideTaken ? `; ${l.besideTaken} is taken too, so add this one with --name <other>` : "";
+		lines.push(`${l.label}: left as it was (${why}${taken})`);
+	}
 	if (report.unknownClients.length > 0) lines.push(`Unknown clients (skipped): ${report.unknownClients.join(", ")}`);
 	if (report.outcomes.some((o) => o.id === "claude-code" && o.result.ok)) lines.push(PLUGIN_TIP);
 	return lines.join("\n");
@@ -2240,7 +2464,7 @@ const PLUGIN_TIP = "Tip: the Levr plugin adds /levr:work, /levr:file and /levr:d
 /** Next-steps blurb after a run. */
 function nextStepsText(report) {
 	if (report.dryRun) return "Dry run — re-run without --dry-run to apply these changes.";
-	if (!report.outcomes.some((o) => o.result.wrote || o.result.executed || o.result.command)) return "Nothing to do.";
+	if (!report.outcomes.some((o) => o.result.ok && !o.result.alreadyConfigured && (o.result.wrote || o.result.executed || o.result.command))) return report.outcomes.some((o) => !o.result.ok) ? "Nothing was installed." : "Nothing to do.";
 	const lines = ["Next: restart the client(s) above — each will prompt you to authorize", "Levr once in the browser. Then ask it: \"What issues are assigned to me?\""];
 	if (report.outcomes.some((o) => o.result.scope === "project" && o.result.wrote)) lines.push("", "Project-scoped config was written into this repository — commit it to", "share the Levr MCP with everyone who checks it out.");
 	return lines.join("\n");
@@ -2248,25 +2472,18 @@ function nextStepsText(report) {
 
 //#endregion
 //#region src/commands/mcp/addHandler.ts
-/**
-* Allowed client entry names: 1-64 of `A-Za-z0-9_-`, and never starting with
-* `-`. The name is passed as an argv element to the client's own CLI
-* (`claude mcp add … <name> <url>`), so a leading `-` would be read there as a
-* flag — the ENG-4159 argument-injection family.
-*/
-const ENTRY_NAME = /^[A-Za-z0-9_-]{1,64}$/;
-function isValidEntryName(name) {
-	return ENTRY_NAME.test(name) && !name.startsWith("-");
-}
 function depsFor(entry) {
-	const install = (harness, mcpUrl, dryRun, scope) => installHarnessSync(harness, mcpUrl, {
+	const install = (harness, mcpUrl, dryRun, scope, override) => installHarnessSync(harness, mcpUrl, {
 		dryRun,
 		scope,
-		serverName: entry.serverName,
-		replaceExisting: entry.replaceExisting
+		serverName: override?.serverName ?? entry.serverName,
+		replaceExisting: override?.replaceExisting ?? entry.replaceExisting
 	});
 	return {
-		detect: () => detectSync(),
+		detect: (url) => detectSync(void 0, {
+			serverName: entry.serverName,
+			besideName: besideName(entry.serverName, url)
+		}),
 		install
 	};
 }
@@ -2380,7 +2597,8 @@ async function mcpAddHandler(flags) {
 	if (options.all || clients.length > 0 || options.yes || !process.stdout.isTTY) {
 		const report = {
 			...runNonInteractive(options, url, source, depsFor(entry)),
-			switchCommand: switchCommandFor(flags, urlKey)
+			switchCommand: switchCommandFor(flags, urlKey),
+			entryName: entry.serverName
 		};
 		this.process.stdout.write(`${formatReport(report)}\n`);
 		if (!isScopedMcpUrl(url) && servedBySessionApi(url)) {
@@ -2452,7 +2670,7 @@ async function interactive(ctx, dryRun, baseUrl, baseSource, flags, entry, resol
 		}
 	}
 	p.note(`${url}\n(${urlSource})`, "MCP endpoint");
-	const detected = deps.detect();
+	const detected = deps.detect(url);
 	const installable = detected.filter((d) => d.available);
 	if (installable.length === 0) {
 		p.outro("No supported MCP clients found on this machine.");
@@ -2477,7 +2695,7 @@ async function interactive(ctx, dryRun, baseUrl, baseSource, flags, entry, resol
 		}
 		scope = picked;
 	} else if (!requestedScope && choices.length === 1) scope = choices[0] ?? DEFAULT_SCOPE;
-	const rows = clientChoices(detected, scope);
+	const rows = clientChoices(detected, scope, url, entry.serverName);
 	const selection = await p.multiselect({
 		message: `Select clients to set up (${scope} scope)`,
 		options: rows.map((r) => ({
@@ -2497,13 +2715,64 @@ async function interactive(ctx, dryRun, baseUrl, baseSource, flags, entry, resol
 		p.outro("Nothing selected — bye.");
 		return;
 	}
+	const overrides = /* @__PURE__ */ new Map();
+	const left = [];
+	for (const c of entryConflicts(selection, detected, scope, url, entry.serverName)) {
+		if (c.state === "beside") {
+			if (c.besideName) overrides.set(c.id, {
+				serverName: c.besideName,
+				replaceExisting: false
+			});
+			continue;
+		}
+		if (c.state === "other-url" && entry.replaceExisting) continue;
+		const where = c.currentUrl ? `points at ${describeTarget(c.currentUrl)}` : "holds no Levr URL";
+		const options = [];
+		if (c.state === "other-url") options.push({
+			value: "switch",
+			label: `Switch it to ${describeTarget(url)}`,
+			hint: "replaces the entry"
+		});
+		if (c.besideName) options.push({
+			value: "beside",
+			label: `Add beside it as ${c.besideName}`,
+			hint: "keeps both; each repeats every tool"
+		});
+		options.push({
+			value: "leave",
+			label: "Leave it"
+		});
+		const answer = options.length === 1 ? "leave" : await p.select({
+			message: `${c.label}: its ${entry.serverName} entry ${where}` + (c.besideTaken ? `, and ${c.besideTaken} is taken too` : ""),
+			options
+		});
+		if (p.isCancel(answer)) {
+			p.cancel("Cancelled.");
+			ctx.process.exitCode = 1;
+			return;
+		}
+		if (answer === "switch") overrides.set(c.id, { replaceExisting: true });
+		else if (answer === "beside" && c.besideName) overrides.set(c.id, {
+			serverName: c.besideName,
+			replaceExisting: false
+		});
+		else left.push({
+			id: c.id,
+			label: c.label,
+			...c.currentUrl ? { currentUrl: c.currentUrl } : {},
+			...c.besideTaken ? { besideTaken: c.besideTaken } : {}
+		});
+	}
+	const leftIds = new Set(left.map((l) => l.id));
+	const toInstall = selection.filter((id) => !leftIds.has(id));
 	const spin = p.spinner();
 	spin.start(dryRun ? "Previewing changes" : "Installing");
-	const outcomes = installSelected(selection, {
+	const outcomes = installSelected(toInstall, {
 		mcpUrl: url,
 		dryRun,
 		scope,
-		namedIds: /* @__PURE__ */ new Set()
+		namedIds: /* @__PURE__ */ new Set(),
+		overrides
 	}, deps.install);
 	spin.stop(dryRun ? "Preview ready" : "Done");
 	const report = {
@@ -2513,7 +2782,9 @@ async function interactive(ctx, dryRun, baseUrl, baseSource, flags, entry, resol
 		outcomes,
 		unknownClients: [],
 		dryRun,
-		switchCommand: switchCommandFor(flags, urlKey)
+		switchCommand: switchCommandFor(flags, urlKey),
+		entryName: entry.serverName,
+		left
 	};
 	p.note(formatReport(report), "Results");
 	p.outro(nextStepsText(report));

package/dist/cli.js

@@ -125,9 +125,11 @@ the scope it does support, and the report says so.
 interactive run with several workspaces asks which one; a non-interactive run
 writes the unpinned URL and lists the --workspace choices.
 
-The entry is called "levr" unless you pass --name. An entry of that name that
-already points somewhere else is left alone: re-run with --replace to switch it
-to the new URL, or pick another --name to keep both side by side. Two entries
+The entry is called "levr" unless you pass --name. When an entry of that name
+already points somewhere else, the interactive picker asks whether to switch
+it, add a second one beside it, or leave it. A non-interactive run leaves it
+alone and exits 1: re-run with --replace to switch it to the new URL, or pick
+another --name to keep both side by side. Two entries
 means every Levr tool appears twice in that client, once per workspace.
 
 Interactive by default; non-interactive when --all/--client/--yes is passed
@@ -207,7 +209,7 @@ Examples:
 		aliases: { y: "yes" }
 	},
 	loader: async () => {
-		const { mcpAddHandler } = await import("./addHandler-Dh4elBBV.js");
+		const { mcpAddHandler } = await import("./addHandler-BL1e6anD.js");
 		return mcpAddHandler;
 	}
 });
@@ -874,7 +876,7 @@ Examples:
 
 //#endregion
 //#region package.json
-var version = "0.11.3";
+var version = "0.11.5";
 
 //#endregion
 //#region src/app.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levr-one/cli",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "description": "The command-line interface for Levr",
   "type": "module",
   "license": "MIT",