@phnx-labs/agents-cli 1.22.39 → 1.22.40

package/dist/lib/mcp.js

@@ -14,9 +14,10 @@ import * as TOML from 'smol-toml';
 import { execFileSync } from 'child_process';
 import * as os from 'os';
 import { getMcpDir, getUserMcpDir, getProjectAgentsDir, getVersionsDir, getUserAgentsDir } from './state.js';
-import { getBinaryPath, getVersionHomePath } from './versions.js';
+import { getBinaryPath, getVersionHomePath } from './installations/versions.js';
 import { IS_WINDOWS, execFileShellSpec } from './platform/index.js';
-import { AGENTS, getMcpConfigPathForHome, getProjectMcpConfigPath } from './agents.js';
+import { AGENTS, getMcpConfigPathForHome, getProjectMcpConfigPath, stripJsonComments } from './agents.js';
+import { MCP_TARGETS, mcpWriteUnsupportedReason } from './mcp-registry.js';
 import { isCapable } from './capabilities.js';
 /**
  * Parse an MCP server config from a YAML file.
@@ -420,18 +421,15 @@ function registerMcpCommand(agentId, name, commandSpec, scope, transport, option
     try {
         validateMcpServerName(name);
         if (agentId === 'hermes') {
-            const server = {
-                name,
-                path: '',
-                config: {
+            // Hermes has no `mcp add` CLI; write its YAML config directly.
+            const home = options.home || os.homedir();
+            writeMcpConfig(agentId, getMcpConfigPathForHome(agentId, home), [{
                     name,
                     transport: transport === 'http' ? 'http' : 'stdio',
                     ...(transport === 'http'
                         ? { url: commandSpec.command }
                         : { command: commandSpec.command, args: commandSpec.args }),
-                },
-            };
-            installMcpToHermesConfig(server, options.home || os.homedir());
+                }], 'merge');
             return { success: true };
         }
         const bin = options.binary || AGENTS[agentId].cliCommand;
@@ -449,181 +447,71 @@ function registerMcpCommand(agentId, name, commandSpec, scope, transport, option
         return { success: false, error: err.message };
     }
 }
-/**
- * Install MCP server to Cursor config file.
- */
-function installMcpToCursorConfig(server, versionHome) {
-    const configPath = path.join(versionHome, '.cursor', 'mcp.json');
-    let config = {};
-    if (fs.existsSync(configPath)) {
-        config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-    }
-    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
-        config.mcpServers = {};
-    }
-    const mcpServers = config.mcpServers;
-    if (server.config.transport === 'stdio') {
-        mcpServers[server.name] = {
-            command: server.config.command,
-            args: server.config.args || [],
-            env: server.config.env || {},
-        };
-    }
-    else {
-        mcpServers[server.name] = {
-            url: server.config.url,
-        };
-    }
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
-}
-/**
- * Install MCP server to OpenCode config file.
- */
-function installMcpToKimiConfig(server, versionHome) {
-    const configPath = path.join(versionHome, '.kimi-code', 'mcp.json');
-    let config = {};
-    if (fs.existsSync(configPath)) {
-        config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-    }
-    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
-        config.mcpServers = {};
-    }
-    const mcpServers = config.mcpServers;
-    if (server.config.transport === 'stdio') {
-        mcpServers[server.name] = {
-            command: server.config.command,
-            args: server.config.args || [],
-            env: server.config.env || {},
-        };
-    }
-    else {
-        mcpServers[server.name] = {
-            url: server.config.url,
-        };
-    }
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+/** Project a discovered MCP server config into the writer's input shape. */
+function toWritableServer(server) {
+    return {
+        name: server.config.name,
+        transport: server.config.transport,
+        command: server.config.command,
+        args: server.config.args,
+        env: server.config.env,
+        url: server.config.url,
+    };
 }
 /**
- * Install MCP server to Factory AI Droid config (`~/.factory/mcp.json`).
- * Droid uses the standard `mcpServers` JSON shape, same as Kimi/Claude.
+ * Read an existing agent config, or `{}` when it does not exist yet.
+ *
+ * A file that exists but does not parse **throws** rather than resetting to
+ * `{}`: these configs hold far more than MCP (hermes' whole `config.yaml`,
+ * openclaw's `openclaw.json`, opencode's `opencode.jsonc`), so silently
+ * rewriting one from scratch destroys everything else in it. The five per-agent
+ * installers this replaced parsed unguarded for exactly that reason -- the throw
+ * surfaced as a reported error and left the file intact, which is the behavior
+ * preserved here.
  */
-function installMcpToFactoryConfig(server, versionHome) {
-    const configPath = path.join(versionHome, '.factory', 'mcp.json');
-    let config = {};
-    if (fs.existsSync(configPath)) {
-        config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-    }
-    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
-        config.mcpServers = {};
-    }
-    const mcpServers = config.mcpServers;
-    if (server.config.transport === 'stdio') {
-        mcpServers[server.name] = {
-            command: server.config.command,
-            args: server.config.args || [],
-            env: server.config.env || {},
-        };
-    }
-    else {
-        mcpServers[server.name] = {
-            url: server.config.url,
-        };
-    }
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
-}
-function installMcpToHermesConfig(server, versionHome) {
-    const configPath = path.join(versionHome, '.hermes', 'config.yaml');
-    let config = {};
-    if (fs.existsSync(configPath)) {
-        const parsed = yaml.parse(fs.readFileSync(configPath, 'utf-8'));
-        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-            config = parsed;
-        }
-    }
-    if (!config.mcp_servers || typeof config.mcp_servers !== 'object' || Array.isArray(config.mcp_servers)) {
-        config.mcp_servers = {};
-    }
-    const mcpServers = config.mcp_servers;
-    if (server.config.transport === 'stdio') {
-        mcpServers[server.name] = {
-            command: server.config.command,
-            args: server.config.args || [],
-            ...(server.config.env && { env: server.config.env }),
-        };
-    }
-    else {
-        mcpServers[server.name] = {
-            url: server.config.url,
-        };
-    }
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    fs.writeFileSync(configPath, yaml.stringify(config), 'utf-8');
-}
-function installMcpToOpenCodeConfig(server, versionHome) {
-    const configPath = path.join(versionHome, '.config', 'opencode', 'opencode.jsonc');
-    let config = {};
-    if (fs.existsSync(configPath)) {
-        const content = fs.readFileSync(configPath, 'utf-8');
-        // Strip JSONC comments
-        const jsonContent = content.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
-        try {
-            config = JSON.parse(jsonContent);
-        }
-        catch {
-            config = {};
-        }
-    }
-    if (!config.mcp || typeof config.mcp !== 'object') {
-        config.mcp = {};
+function readExistingConfig(configPath, parse) {
+    if (!fs.existsSync(configPath))
+        return {};
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    // An empty (or whitespace-only) file is "nothing recorded yet", not corruption
+    // -- a touched file or an interrupted write. `JSON.parse('')` throws, so
+    // without this an empty ~/.factory/mcp.json would fail the whole sync.
+    if (raw.trim() === '')
+        return {};
+    let parsed;
+    try {
+        parsed = parse(raw);
     }
-    const mcpServers = config.mcp;
-    if (server.config.transport === 'stdio') {
-        // OpenCode uses command as array
-        const commandArray = [server.config.command, ...(server.config.args || [])];
-        mcpServers[server.name] = {
-            type: 'local',
-            command: commandArray,
-            ...(server.config.env && { env: server.config.env }),
-        };
+    catch (err) {
+        throw new Error(`existing config at ${configPath} is not valid: ${err.message}`);
     }
-    else {
-        mcpServers[server.name] = {
-            type: 'remote',
-            url: server.config.url,
-        };
+    if (parsed === null || parsed === undefined)
+        return {};
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`existing config at ${configPath} is not an object`);
     }
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    return parsed;
 }
 /**
- * Agents whose config file format is implemented by `writeMcpConfig`.
- * Others are intentionally skipped until their schema is added.
+ * Parse a JSONC config.
+ *
+ * Uses the shared string-literal-aware `stripJsonComments` — the same one the
+ * read path uses on this very file. A regex that blanks `//` to end-of-line
+ * destroys `"$schema": "https://opencode.ai/config.json"`, which every
+ * opencode-generated config carries, and would make the writer disagree with
+ * the reader about the same bytes.
  */
-function writeMcpConfigSupportsAgent(agentId) {
-    switch (agentId) {
-        case 'claude':
-        case 'cursor':
-        case 'kimi':
-        case 'droid':
-        case 'openclaw':
-        case 'codex':
-        case 'grok':
-        case 'opencode':
-        case 'hermes':
-        case 'pi':
-        case 'muse':
-        case 'warp':
-            return true;
-        default:
-            return false;
-    }
+function parseJsonc(raw) {
+    return JSON.parse(stripJsonComments(raw));
 }
 /**
  * Serialize MCP servers into an agent-specific config file.
  *
+ * The format comes from `MCP_TARGETS` (lib/mcp-registry.ts), so a harness whose
+ * schema is not implemented **throws** here rather than falling through the
+ * switch and returning as if it had written something. `installMcpServers`
+ * catches that and reports it as an error, never as a silent success.
+ *
  * `mode: 'overwrite'` replaces the whole MCP section (used for tool-managed
  * version-home configs). `mode: 'merge'` updates/adds the provided server
  * entries while preserving existing entries (used for project-level configs
@@ -633,27 +521,19 @@ export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite')
     if (servers.length === 0) {
         return;
     }
-    switch (agentId) {
-        case 'claude':
-        case 'cursor':
-        case 'kimi':
-        case 'droid':
-        // omp reads the same Claude `{ "mcpServers": {...} }` schema from .mcp.json
-        // (stdio: command/args/env; http/sse: url/headers — transport inferred from
-        // command/url presence).
-        case 'pi':
-        // Oz reads the same Claude `{ "mcpServers": {...} }` schema from
-        // `.warp/.mcp.json` (stdio + http with headers).
-        case 'warp': {
-            let config = {};
-            if (fs.existsSync(configPath)) {
-                try {
-                    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-                }
-                catch {
-                    config = {};
-                }
-            }
+    // Narrowed, not asserted: this is what lets the `never` guard on the default
+    // arm below be a real compile-time check rather than a cosmetic one.
+    const target = MCP_TARGETS[agentId];
+    if (!target || target.format === null) {
+        throw new Error(`cannot write MCP config: ${mcpWriteUnsupportedReason(agentId)}`);
+    }
+    const format = target.format;
+    switch (format) {
+        // Claude's `{ "mcpServers": {...} }` schema, shared by cursor, kimi, droid,
+        // omp (.mcp.json) and Oz (.warp/.mcp.json): stdio carries command/args/env,
+        // remote carries url + optional headers.
+        case 'claude-json': {
+            const config = readExistingConfig(configPath, JSON.parse);
             const mcpServers = mode === 'merge' && config.mcpServers && typeof config.mcpServers === 'object'
                 ? { ...config.mcpServers }
                 : {};
@@ -677,16 +557,33 @@ export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite')
             fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
             break;
         }
-        case 'openclaw': {
-            let config = {};
-            if (fs.existsSync(configPath)) {
-                try {
-                    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        case 'antigravity-json': {
+            // agy reads ~/.gemini/config/mcp_config.json. Same `mcpServers` map as
+            // Claude for stdio, but a remote server is keyed `serverUrl` (SSE) and
+            // carries no headers — see agy's bundled docs/mcp_servers.md.
+            const config = readExistingConfig(configPath, JSON.parse);
+            const mcpServers = mode === 'merge' && config.mcpServers && typeof config.mcpServers === 'object'
+                ? { ...config.mcpServers }
+                : {};
+            for (const server of servers) {
+                if (server.transport === 'stdio') {
+                    mcpServers[server.name] = {
+                        command: server.command,
+                        args: server.args || [],
+                        env: server.env || {},
+                    };
                 }
-                catch {
-                    config = {};
+                else {
+                    mcpServers[server.name] = { serverUrl: server.url };
                 }
             }
+            config.mcpServers = mcpServers;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+            break;
+        }
+        case 'openclaw-json': {
+            const config = readExistingConfig(configPath, JSON.parse);
             if (!config.mcp || typeof config.mcp !== 'object') {
                 config.mcp = {};
             }
@@ -716,17 +613,8 @@ export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite')
             fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
             break;
         }
-        case 'codex':
-        case 'grok': {
-            let config = {};
-            if (fs.existsSync(configPath)) {
-                try {
-                    config = TOML.parse(fs.readFileSync(configPath, 'utf-8'));
-                }
-                catch {
-                    config = {};
-                }
-            }
+        case 'toml': {
+            const config = readExistingConfig(configPath, (raw) => TOML.parse(raw));
             const mcpServers = mode === 'merge' && config.mcp_servers && typeof config.mcp_servers === 'object'
                 ? { ...config.mcp_servers }
                 : {};
@@ -750,18 +638,8 @@ export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite')
             fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');
             break;
         }
-        case 'opencode': {
-            let config = {};
-            if (fs.existsSync(configPath)) {
-                try {
-                    const content = fs.readFileSync(configPath, 'utf-8');
-                    const jsonContent = content.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
-                    config = JSON.parse(jsonContent);
-                }
-                catch {
-                    config = {};
-                }
-            }
+        case 'opencode-jsonc': {
+            const config = readExistingConfig(configPath, parseJsonc);
             const mcp = mode === 'merge' && config.mcp && typeof config.mcp === 'object'
                 ? { ...config.mcp }
                 : {};
@@ -786,19 +664,8 @@ export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite')
             fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
             break;
         }
-        case 'hermes': {
-            let config = {};
-            if (fs.existsSync(configPath)) {
-                try {
-                    const parsed = yaml.parse(fs.readFileSync(configPath, 'utf-8'));
-                    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-                        config = parsed;
-                    }
-                }
-                catch {
-                    config = {};
-                }
-            }
+        case 'yaml': {
+            const config = readExistingConfig(configPath, (raw) => yaml.parse(raw));
             const mcpServers = mode === 'merge' && config.mcp_servers && typeof config.mcp_servers === 'object' && !Array.isArray(config.mcp_servers)
                 ? { ...config.mcp_servers }
                 : {};
@@ -821,19 +688,11 @@ export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite')
             fs.writeFileSync(configPath, yaml.stringify(config), 'utf-8');
             break;
         }
-        case 'muse': {
+        case 'muse-json': {
             // Muse Code settings.json: requires schema_version: 1; MCP lives under
             // mcp_servers with an explicit transport (stdio | streamable_http).
             // See https://dev.meta.ai/docs/muse-code/extending#mcp
-            let config = {};
-            if (fs.existsSync(configPath)) {
-                try {
-                    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-                }
-                catch {
-                    config = {};
-                }
-            }
+            const config = readExistingConfig(configPath, JSON.parse);
             if (config.schema_version === undefined) {
                 config.schema_version = 1;
             }
@@ -864,6 +723,14 @@ export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite')
             fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
             break;
         }
+        default: {
+            // Unreachable: mcpWriteUnsupportedReason above rejects a null format and
+            // every McpFormat has an arm. The assignment is deliberately NOT cast —
+            // `as never` would make it unfailable and the guard cosmetic. Adding an
+            // McpFormat without an arm above is a compile error here.
+            const unhandled = format;
+            throw new Error(`unhandled MCP config format: ${String(unhandled)}`);
+        }
     }
 }
 /**
@@ -892,79 +759,29 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
     for (const server of servers) {
         let handled = false;
         try {
-            if (agentId === 'claude') {
+            const target = MCP_TARGETS[agentId];
+            if (target?.cli === 'claude') {
                 installMcpViaClaude(binaryPath, server, versionHome);
                 handled = true;
             }
-            else if (agentId === 'codex') {
+            else if (target?.cli === 'codex') {
                 installMcpViaCodex(binaryPath, server, versionHome);
                 handled = true;
             }
-            else if (agentId === 'cursor') {
-                installMcpToCursorConfig(server, versionHome);
-                handled = true;
-            }
-            else if (agentId === 'opencode') {
-                installMcpToOpenCodeConfig(server, versionHome);
-                handled = true;
-            }
-            else if (agentId === 'openclaw') {
-                // OpenClaw has no install CLI; write the JSON config directly.
-                // Use merge because this loop runs once per server.
-                const userConfigPath = getMcpConfigPathForHome(agentId, versionHome);
-                const writableServer = {
-                    name: server.config.name,
-                    transport: server.config.transport,
-                    command: server.config.command,
-                    args: server.config.args,
-                    env: server.config.env,
-                    url: server.config.url,
-                };
-                writeMcpConfig(agentId, userConfigPath, [writableServer], 'merge');
-                handled = true;
-            }
-            else if (agentId === 'grok') {
-                // Grok has no working `grok mcp add` CLI, so write the TOML config
-                // directly into the version-home directory for all scopes.
-                // Use merge because this loop runs once per server.
-                const userConfigPath = getMcpConfigPathForHome(agentId, versionHome);
-                const writableServer = {
-                    name: server.config.name,
-                    transport: server.config.transport,
-                    command: server.config.command,
-                    args: server.config.args,
-                    env: server.config.env,
-                    url: server.config.url,
-                };
-                writeMcpConfig(agentId, userConfigPath, [writableServer], 'merge');
-                handled = true;
-            }
-            else if (agentId === 'kimi') {
-                installMcpToKimiConfig(server, versionHome);
-                handled = true;
-            }
-            else if (agentId === 'droid') {
-                installMcpToFactoryConfig(server, versionHome);
-                handled = true;
-            }
-            else if (agentId === 'hermes') {
-                installMcpToHermesConfig(server, versionHome);
+            else {
+                // No harness CLI for this agent (or none that works — `grok mcp add`
+                // does not register into the version home), so write its config file
+                // directly. `writeMcpConfig` throws for a harness whose format is not
+                // implemented, which the catch below turns into a reported error rather
+                // than a silent success. Merge, because this loop runs once per server.
+                writeMcpConfig(agentId, getMcpConfigPathForHome(agentId, versionHome), [toWritableServer(server)], 'merge');
                 handled = true;
             }
             // Project-layer servers also get merged into the agent's project-level
             // config (e.g., .mcp.json, .codex/config.toml) so the CLI discovers them
             // when run inside the repo.
-            if (server.scope === 'project' && options.cwd && writeMcpConfigSupportsAgent(agentId)) {
-                const projectConfigPath = getProjectMcpConfigPath(agentId, options.cwd);
-                const writableServer = {
-                    name: server.config.name,
-                    transport: server.config.transport,
-                    command: server.config.command,
-                    args: server.config.args,
-                    env: server.config.env,
-                    url: server.config.url,
-                };
-                writeMcpConfig(agentId, projectConfigPath, [writableServer], 'merge');
+            if (server.scope === 'project' && options.cwd) {
+                writeMcpConfig(agentId, getProjectMcpConfigPath(agentId, options.cwd), [toWritableServer(server)], 'merge');
                 handled = true;
             }
             if (handled) {

package/dist/lib/menubar/install-menubar.d.ts

@@ -14,6 +14,13 @@
  * migration (`installMenubarLaunchAgent` in migrate.ts) honors, so a disabled
  * menu bar never silently comes back on the next release.
  */
+/**
+ * launchd Label for this process's helper — the production identifier for a
+ * real invocation, namespaced under a redirected HOME (RUSH-2639). launchd
+ * routes bootout/bootstrap/kickstart by identifier alone, so without this a
+ * hermetic test fork's own teardown boots out the operator's live helper.
+ */
+export declare function serviceLabel(): string;
 /**
  * Absolute path to the installed MenubarHelper executable if it exists on disk,
  * else null. The desktop notifier (notify-desktop.ts) routes daemon

package/dist/lib/menubar/install-menubar.js

@@ -24,9 +24,19 @@ import { getRuntimeStateDir, getHelpersDir } from '../state.js';
 import { getCliVersion, resolveAgentsBin, resolveInstalledLayout } from '../version.js';
 import { copyAppBundle, withInstallLock } from '../app-bundle-install.js';
 import { compareVersions } from '../agent-spec/primitives.js';
+import { namespacedServiceLabel, serviceManifestHomeEnv } from '../service-manifest.js';
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
 const INSTALL_DIR_NAME = 'agents-cli';
-const SERVICE_LABEL = 'com.phnx-labs.agents-menubar';
+const SERVICE_LABEL_BASE = 'com.phnx-labs.agents-menubar';
+/**
+ * launchd Label for this process's helper — the production identifier for a
+ * real invocation, namespaced under a redirected HOME (RUSH-2639). launchd
+ * routes bootout/bootstrap/kickstart by identifier alone, so without this a
+ * hermetic test fork's own teardown boots out the operator's live helper.
+ */
+export function serviceLabel() {
+    return namespacedServiceLabel(SERVICE_LABEL_BASE);
+}
 /**
  * Minimum seconds between launchd restarts of the helper (`ThrottleInterval`).
  *
@@ -91,7 +101,7 @@ export function resolveInstalledMenubarExecutable() {
 }
 /** ~/Library/LaunchAgents/com.phnx-labs.agents-menubar.plist */
 function servicePlistPath() {
-    return path.join(os.homedir(), 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
+    return path.join(os.homedir(), 'Library', 'LaunchAgents', `${serviceLabel()}.plist`);
 }
 /** Sticky opt-out marker written by `agents menubar disable`. */
 function disabledSentinelPath() {
@@ -261,8 +271,16 @@ export function generateServicePlist(execPath) {
     // Bake interpreter + entry + bin so the GUI helper can reach the CLI with no
     // login PATH. AgentsCLI.swift prefers [AGENTS_NODE, AGENTS_ENTRY] when both
     // exist, else falls back to AGENTS_BIN, else probes well-known paths.
+    //
+    // HOME is baked for the same reason (RUSH-2639, see service-manifest.ts):
+    // launchd applies this dict on top of the LOGIN SESSION's environment, not the
+    // environment of whoever called `launchctl bootstrap`. Without the key the
+    // helper resolves the account home and every `agents` call it makes bootstraps
+    // that home's `~/.agents` — which is how a hermetic test fork's helper wrote
+    // into the runner's real home.
     const env = {
         PATH: `/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${path.dirname(process.execPath)}:${home}/.local/bin`,
+        ...serviceManifestHomeEnv(),
     };
     const node = process.execPath;
     const entry = resolveCliEntry();
@@ -281,7 +299,7 @@ export function generateServicePlist(execPath) {
 <plist version="1.0">
 <dict>
   <key>Label</key>
-  <string>${SERVICE_LABEL}</string>
+  <string>${serviceLabel()}</string>
   <key>ProgramArguments</key>
   <array>
     <string>${xmlEscape(execPath)}</string>
@@ -315,7 +333,7 @@ ${envXml}
  * is the only sequence that reliably re-attaches the status item.
  */
 export function restartMenubarLaunchAgent(uid, plist, exec = execFileSync) {
-    const serviceTarget = `gui/${uid}/${SERVICE_LABEL}`;
+    const serviceTarget = `gui/${uid}/${serviceLabel()}`;
     const opts = { stdio: ['ignore', 'ignore', 'ignore'] };
     try {
         exec('launchctl', ['bootout', serviceTarget], opts);
@@ -451,7 +469,7 @@ export function disableMenubarService() {
     const plist = servicePlistPath();
     const uid = process.getuid?.() ?? 0;
     try {
-        execFileSync('launchctl', ['bootout', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+        execFileSync('launchctl', ['bootout', `gui/${uid}/${serviceLabel()}`], { stdio: ['ignore', 'ignore', 'ignore'] });
     }
     catch {
         try {
@@ -727,7 +745,7 @@ export function runMenubarSetup() {
     // menu bar, so a stale `menubar disable` must not silently win.
     clearMenubarOptOut();
     installAndStartService(exec);
-    step('login item', before.serviceInstalled ? 'ok' : 'changed', `${SERVICE_LABEL} — starts at login, restarts if it dies`);
+    step('login item', before.serviceInstalled ? 'ok' : 'changed', `${serviceLabel()} — starts at login, restarts if it dies`);
     // launchd's bootstrap+kickstart is asynchronous; give the status item a beat
     // to claim the lock before counting instances, or `setup` reports zero on a
     // machine that is in fact coming up correctly.

package/dist/lib/menubar/snapshot.d.ts

@@ -18,6 +18,13 @@ export interface MenubarDevice {
 export interface MenubarSnapshot {
     version: 1;
     capturedAt: string;
+    /**
+     * The installed CLI version that produced this snapshot — the same string
+     * `agents --version` prints (RUSH-2688). The snapshot is emitted by whatever
+     * `agents` binary is on PATH, so this is resolved at runtime, letting the menu
+     * bar show its own version in the header and making a stale menu bar visible.
+     */
+    cliVersion: string;
     routines: Record<string, unknown>[];
     recentSessions: Record<string, unknown>[];
     activeSessions: Record<string, unknown>[];