@phnx-labs/agents-cli 1.22.47 → 1.22.49

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[];

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 {
@@ -714,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
@@ -735,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
@@ -839,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 });
@@ -849,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
@@ -868,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() };
@@ -946,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.

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.

package/dist/lib/project-probe.d.ts

@@ -58,7 +58,7 @@ export declare function probeProjectWorkspaces(paths: string[]): RepoWorkspaceSt
  */
 export declare function workspaceTargetsForDef(def: ProjectDef): string[];
 /**
- * Parse a peer's `projects probe --json` stdout, tagging each row with the
+ * Parse a peer's `projects probe` stdout, tagging each row with the
  * machine that answered. Defensive against version skew / partial output, the
  * same boundary contract as `parseRemoteActive`: non-JSON or a non-array
  * yields `[]`, and rows without a `path`/`present` core are dropped.

package/dist/lib/project-probe.js

@@ -96,7 +96,7 @@ export function workspaceTargetsForDef(def) {
     return projectProbeTargets(def);
 }
 /**
- * Parse a peer's `projects probe --json` stdout, tagging each row with the
+ * Parse a peer's `projects probe` stdout, tagging each row with the
  * machine that answered. Defensive against version skew / partial output, the
  * same boundary contract as `parseRemoteActive`: non-JSON or a non-array
  * yields `[]`, and rows without a `path`/`present` core are dropped.

package/dist/lib/project-pull.d.ts

@@ -93,7 +93,7 @@ export declare function decodePullTargets(raw: string): ProjectRepoTarget[];
 export declare function pullProjectTargets(targets: ProjectRepoTarget[], host?: string): Promise<ProjectPullResult[]>;
 export declare function buildPullEnvelope(results: ProjectPullResult[], targets: ProjectRepoTarget[]): ProjectPullEnvelope;
 /**
- * Parse a peer's `projects pull-local --json` stdout. Fails CLOSED **and
+ * Parse a peer's `projects pull-local` stdout. Fails CLOSED **and
  * LOUD**: any structural anomaly (wrong schema version, wrong kind, machine
  * mismatch, fingerprint mismatch, non-array results, malformed rows) returns
  * `{ items: [], valid: false }` rather than silently accepting a partial or

package/dist/lib/project-pull.js

@@ -66,7 +66,7 @@ export function encodePullTargets(targets) {
  * test can exercise the real caller-side arguments rather than a retyped copy.
  */
 export function pullLocalArgs(targets) {
-    return ['projects', 'pull-local', '--json', '--targets', encodePullTargets(targets)];
+    return ['projects', 'pull-local', '--targets', encodePullTargets(targets)];
 }
 /**
  * Decode the `--targets` argument back into targets on the peer. THROWS on any
@@ -226,7 +226,7 @@ export function buildPullEnvelope(results, targets) {
 // Envelope parser (fail-closed — every validation failure returns [])
 // ---------------------------------------------------------------------------
 /**
- * Parse a peer's `projects pull-local --json` stdout. Fails CLOSED **and
+ * Parse a peer's `projects pull-local` stdout. Fails CLOSED **and
  * LOUD**: any structural anomaly (wrong schema version, wrong kind, machine
  * mismatch, fingerprint mismatch, non-array results, malformed rows) returns
  * `{ items: [], valid: false }` rather than silently accepting a partial or

package/dist/lib/projects.d.ts

@@ -204,7 +204,7 @@ export declare function projectDirsAbs(def: ProjectDef, opts: {
  * with `expandLocalHome` and resolved, so this matches sessions whose cwd shares
  * this machine's home layout. A session recorded on a different-home machine
  * (`/Users/x/…` vs `/home/x/…`) will not match until the fleet-wide,
- * home-relative variant lands (see the deferred item in docs/projects.md).
+ * home-relative variant lands (see docs/concepts.md).
  */
 export declare function projectNameForCwd(cwd: string | undefined, defs: ProjectDef[]): string | undefined;
 /**

package/dist/lib/projects.js

@@ -429,7 +429,7 @@ function isUnder(child, parent) {
  * with `expandLocalHome` and resolved, so this matches sessions whose cwd shares
  * this machine's home layout. A session recorded on a different-home machine
  * (`/Users/x/…` vs `/home/x/…`) will not match until the fleet-wide,
- * home-relative variant lands (see the deferred item in docs/projects.md).
+ * home-relative variant lands (see docs/concepts.md).
  */
 export function projectNameForCwd(cwd, defs) {
     if (!cwd)

package/dist/lib/sandbox.js

@@ -209,11 +209,11 @@ export function assertSandboxForwardsHostGhAuth(spawnEnv) {
 }
 /** Link this host's Cursor login and CLI config into the disposable overlay. */
 export function generateCursorConfig(overlayHome) {
-    const realConfigHome = process.env.XDG_CONFIG_HOME || path.join(resolveRealHome(), '.config');
-    const realAuth = path.join(realConfigHome, 'cursor', 'auth.json');
+    const realCursorDir = path.join(process.env.AGENTS_REAL_HOME || resolveRealHome(), '.cursor');
+    const realAuth = path.join(realCursorDir, 'auth.json');
     if (!fs.existsSync(realAuth))
         return;
-    const overlayCursorDir = path.join(overlayHome, '.config', 'cursor');
+    const overlayCursorDir = path.join(overlayHome, '.cursor');
     fs.mkdirSync(overlayCursorDir, { recursive: true });
     const overlayAuth = path.join(overlayCursorDir, 'auth.json');
     if (process.platform === 'win32') {
@@ -227,10 +227,9 @@ export function generateCursorConfig(overlayHome) {
     else {
         fs.symlinkSync(realAuth, overlayAuth);
     }
-    // Setting XDG_CONFIG_HOME makes Cursor look for cli-config.json beside auth.json.
-    // This file carries account identity (authId, displayName, email, userId) as
-    // well as preferences, so it must remain linked rather than copied.
-    const realCliConfig = path.join(resolveRealHome(), '.cursor', 'cli-config.json');
+    // cli-config.json carries account identity alongside the file-store token, so
+    // it must remain linked rather than copied.
+    const realCliConfig = path.join(realCursorDir, 'cli-config.json');
     if (fs.existsSync(realCliConfig)) {
         const overlayCliConfig = path.join(overlayCursorDir, 'cli-config.json');
         try {

package/dist/lib/secrets/download-keychain.d.ts

@@ -0,0 +1,47 @@
+/**
+ * On-demand download + verification of the macOS keychain broker helper
+ * ("Agents CLI.app").
+ *
+ * Mirrors the ComputerHelper / MenubarHelper download model
+ * (`../helper-download.ts`): the helper ships as a signed + notarized `.app`
+ * zipped as a GitHub release asset on the helper's own `keychain/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 running
+ * CLI version, verifies its sha256 + code signature before install.
+ *
+ * Unlike the menu-bar helper, the keychain helper pins NO designated
+ * requirement (no `expectedBundleId`). The menu-bar `expectedBundleId` exists
+ * because macOS keys the Accessibility (TCC) grant to the bundle's designated
+ * requirement, so a substituted bundle whose DR does not pin (id, team) would
+ * silently revoke that upgrade-stable grant. The keychain helper has no such
+ * DR-keyed grant to protect: its items are gated by the access-group
+ * entitlement (`keychain-helper.swift` → `kSecAttrAccessGroup`, the
+ * `keychain-access-groups` entitlement) plus a biometry `SecAccessControl`
+ * (user presence) — NOT a `SecTrustedApplication` ACL keyed to a bundle-id/DR.
+ * The release-time gate `scripts/verify-keychain-helper.sh` correspondingly
+ * pins the executable's sha256, not a designated requirement. So Team +
+ * notarization is the verification boundary here, exactly like ComputerHelper.
+ */
+import { type HelperSpec } from '../helper-download.js';
+/** The zipped `.app` release asset name (the bundle name has a space). */
+export declare const KEYCHAIN_HELPER_ASSET = "Agents_CLI.app.zip";
+/** The bundle directory name once extracted. */
+export declare const KEYCHAIN_HELPER_APP_NAME = "Agents CLI.app";
+/** Keychain-helper identity + verification policy — Team + notarization only,
+ *  no DR pin (see docblock). */
+export declare const KEYCHAIN_HELPER_SPEC: HelperSpec;
+/** Release-asset URLs for the keychain helper zip + its checksum at `v<version>`. */
+export declare function keychainHelperAssetUrls(version: string): {
+    zip: string;
+    sha256: string;
+};
+/** Cache dir for the downloaded keychain helper, one subdir per release tag. */
+export declare function keychainHelperCacheDir(version: string): string;
+/** Verify a keychain helper `.app`: codesign + Team + notarization (no DR pin). */
+export declare function verifyKeychainHelper(appPath: string): void;
+/**
+ * Download the keychain helper release asset for `version`, verify sha256 +
+ * signature, and return the path to the extracted `Agents CLI.app` in the
+ * cache. A missing asset is a hard error naming the exact tag.
+ */
+export declare function downloadKeychainHelperApp(version: string): Promise<string>;