@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/installations/versions.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],
@@ -2185,8 +2197,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 +2376,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[];
@@ -370,6 +394,19 @@ export interface PidStaleness {
  * PREVIOUS binary — the exact condition `restartMenubarHelperAfterSwap` exists
  * to fix. Millisecond epoch timestamps in, so the truth table is unit-testable
  * without a live process or filesystem.
+ *
+ * The two timestamps do not have the same resolution. `pidStartTimeMs` parses
+ * `ps -o lstart`, which prints whole SECONDS, while the bundle mtime carries
+ * sub-second precision — and the restart this check exists to detect happens
+ * within a second of the swap that triggered it. A raw `<` therefore called a
+ * healthy just-restarted helper stale on essentially every upgrade: measured on
+ * zion at 1.22.46, pid start 1787441353000 vs bundle mtime 1787441353700, 700ms
+ * apart inside one second, reported as "running the OLD binary" and surfaced as
+ * `accessibilityHintNeeded` — telling the user to re-grant Accessibility after
+ * an upgrade that had already restarted the helper correctly. So the bundle
+ * mtime is truncated to the same whole second `ps` reports before comparing: a
+ * pid that started in the swap's own second is fresh, and a genuinely stale pid
+ * (a full second or more older) is still caught.
  */
 export declare function isMenubarProcessStaleAgainstBundle(pidStartedAtMs: number, bundleMtimeMs: number): boolean;
 /**

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

@@ -25,9 +25,25 @@ import { getCliVersion, resolveAgentsBin, resolveInstalledLayout } from '../vers
 import { copyAppBundle, withInstallLock } from '../app-bundle-install.js';
 import { compareVersions } from '../agent-spec/primitives.js';
 import { namespacedServiceLabel, serviceManifestHomeEnv, serviceManagerRegistrationAllowed } from '../service-manifest.js';
+import { downloadMenubarHelperApp } from './download-menubar.js';
+import { helperFloor } from '../helper-versions.js';
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 const SERVICE_LABEL_BASE = 'com.phnx-labs.agents-menubar';
+/**
+ * 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 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
@@ -83,12 +99,12 @@ function readInstalledMenubarVersion() {
 }
 /** Executable inside the installed bundle. */
 function installedExecutablePath() {
-    return path.join(installedAppPath(), 'Contents', 'MacOS', 'MenubarHelper');
+    return path.join(installedAppPath(), 'Contents', 'MacOS', MENUBAR_HELPER_EXECUTABLE_NAME);
 }
 /**
- * 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).
@@ -119,7 +135,7 @@ export function menubarServiceInstalled() {
  * Locate the source `.app` shipped alongside the compiled JS.
  *   1. dist/lib/menubar/MenubarHelper.app — npm install layout (sibling of this file)
  *   2. <repo>/bin/MenubarHelper.app       — raw working tree (tsx/dev)
- *   3. apps/cli/menubar/dist/MenubarHelper.app — fresh local build
+ *   3. cli/menubar/dist/MenubarHelper.app — fresh local build
  *   4. <on-disk install>/dist/lib/menubar/MenubarHelper.app — Bun single-file
  *      binary: `import.meta.url` is a virtual `/$bunfs/` path, so the sibling
  *      candidates above can't see the on-disk bundle; recover it via the
@@ -229,7 +245,12 @@ export function hasDeveloperIdSignature(appPath) {
 export function ensureMenubarAppInstalled(opts = {}) {
     if (!onDarwin())
         return null;
-    const src = sourceAppPath();
+    // An explicit `sourceAppPath` (a pre-downloaded cache path from the explicit
+    // enable/setup path) overrides local discovery. This function itself does NO
+    // network — the download happens in the async callers before they hand a path
+    // here, so the sync startup self-heal that calls it with no override stays
+    // network-free and simply no-ops when `sourceAppPath()` finds nothing.
+    const src = opts.sourceAppPath ?? sourceAppPath();
     if (!src)
         return null;
     const dest = installedAppPath();
@@ -393,15 +414,18 @@ export function restartMenubarHelperAfterSwap(uid, ownProcesses, exec = execFile
     }
 }
 /**
- * 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.
+ * Sync install + start core: install the given (already-on-disk) source `.app`
+ * and start the launchd service. NO network — the source `.app` must already be
+ * local (a bundled/local copy for the sync startup self-heal, or a pre-downloaded
+ * cache path for the explicit async enable/setup path). Returns false on
+ * non-darwin, when no source resolves, or when the bundle fails the Gatekeeper
+ * check. Shared by the sync self-heal (`installMenubarLaunchAgentOnUpgrade`) and
+ * the async `enableMenubarService`.
  */
-export function enableMenubarService(opts = { clearOptOut: true }) {
+function startMenubarServiceFromSource(opts = {}) {
     if (!onDarwin())
         return false;
-    const exec = ensureMenubarAppInstalled({ forceReinstall: true });
+    const exec = ensureMenubarAppInstalled({ forceReinstall: true, sourceAppPath: opts.sourceAppPath });
     if (!exec)
         return false;
     // Never bootstrap a helper macOS will reject at launch: an invalid signature
@@ -420,6 +444,29 @@ export function enableMenubarService(opts = { clearOptOut: true }) {
     installAndStartService(exec);
     return true;
 }
+/**
+ * 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 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 async function enableMenubarService(opts = { clearOptOut: true }) {
+    if (!onDarwin())
+        return false;
+    let src = sourceAppPath();
+    if (!src)
+        src = await downloadMenubarHelperApp(helperFloor('menubar'));
+    return startMenubarServiceFromSource({ ...opts, sourceAppPath: src });
+}
 /** Drop the sticky `agents menubar disable` sentinel. */
 function clearMenubarOptOut() {
     try {
@@ -602,8 +649,19 @@ export function mayInstallMenubarHelper(opts) {
     // No owner recorded yet (fresh or pre-`AGENTS_ENTRY` plist) — adopt it.
     if (!opts.plistEntry)
         return true;
+    // The recorded owner's entry path is gone from disk, so this install may adopt
+    // the helper — but a non-Developer-ID (ad-hoc/dev) source may NOT seize a
+    // healthy install this way. Recopying an ad-hoc bundle over the Developer-ID
+    // one poisons the shared Accessibility grant (an ad-hoc signature fails the
+    // grant's stored code requirement, so macOS revokes it and re-prompts on the
+    // next paste) and Gatekeeper then rejects the result as "damaged" (RUSH-2134).
+    // This does not strand a genuinely broken helper: escape (1) above
+    // (helperExecMissing / needsDevIdHeal) already lets ANY source repair a
+    // missing-or-ad-hoc install, so refusing here only declines to re-point the
+    // plist of a helper that is already present and working — the menu bar keeps
+    // running, nothing deadlocks.
     if (!opts.ownerEntryExists)
-        return true; // the recorded owner is gone
+        return opts.sourceIsDeveloperId;
     if (opts.installedVersion && opts.currentVersion) {
         const versionOrder = compareVersions(opts.currentVersion, opts.installedVersion);
         if (versionOrder > 0)
@@ -703,7 +761,7 @@ export function installMenubarLaunchAgentOnUpgrade() {
         if (!sourceAppPath())
             return;
         if (!menubarServiceInstalled()) {
-            enableMenubarService({ clearOptOut: false });
+            startMenubarServiceFromSource({ clearOptOut: false });
             return;
         }
         // Re-enable (recopy helper + rewrite plist) when the version drifted OR the
@@ -724,7 +782,7 @@ export function installMenubarLaunchAgentOnUpgrade() {
         // false without installing when the bundle fails the Gatekeeper check, and
         // stamping first would spend the shared cooldown on a no-op — locking every
         // non-owner out for another hour while nothing had been fixed.
-        if (enableMenubarService({ clearOptOut: false })) {
+        if (startMenubarServiceFromSource({ clearOptOut: false })) {
             stampMenubarHeal();
             // One-time: the ad-hoc -> Developer ID transition leaves a dead TCC row
             // under the old identity (tccutil on zion reset it 11 times across
@@ -828,7 +886,7 @@ function endProcess(pid) {
  *   4. login item  — write the plist (RunAtLoad + KeepAlive) and bootstrap it
  *   5. single      — verify exactly one helper came back up
  */
-export function runMenubarSetup() {
+export async function runMenubarSetup() {
     const steps = [];
     const step = (name, outcome, detail) => {
         steps.push({ name, outcome, detail });
@@ -838,9 +896,20 @@ export function runMenubarSetup() {
         return { steps, configured: false, status: getMenubarStatus() };
     }
     const before = getMenubarStatus();
-    if (!sourceAppPath()) {
-        step('bundle', 'failed', 'no AGI Menu bundle ships with this install');
-        return { steps, configured: false, status: before };
+    // Explicit user-initiated path: when no bundled/local `.app` ships (a fresh
+    // `npm i -g` machine whose tarball lacks the bundle), fetch the signed +
+    // notarized release asset for this CLI version. Verified (sha256 + codesign +
+    // Team + designated-requirement pin + notarization) before install; the
+    // cached copy is the source for `ensureMenubarAppInstalled` below.
+    let src = sourceAppPath();
+    if (!src) {
+        try {
+            src = await downloadMenubarHelperApp(helperFloor('menubar'));
+        }
+        catch (e) {
+            step('bundle', 'failed', `no AGI Menu bundle ships with this install, and the release-asset download failed: ${e.message}`);
+            return { steps, configured: false, status: before };
+        }
     }
     // 3 before 1: end the running copies BEFORE swapping the bundle underneath
     // them, so no helper keeps a status item alive on a binary that no longer
@@ -857,7 +926,7 @@ export function runMenubarSetup() {
     else {
         step('duplicates', 'ok', 'no helper was running');
     }
-    const exec = ensureMenubarAppInstalled({ forceReinstall: true });
+    const exec = ensureMenubarAppInstalled({ forceReinstall: true, sourceAppPath: src });
     if (!exec) {
         step('bundle', 'failed', 'could not install the helper bundle');
         return { steps, configured: false, status: getMenubarStatus() };
@@ -935,14 +1004,14 @@ function parsePsLines(psOutput) {
  *
  * 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 function classifyMenubarProcesses(commOutput, commandOutput, installedExec) {
     const commands = parsePsLines(commandOutput);
     const own = [];
     const foreign = [];
     for (const [pid, executable] of parsePsLines(commOutput)) {
-        if (path.basename(executable) !== 'MenubarHelper')
+        if (path.basename(executable) !== MENUBAR_HELPER_EXECUTABLE_NAME)
             continue;
         // `--notify` is a one-shot that posts a notification and exits; it runs the
         // installed binary but never claims the status item or the chords.
@@ -990,9 +1059,22 @@ export function getMenubarStatus() {
  * PREVIOUS binary — the exact condition `restartMenubarHelperAfterSwap` exists
  * to fix. Millisecond epoch timestamps in, so the truth table is unit-testable
  * without a live process or filesystem.
+ *
+ * The two timestamps do not have the same resolution. `pidStartTimeMs` parses
+ * `ps -o lstart`, which prints whole SECONDS, while the bundle mtime carries
+ * sub-second precision — and the restart this check exists to detect happens
+ * within a second of the swap that triggered it. A raw `<` therefore called a
+ * healthy just-restarted helper stale on essentially every upgrade: measured on
+ * zion at 1.22.46, pid start 1787441353000 vs bundle mtime 1787441353700, 700ms
+ * apart inside one second, reported as "running the OLD binary" and surfaced as
+ * `accessibilityHintNeeded` — telling the user to re-grant Accessibility after
+ * an upgrade that had already restarted the helper correctly. So the bundle
+ * mtime is truncated to the same whole second `ps` reports before comparing: a
+ * pid that started in the swap's own second is fresh, and a genuinely stale pid
+ * (a full second or more older) is still caught.
  */
 export function isMenubarProcessStaleAgainstBundle(pidStartedAtMs, bundleMtimeMs) {
-    return pidStartedAtMs < bundleMtimeMs;
+    return pidStartedAtMs < Math.floor(bundleMtimeMs / 1000) * 1000;
 }
 /** Wall-clock start time of a live pid via `ps`, or null if it can't be read. */
 function pidStartTimeMs(pid) {

package/dist/lib/menubar/notify-desktop.d.ts

@@ -3,7 +3,7 @@
  *
  * The one place the daemon (overdue routines, heal, routine start/finish/output)
  * emits a native desktop notification. On macOS it routes through the installed
- * `MenubarHelper.app` companion — a one-shot `MenubarHelper --notify` invocation —
+ * `MenubarHelper.app` companion — a one-shot `"AGI Menu" --notify` invocation —
  * so the notification is attributed to that bundle and carries the agents-cli
  * mark instead of the generic AppleScript icon. A banner carries two images: the
  * agents-cli app icon on the LEFT (the sender) and, when the event belongs to one
@@ -48,7 +48,7 @@ export interface DesktopNotification {
      */
     agent?: string;
 }
-/** Argv for the MenubarHelper one-shot notify mode. Exported for tests. */
+/** Argv for the "AGI Menu" one-shot notify mode. Exported for tests. */
 export declare function buildMenubarNotifyArgs(n: DesktopNotification): string[];
 /** AppleScript for the osascript degradation path. Exported for tests. */
 export declare function buildOsascriptNotifyArgs(n: DesktopNotification): string[];
@@ -67,7 +67,7 @@ export declare function buildOsascriptNotifyArgs(n: DesktopNotification): string
  */
 export declare function spawnDetachedQuiet(command: string, args: string[], timeoutMs?: number): ChildProcess;
 /**
- * Fire a native desktop notification, branded via the MenubarHelper companion on
+ * Fire a native desktop notification, branded via the "AGI Menu" companion on
  * macOS. Best-effort — any failure is swallowed so a notification hiccup never
  * blocks or crashes the daemon.
  */

package/dist/lib/menubar/notify-desktop.js

@@ -3,7 +3,7 @@
  *
  * The one place the daemon (overdue routines, heal, routine start/finish/output)
  * emits a native desktop notification. On macOS it routes through the installed
- * `MenubarHelper.app` companion — a one-shot `MenubarHelper --notify` invocation —
+ * `MenubarHelper.app` companion — a one-shot `"AGI Menu" --notify` invocation —
  * so the notification is attributed to that bundle and carries the agents-cli
  * mark instead of the generic AppleScript icon. A banner carries two images: the
  * agents-cli app icon on the LEFT (the sender) and, when the event belongs to one
@@ -32,7 +32,7 @@ import { resolveInstalledMenubarExecutable } from './install-menubar.js';
  * only if the child never self-exits.
  */
 const NOTIFY_TIMEOUT_MS = 4000;
-/** Argv for the MenubarHelper one-shot notify mode. Exported for tests. */
+/** Argv for the "AGI Menu" one-shot notify mode. Exported for tests. */
 export function buildMenubarNotifyArgs(n) {
     const args = ['--notify', '--title', n.title, '--body', n.body];
     if (n.subtitle)
@@ -88,7 +88,7 @@ export function spawnDetachedQuiet(command, args, timeoutMs = NOTIFY_TIMEOUT_MS)
     return child;
 }
 /**
- * Fire a native desktop notification, branded via the MenubarHelper companion on
+ * Fire a native desktop notification, branded via the "AGI Menu" companion on
  * macOS. Best-effort — any failure is swallowed so a notification hiccup never
  * blocks or crashes the daemon.
  */
@@ -98,9 +98,9 @@ export function notifyDesktop(n) {
         if (platform === 'darwin') {
             const exec = resolveInstalledMenubarExecutable();
             if (exec) {
-                // Branded path: the notification is attributed to MenubarHelper.app, so it
-                // shows the agents-cli mark and its click action is handled by the running
-                // helper's UNUserNotificationCenter delegate.
+                // Branded path: the notification is attributed to MenubarHelper.app
+                // ("AGI Menu" on disk), so it shows the agents-cli mark and its click
+                // action is handled by the running helper's UNUserNotificationCenter delegate.
                 spawnDetachedQuiet(exec, buildMenubarNotifyArgs(n));
                 return;
             }

package/dist/lib/model-tiers.d.ts

@@ -7,7 +7,7 @@
  * actually ships — so `--model cheap|default|best|ultra` works on `agents run`
  * and `agents teams add` alike, funnelling through `resolveModel()`.
  *
- * Ranking signal, in priority (see apps/cli/docs — model ranking mechanisms):
+ * Ranking signal, in priority (see cli/docs — model ranking mechanisms):
  *   1. Provider-declared lineup — the catalog's own family names / descriptions
  *      (opus/sonnet/haiku/fable; Codex "frontier / balanced / fast"). Most
  *      drift-proof: the provider tells us its own ranking.