@phnx-labs/agents-cli 1.22.47 → 1.22.50

package/dist/lib/installations/versions.js

@@ -34,7 +34,7 @@ import { discoverPermissionGroups, getActivePermissionPresetName, readPermission
 import { parseMcpConfigForScan, isProjectMcpTrusted } from '../mcp.js';
 import { createVersionedAlias, removeVersionedAlias, switchConfigSymlink, getConfigSymlinkVersion, ensureClaudeInsideSymlink, assertIsolationBoundary, isIsolationProtected, } from './shims.js';
 import { importInstallScriptBinary } from '../import.js';
-import { createInstallation, getBinaryPath, getCliVersionFromPath, getGlobalDefault, getIsolatedDefault, getLiveVersion, getVersionDir, getVersionHomePath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, isGlobalBinaryAgent, isVersionInstalled, isVersionIsolated, listInstalledVersions, pickCanonicalGlobalBinaryVersion, resolveVersion, } from './store.js';
+import { createInstallation, getBinaryPath, getCliVersionFromPath, getGlobalDefault, getIsolatedDefault, getLiveVersion, getVersionDir, getVersionHomePath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, isGlobalBinaryAgent, isVersionInstalled, isVersionIsolated, listInstalledVersions, pickCanonicalGlobalBinaryVersion, resolveGrokFallbackBinary, resolveVersion, } from './store.js';
 export * from './store.js';
 import { INSTALLATION_RECORD_FILE } from './types.js';
 import { composeWin32CommandLine } from '../platform/index.js';
@@ -52,6 +52,7 @@ import { getWriter, getDetector } from '../staleness/registry.js';
 import { syncMemoryToVersionHome } from '../memory.js';
 import { listPluginSkillNames, resolveCommandSource, resolveSkillSource } from '../staleness/writers/sources.js';
 import { syncProjectResourcesToAgent } from '../project-resources.js';
+import { installClaudeStatusLine } from '../claude-statusline.js';
 /** Promisified exec for running shell commands. */
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
@@ -120,6 +121,17 @@ function sourceMapFromWorkflows(cwd) {
         .filter(d => d.isDirectory() && fs.existsSync(path.join(dir, d.name, 'WORKFLOW.md')))
         .map(d => d.name));
 }
+// A plugin is a directory whose marker is `.claude-plugin/plugin.json`. Attribute
+// each to the layer it actually resolves from (system / user / project / extra) —
+// the same first-wins resolution the plugins staleness checker uses. Hardcoding
+// 'user' here made a `system:*` selection expand to zero plugins, so
+// `agents sync <agent> system` silently skipped system-layer plugins like `swarm`
+// (RUSH-3207).
+function sourceMapFromPlugins(cwd) {
+    return sourceMapFromLayeredDirectory(cwd, ['plugins'], (dir) => fs.readdirSync(dir, { withFileTypes: true })
+        .filter(d => d.isDirectory() && fs.existsSync(path.join(dir, d.name, '.claude-plugin', 'plugin.json')))
+        .map(d => d.name));
+}
 function sourceMapFromPluginSkills(plugins, activePluginNames, cwd) {
     const sourceRank = new Map([
         ['user', 0],
@@ -1020,9 +1032,9 @@ export function setIsolatedDefault(agent, version) {
 /**
  * Move any `grok-<installedVersion>-...` binary (and its generic platform
  * copy) found directly under `sourceDownloads` into `targetDownloads`.
- * Returns true if the versioned binary was moved.
+ * Returns true if the versioned binary was transferred.
  */
-function tryMoveGrokDownloads(sourceDownloads, targetDownloads, installedVersion) {
+function transferGrokDownloads(sourceDownloads, targetDownloads, copy) {
     if (!fs.existsSync(sourceDownloads))
         return false;
     if (path.resolve(sourceDownloads) === path.resolve(targetDownloads))
@@ -1030,42 +1042,36 @@ function tryMoveGrokDownloads(sourceDownloads, targetDownloads, installedVersion
     const entries = fs.readdirSync(sourceDownloads).filter((e) => e.startsWith('grok-'));
     if (entries.length === 0)
         return false;
-    const escapedVersion = installedVersion.replace(/\./g, '\\.');
-    const versionedPattern = new RegExp(`^grok-${escapedVersion}-`);
-    const movedPaths = [];
-    // Move the versioned binary first — only create the target dir once we
-    // know there is something to move into it.
-    for (const entry of entries) {
-        if (!versionedPattern.test(entry))
-            continue;
-        const src = path.join(sourceDownloads, entry);
-        const dst = path.join(targetDownloads, entry);
-        if (fs.existsSync(dst))
-            continue;
-        try {
-            fs.mkdirSync(targetDownloads, { recursive: true });
-            fs.renameSync(src, dst);
-            movedPaths.push(dst);
-        }
-        catch {
-            /* ignore per-file failures */
-        }
+    const realBinary = resolveGrokFallbackBinary(sourceDownloads);
+    if (!realBinary)
+        return false;
+    const transferred = path.join(targetDownloads, path.basename(realBinary));
+    try {
+        fs.mkdirSync(targetDownloads, { recursive: true });
+        if (copy)
+            fs.copyFileSync(realBinary, transferred);
+        else
+            fs.renameSync(realBinary, transferred);
     }
-    if (movedPaths.length === 0)
+    catch {
         return false;
+    }
     // The installer also creates a generic platform binary (e.g. grok-macos-aarch64)
     // that is a copy of the versioned binary. Move it too if its size matches.
-    const movedSize = fs.statSync(movedPaths[0]).size;
+    const movedSize = fs.statSync(transferred).size;
     for (const entry of entries) {
-        if (versionedPattern.test(entry))
-            continue; // already handled
+        if (entry === path.basename(realBinary))
+            continue;
         const src = path.join(sourceDownloads, entry);
         const dst = path.join(targetDownloads, entry);
         if (fs.existsSync(dst))
             continue;
         try {
             if (fs.statSync(src).size === movedSize) {
-                fs.renameSync(src, dst);
+                if (copy)
+                    fs.copyFileSync(src, dst);
+                else
+                    fs.renameSync(src, dst);
             }
         }
         catch {
@@ -1087,7 +1093,7 @@ function tryMoveGrokDownloads(sourceDownloads, targetDownloads, installedVersion
  * whatever version was default at the time), sweep every other installed
  * grok version home for the missing file before giving up.
  */
-function relocateGrokBinaryToVersionHome(installedVersion) {
+function relocateGrokBinaryToVersionHome(installationLabel, copyExisting) {
     const hostGrokLink = path.join(getHomeDir(), agentConfigDirName('grok'));
     let sourceDownloads;
     try {
@@ -1096,16 +1102,16 @@ function relocateGrokBinaryToVersionHome(installedVersion) {
     catch {
         sourceDownloads = path.join(hostGrokLink, 'downloads');
     }
-    const targetDownloads = path.join(getVersionHomePath('grok', installedVersion), agentConfigDirName('grok'), 'downloads');
-    if (tryMoveGrokDownloads(sourceDownloads, targetDownloads, installedVersion))
+    const targetDownloads = path.join(getVersionHomePath('grok', installationLabel), agentConfigDirName('grok'), 'downloads');
+    if (transferGrokDownloads(sourceDownloads, targetDownloads, copyExisting))
         return;
     for (const version of listInstalledVersions('grok')) {
-        if (version === installedVersion)
+        if (version === installationLabel)
             continue;
         const candidate = path.join(getVersionHomePath('grok', version), agentConfigDirName('grok'), 'downloads');
         if (path.resolve(candidate) === path.resolve(sourceDownloads))
             continue; // already tried
-        if (tryMoveGrokDownloads(candidate, targetDownloads, installedVersion))
+        if (transferGrokDownloads(candidate, targetDownloads, copyExisting))
             return;
     }
 }
@@ -1146,6 +1152,7 @@ async function checkGrokAccountCollision(installedVersion) {
  */
 export async function installVersion(agent, version, onProgress, opts) {
     const agentConfig = AGENTS[agent];
+    const requestedLabel = version;
     if (isAgentHardDeprecated(agent)) {
         return { success: false, installedVersion: version, error: hardDeprecationError(agent) };
     }
@@ -1177,7 +1184,7 @@ export async function installVersion(agent, version, onProgress, opts) {
             }
             version = 'latest';
         }
-        let installedVersion = version;
+        let releaseVersion = version;
         try {
             if (runInstaller) {
                 const script = agentConfig.installScript.replaceAll('VERSION', version);
@@ -1206,13 +1213,19 @@ export async function installVersion(agent, version, onProgress, opts) {
                         error: `${agentConfig.name} installed but its version could not be determined after several attempts.`,
                     };
                 }
-                installedVersion = probed;
+                releaseVersion = probed;
                 // Fold any stale literal `latest` dir from an earlier probe-failed
                 // install into the real version so it stops shadowing `agents view`.
-                await reconcileStaleLatestDir(agent, installedVersion);
+                await reconcileStaleLatestDir(agent, releaseVersion);
             }
+            // Self-updating installers always fetch the current vendor release, but a
+            // concrete requested token is still the stable installation/account slot.
+            // Keeping the two strings separate lets several homes carry the same
+            // release without sharing credentials. `latest` remains the convenient
+            // release-named slot; concrete tokens remain exactly addressable.
+            const installationLabel = requestedLabel === 'latest' ? releaseVersion : requestedLabel;
             if (agent === 'grok') {
-                await checkGrokAccountCollision(installedVersion);
+                await checkGrokAccountCollision(installationLabel);
             }
             onProgress?.(`${agentConfig.name} installed. Setting up agents-cli version home for isolation...`);
         }
@@ -1221,14 +1234,15 @@ export async function installVersion(agent, version, onProgress, opts) {
             return { success: false, installedVersion: version, error: `${agentConfig.name} installer failed: ${err.message}` };
         }
         ensureAgentsDir();
-        const versionDir = getVersionDir(agent, installedVersion);
+        const installationLabel = requestedLabel === 'latest' ? releaseVersion : requestedLabel;
+        const versionDir = getVersionDir(agent, installationLabel);
         fs.mkdirSync(versionDir, { recursive: true });
         fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
         // Grok's installer drops the binary into ~/.grok/downloads, which currently
         // resolves to the PREVIOUS default home. Move it into the target version home
         // so version isolation is correct.
         if (agent === 'grok') {
-            relocateGrokBinaryToVersionHome(installedVersion);
+            relocateGrokBinaryToVersionHome(installationLabel, !runInstaller);
         }
         // Symlink the installed binary into the version's node_modules/.bin so
         // listInstalledVersions (which checks getBinaryPath) sees this version as
@@ -1253,26 +1267,26 @@ export async function installVersion(agent, version, onProgress, opts) {
             // that exec-loops forever).
             const installedBinary = findInPath(agentConfig.cliCommand);
             if (installedBinary) {
-                importInstallScriptBinary({ agentId: agent, npmPackage: agentConfig.npmPackage, cliCommand: agentConfig.cliCommand }, installedVersion, installedBinary, versionDir);
+                importInstallScriptBinary({ agentId: agent, npmPackage: agentConfig.npmPackage, cliCommand: agentConfig.cliCommand }, installationLabel, installedBinary, versionDir);
             }
             /* If null: binary missing from PATH (install script failed silently) or
                only our shim is present. Leave the version dir empty so getBinaryPath
                correctly reports it uninstalled. */
         }
-        createVersionedAlias(agent, installedVersion);
+        createVersionedAlias(agent, installationLabel);
         // Freeze this installation's identity. The dir name is its stable label from
         // here on; the release it carries is recorded separately so `agents update`
         // can move the release without invalidating any reference to the label.
-        createInstallation(agent, installedVersion, installedVersion);
-        const trackerInstall = await installSessionTrackerHook(agent, installedVersion);
+        createInstallation(agent, installationLabel, releaseVersion);
+        const trackerInstall = await installSessionTrackerHook(agent, installationLabel);
         if (!trackerInstall.installed && trackerInstall.error) {
-            console.warn(`agents: SessionStart hook not installed for ${agent}@${installedVersion}: ${trackerInstall.error}`);
+            console.warn(`agents: SessionStart hook not installed for ${agent}@${installationLabel}: ${trackerInstall.error}`);
         }
         // The self-updating binary just changed on disk — drop the cached
         // `--version` so `agents view` reflects the freshly-installed release.
         invalidateLiveVersionCache(agent);
-        emit('version.install', { agent, version: installedVersion });
-        return { success: true, installedVersion };
+        emit('version.install', { agent, version: installationLabel });
+        return { success: true, installedVersion: installationLabel };
     }
     // Resolve the `latest`/`oldest` aliases to a concrete npm version up front so
     // the rest of the install path treats them as an ordinary pinned install.
@@ -2185,8 +2199,13 @@ function resourceSourceMap(kind, cwd, available) {
         }
         case 'mcp':
             return new Map(getScopedMcpResources(cwd).map(r => [r.name, r.scope]));
-        case 'plugins':
-            return new Map(available.plugins.map(n => [n, 'user']));
+        case 'plugins': {
+            const sources = sourceMapFromPlugins(cwd);
+            return new Map(available.plugins.flatMap((n) => {
+                const source = sources.get(n);
+                return source ? [[n, source]] : [];
+            }));
+        }
         case 'workflows': {
             const sources = sourceMapFromWorkflows(cwd);
             return new Map(available.workflows.flatMap((n) => {
@@ -2359,6 +2378,12 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             console.warn(`agents: SessionStart hook not installed for ${agent}@${version}: ${trackerResult.error}`);
         }
     }
+    if (agent === 'claude') {
+        const statusLine = installClaudeStatusLine(versionHome);
+        if (statusLine.error) {
+            console.warn(`agents: Claude status line not installed for ${agent}@${version}: ${statusLine.error}`);
+        }
+    }
     // Fast guard BEFORE getAvailableResources / pattern expansion /
     // ensureVersionResourcePatterns. Guard needs only loadManifest + isStale
     // (~6 ms); the work that used to sit ahead of it was ~12.5 ms of the 21.5 ms

package/dist/lib/linear-autoclose.d.ts

@@ -7,7 +7,7 @@
  * routine YAML's `command:` shell script so the routine stays self-contained
  * and independent of the CLI build.
  *
- * @see apps/cli/routines/linear-autoclose.yml
+ * @see cli/routines/linear-autoclose.yml
  */
 /**
  * Subset of `gh pr view --json state,mergedAt` output that drives the

package/dist/lib/linear-autoclose.js

@@ -7,7 +7,7 @@
  * routine YAML's `command:` shell script so the routine stays self-contained
  * and independent of the CLI build.
  *
- * @see apps/cli/routines/linear-autoclose.yml
+ * @see cli/routines/linear-autoclose.yml
  */
 /**
  * Pure decision: returns true when the PR has been merged and its linked

package/dist/lib/loop.d.ts

@@ -6,7 +6,7 @@
  * can spawn subagents freely). Every guard — `max_iterations`, `budget`, the
  * `until: signal` condition, SIGINT/SIGTERM — lives OUTSIDE the agent, so the
  * agent cannot vote past a kill-switch (the standard answer to runaway-loop and
- * runaway-cost failure modes; see docs/entrypoints-and-loops.md).
+ * runaway-cost failure modes; see docs/execution.md).
  *
  * Structure mirrors the teams supervisor (`runSupervisor` in teams/supervisor.ts):
  * a bounded for-loop with a hard cap, a SIGINT/SIGTERM trap that flips a stop
@@ -21,7 +21,7 @@
 import type { AgentId } from './types.js';
 import type { ExecOptions } from './exec.js';
 import { type Checkpoint } from './checkpoint.js';
-/** Loop block config (docs/entrypoints-and-loops.md → "The loop block"). */
+/** Loop block config; see docs/execution.md. */
 export interface LoopConfig {
     /** Stop condition. `signal` reads loop-signal.json; absence is fail-closed. */
     until?: 'signal';

package/dist/lib/loop.js

@@ -6,7 +6,7 @@
  * can spawn subagents freely). Every guard — `max_iterations`, `budget`, the
  * `until: signal` condition, SIGINT/SIGTERM — lives OUTSIDE the agent, so the
  * agent cannot vote past a kill-switch (the standard answer to runaway-loop and
- * runaway-cost failure modes; see docs/entrypoints-and-loops.md).
+ * runaway-cost failure modes; see docs/execution.md).
  *
  * Structure mirrors the teams supervisor (`runSupervisor` in teams/supervisor.ts):
  * a bounded for-loop with a hard cap, a SIGINT/SIGTERM trap that flips a stop

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

@@ -0,0 +1,47 @@
+/**
+ * On-demand download + verification of the macOS menu-bar helper
+ * ("MenubarHelper.app").
+ *
+ * Mirrors the ComputerHelper download model (`../computer/download.ts`): the
+ * helper ships as a signed + notarized `.app` zipped as a GitHub release asset
+ * on the helper's own `menubar/v<x.y.z>` tag, NOT the CLI's tag (see
+ * `helper-versions.ts`). A fresh `npm i -g` machine whose tarball lacks a
+ * bundled copy fetches the asset for the pinned helper version, verifies its
+ * sha256 + code signature before install.
+ *
+ * The one difference — and the reason this is not the ComputerHelper spec — is
+ * the DESIGNATED-REQUIREMENT pin. macOS keys the menu bar's Accessibility (TCC)
+ * grant to the bundle's designated requirement (bundle id
+ * `com.phnx-labs.agents-menubar` + Developer ID Team `2HTP252L87`), and
+ * re-validates each new version against it. A downloaded bundle whose DR drops
+ * either pin would silently revoke the user's grant, so `MENUBAR_HELPER_SPEC`
+ * sets `expectedBundleId` and the shared `verifyHelperApp` enforces the DR
+ * before the bundle is ever installed. This matches the release-time gate in
+ * `scripts/verify-menubar-helper.sh`.
+ */
+import { type HelperSpec } from '../helper-download.js';
+/** The zipped `.app` release asset name. */
+export declare const MENUBAR_HELPER_ASSET = "MenubarHelper.app.zip";
+/** The bundle directory name once extracted. */
+export declare const MENUBAR_HELPER_APP_NAME = "MenubarHelper.app";
+/** The bundle id the Accessibility grant (and thus the designated requirement)
+ *  is keyed to — the same value `install-menubar.ts`'s `SERVICE_LABEL_BASE` and
+ *  `scripts/verify-menubar-helper.sh` pin. */
+export declare const MENUBAR_HELPER_BUNDLE_ID = "com.phnx-labs.agents-menubar";
+/** MenubarHelper identity + verification policy — DR-pinned (see docblock). */
+export declare const MENUBAR_HELPER_SPEC: HelperSpec;
+/** Release-asset URLs for the menu-bar helper zip + its checksum at `v<version>`. */
+export declare function menubarHelperAssetUrls(version: string): {
+    zip: string;
+    sha256: string;
+};
+/** Cache dir for the downloaded menu-bar helper, one subdir per release tag. */
+export declare function menubarHelperCacheDir(version: string): string;
+/** Verify a menu-bar helper `.app`: codesign + Team + DR pin + notarization. */
+export declare function verifyMenubarHelper(appPath: string): void;
+/**
+ * Download the menu-bar helper release asset for `version`, verify sha256 +
+ * signature + DR pin, and return the path to the extracted `MenubarHelper.app`
+ * in the cache. A missing asset is a hard error naming the exact tag.
+ */
+export declare function downloadMenubarHelperApp(version: string): Promise<string>;

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

@@ -0,0 +1,60 @@
+/**
+ * On-demand download + verification of the macOS menu-bar helper
+ * ("MenubarHelper.app").
+ *
+ * Mirrors the ComputerHelper download model (`../computer/download.ts`): the
+ * helper ships as a signed + notarized `.app` zipped as a GitHub release asset
+ * on the helper's own `menubar/v<x.y.z>` tag, NOT the CLI's tag (see
+ * `helper-versions.ts`). A fresh `npm i -g` machine whose tarball lacks a
+ * bundled copy fetches the asset for the pinned helper version, verifies its
+ * sha256 + code signature before install.
+ *
+ * The one difference — and the reason this is not the ComputerHelper spec — is
+ * the DESIGNATED-REQUIREMENT pin. macOS keys the menu bar's Accessibility (TCC)
+ * grant to the bundle's designated requirement (bundle id
+ * `com.phnx-labs.agents-menubar` + Developer ID Team `2HTP252L87`), and
+ * re-validates each new version against it. A downloaded bundle whose DR drops
+ * either pin would silently revoke the user's grant, so `MENUBAR_HELPER_SPEC`
+ * sets `expectedBundleId` and the shared `verifyHelperApp` enforces the DR
+ * before the bundle is ever installed. This matches the release-time gate in
+ * `scripts/verify-menubar-helper.sh`.
+ */
+import { EXPECTED_TEAM_ID, downloadHelperApp, helperAssetUrls, helperCacheDir, verifyHelperApp, } from '../helper-download.js';
+/** The zipped `.app` release asset name. */
+export const MENUBAR_HELPER_ASSET = 'MenubarHelper.app.zip';
+/** The bundle directory name once extracted. */
+export const MENUBAR_HELPER_APP_NAME = 'MenubarHelper.app';
+/** The bundle id the Accessibility grant (and thus the designated requirement)
+ *  is keyed to — the same value `install-menubar.ts`'s `SERVICE_LABEL_BASE` and
+ *  `scripts/verify-menubar-helper.sh` pin. */
+export const MENUBAR_HELPER_BUNDLE_ID = 'com.phnx-labs.agents-menubar';
+/** MenubarHelper identity + verification policy — DR-pinned (see docblock). */
+export const MENUBAR_HELPER_SPEC = {
+    helper: 'menubar',
+    assetName: MENUBAR_HELPER_ASSET,
+    appName: MENUBAR_HELPER_APP_NAME,
+    cacheSubdir: ['menubar', 'mac-helper'],
+    expectedTeamId: EXPECTED_TEAM_ID,
+    expectedBundleId: MENUBAR_HELPER_BUNDLE_ID,
+    localBuildHint: 'menubar/scripts/build.sh release, then cp -R menubar/dist/MenubarHelper.app bin/MenubarHelper.app',
+};
+/** Release-asset URLs for the menu-bar helper zip + its checksum at `v<version>`. */
+export function menubarHelperAssetUrls(version) {
+    return helperAssetUrls(MENUBAR_HELPER_SPEC, version);
+}
+/** Cache dir for the downloaded menu-bar helper, one subdir per release tag. */
+export function menubarHelperCacheDir(version) {
+    return helperCacheDir(MENUBAR_HELPER_SPEC, version);
+}
+/** Verify a menu-bar helper `.app`: codesign + Team + DR pin + notarization. */
+export function verifyMenubarHelper(appPath) {
+    verifyHelperApp(appPath, MENUBAR_HELPER_SPEC);
+}
+/**
+ * Download the menu-bar helper release asset for `version`, verify sha256 +
+ * signature + DR pin, and return the path to the extracted `MenubarHelper.app`
+ * in the cache. A missing asset is a hard error naming the exact tag.
+ */
+export function downloadMenubarHelperApp(version) {
+    return downloadHelperApp(MENUBAR_HELPER_SPEC, version);
+}

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

@@ -14,6 +14,20 @@
  * migration (`installMenubarLaunchAgent` in migrate.ts) honors, so a disabled
  * menu bar never silently comes back on the next release.
  */
+/**
+ * The bundled executable's basename (RUSH-3101) — what launchd execs directly
+ * inside `Contents/MacOS/`, bypassing LaunchServices name resolution. Before
+ * this it was `MenubarHelper`, so that raw Mach-O basename is exactly what
+ * macOS showed in System Settings > Privacy & Security > Accessibility and in
+ * the "would like to control this computer" prompt. Renaming this constant
+ * alone does NOT touch the bundle id, Team ID, or designated requirement
+ * (`SERVICE_LABEL_BASE`, `MENUBAR_HELPER_BUNDLE_ID` in download-menubar.ts) —
+ * those are what keep the existing Accessibility grant alive across upgrades.
+ * Every basename-matching check reads this constant rather than re-deriving
+ * the string; the Swift side has its own equal in
+ * `menubar/Sources/MenubarHelper/HelperIdentity.swift`.
+ */
+export declare const MENUBAR_HELPER_EXECUTABLE_NAME = "AGI Menu";
 /**
  * launchd Label for this process's helper — the production identifier for a
  * real invocation, namespaced under a redirected HOME (RUSH-2639). launchd
@@ -22,9 +36,9 @@
  */
 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
- * notifications through this one-shot (`MenubarHelper --notify ...`) so they
+ * Absolute path to the installed menu-bar helper executable if it exists on
+ * disk, else null. The desktop notifier (notify-desktop.ts) routes daemon
+ * notifications through this one-shot (`"AGI Menu" --notify ...`) so they
  * carry the agents-cli mark rather than the generic osascript icon. Null on
  * non-darwin or when the helper is not installed (menu bar disabled, a Linux
  * package, or a dev checkout without a built bundle).
@@ -61,6 +75,7 @@ export declare function hasDeveloperIdSignature(appPath: string): boolean;
  */
 export declare function ensureMenubarAppInstalled(opts?: {
     forceReinstall?: boolean;
+    sourceAppPath?: string;
 }): string | null;
 export declare function generateServicePlist(execPath: string): string;
 /**
@@ -106,11 +121,20 @@ export declare function restartMenubarHelperAfterSwap(uid: number, ownProcesses:
  * Install + start the menu-bar helper as a launchd user service (idempotent).
  * Clears the sticky opt-out, installs the .app, writes the plist, and
  * bootstraps it into the GUI domain. Returns false on non-darwin or when no
- * helper bundle ships with this install.
+ * helper bundle can be resolved for this install.
+ *
+ * ASYNC and download-capable: this is the EXPLICIT user-initiated path
+ * (`agents menubar enable`). When no bundled/local `.app` ships (a fresh
+ * `npm i -g` machine whose tarball lacks the bundle), it fetches the signed +
+ * notarized release asset for the running CLI version — verified (sha256 +
+ * codesign + Team + designated-requirement pin + notarization) before install
+ * — and starts the service from that cached copy. The startup self-heal never
+ * routes here: it calls `startMenubarServiceFromSource` and stays sync +
+ * network-free, no-opping when no local source exists.
  */
 export declare function enableMenubarService(opts?: {
     clearOptOut?: boolean;
-}): boolean;
+}): Promise<boolean>;
 /**
  * Pure staleness decision (no I/O) so the truth table is unit-testable. The
  * installed service is stale when the helper binary is gone, or when it was
@@ -296,7 +320,7 @@ export declare function processesToEnd(status: Pick<MenubarStatus, 'instances' |
  *   4. login item  — write the plist (RunAtLoad + KeepAlive) and bootstrap it
  *   5. single      — verify exactly one helper came back up
  */
-export declare function runMenubarSetup(): SetupResult;
+export declare function runMenubarSetup(): Promise<SetupResult>;
 /** A live MenubarHelper process: its pid and the executable it is running. */
 export interface MenubarProcess {
     pid: number;
@@ -320,7 +344,7 @@ export interface MenubarProcess {
  *
  * Identity comes from `comm` (the resolved executable), never from a substring
  * of the command line: matching the latter flags any shell that merely mentions
- * MenubarHelper. `command` is consulted only to drop `--notify` one-shots.
+ * the helper's name. `command` is consulted only to drop `--notify` one-shots.
  */
 export declare function classifyMenubarProcesses(commOutput: string, commandOutput: string, installedExec: string): {
     own: MenubarProcess[];