@phnx-labs/agents-cli 1.22.47 → 1.22.50

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

package/dist/lib/secrets/download-keychain.js

@@ -0,0 +1,70 @@
+/**
+ * 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 { EXPECTED_TEAM_ID, downloadHelperApp, helperAssetUrls, helperCacheDir, verifyHelperApp, } from '../helper-download.js';
+/** The zipped `.app` release asset name (the bundle name has a space). */
+// Underscore, and NOT a space. GitHub rewrites a space in a release-asset name
+// to a dot on upload, so an asset staged as `Agents CLI.app.zip` is SERVED as
+// `Agents.CLI.app.zip` and a client asking for the spaced name 404s forever --
+// which is exactly what shipped. The fix is to CHOOSE a name GitHub leaves
+// alone rather than to mirror its rewrite: `Agents.CLI.app.zip` would work by
+// matching an artifact of that behavior, and would silently break if the
+// normalization rule ever changed. Underscores are preserved verbatim (verified
+// against a real upload).
+//
+// The bundle DIRECTORY inside the zip keeps its space (`appName` below) -- that
+// is the on-disk bundle name macOS and the TCC grant key on, and it is unchanged.
+export const KEYCHAIN_HELPER_ASSET = 'Agents_CLI.app.zip';
+/** The bundle directory name once extracted. */
+export const KEYCHAIN_HELPER_APP_NAME = 'Agents CLI.app';
+/** Keychain-helper identity + verification policy — Team + notarization only,
+ *  no DR pin (see docblock). */
+export const KEYCHAIN_HELPER_SPEC = {
+    helper: 'keychain',
+    assetName: KEYCHAIN_HELPER_ASSET,
+    appName: KEYCHAIN_HELPER_APP_NAME,
+    cacheSubdir: ['secrets', 'mac-helper'],
+    expectedTeamId: EXPECTED_TEAM_ID,
+    localBuildHint: 'cli/scripts/build-keychain-helper.sh',
+};
+/** Release-asset URLs for the keychain helper zip + its checksum at `v<version>`. */
+export function keychainHelperAssetUrls(version) {
+    return helperAssetUrls(KEYCHAIN_HELPER_SPEC, version);
+}
+/** Cache dir for the downloaded keychain helper, one subdir per release tag. */
+export function keychainHelperCacheDir(version) {
+    return helperCacheDir(KEYCHAIN_HELPER_SPEC, version);
+}
+/** Verify a keychain helper `.app`: codesign + Team + notarization (no DR pin). */
+export function verifyKeychainHelper(appPath) {
+    verifyHelperApp(appPath, KEYCHAIN_HELPER_SPEC);
+}
+/**
+ * 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 function downloadKeychainHelperApp(version) {
+    return downloadHelperApp(KEYCHAIN_HELPER_SPEC, version);
+}

package/dist/lib/secrets/install-helper.d.ts

@@ -29,6 +29,20 @@ export declare function setInstallRootForTest(dir: string | null): string | null
 export declare function ensureKeychainHelperInstalled(opts?: {
     forceReinstall?: boolean;
 }): void;
+/**
+ * ASYNC, download-capable install — the EXPLICIT onboarding/upgrade path
+ * (`agents setup secrets`, the bootstrap upgrade self-heal). When a bundled or
+ * locally-built `.app` ships (the common case, and always true this release
+ * stage), it installs that copy with NO network. When the tarball lacks the
+ * bundle (a fresh `npm i -g` whose tarball dropped it), it fetches the signed +
+ * notarized release asset for the running CLI version — sha256 + codesign +
+ * Team + notarization verified before install — and installs from the cached
+ * copy. The sync `getKeychainHelperPath()` never routes here: it stays sync +
+ * network-free and fails loud toward this command when no source exists.
+ */
+export declare function ensureKeychainHelperInstalledAsync(opts?: {
+    forceReinstall?: boolean;
+}): Promise<void>;
 /**
  * Return the absolute path to the helper executable. If the installed bundle
  * is missing, or is stale relative to the bundled source helper, performs a
@@ -37,7 +51,12 @@ export declare function ensureKeychainHelperInstalled(opts?: {
  * `npm i -g`, so this call site is the only one every machine is guaranteed to
  * pass through.
  *
- * Throws on non-darwin.
+ * SYNC and network-free by design: this is the secrets hot path, called by
+ * every keychain op. It never downloads. When no bundled/local source exists
+ * (a tarball that dropped the bundle), the reinstall's `sourceAppPath()` throws
+ * loud, directing the user to `agents setup secrets` — the explicit, async,
+ * download-capable path (`ensureKeychainHelperInstalledAsync`). Throws on
+ * non-darwin.
  */
 export declare function getKeychainHelperPath(): string;
 /** Diagnostic snapshot of the installed Keychain helper. */

package/dist/lib/secrets/install-helper.js

@@ -19,6 +19,8 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { copyAppBundle, withInstallLock } from '../app-bundle-install.js';
+import { downloadKeychainHelperApp } from './download-keychain.js';
+import { helperFloor } from '../helper-versions.js';
 const APP_BUNDLE_NAME = 'Agents CLI.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 let installRootOverride = null;
@@ -60,7 +62,18 @@ function sourceAppPath() {
             return c;
     }
     throw new Error(`Source ${APP_BUNDLE_NAME} not found. Looked in:\n  ${candidates.join('\n  ')}\n` +
-        'The npm package may have been built without the signed helper bundle. Reinstall agents-cli.');
+        'The npm package shipped without the bundled keychain helper. Run `agents setup secrets` to ' +
+        'download the signed helper for this version, or reinstall agents-cli.');
+}
+/** The bundled/local source `.app`, or null when absent (no throw) — the async
+ *  download path resolves the missing bundle instead of failing. */
+function bundledSourceAppPathOrNull() {
+    try {
+        return sourceAppPath();
+    }
+    catch {
+        return null;
+    }
 }
 function assertDarwin() {
     if (process.platform !== 'darwin') {
@@ -122,6 +135,30 @@ function spctlAssess(appPath) {
  */
 export function ensureKeychainHelperInstalled(opts = {}) {
     assertDarwin();
+    installKeychainHelperFromSource(sourceAppPath(), opts);
+}
+/**
+ * ASYNC, download-capable install — the EXPLICIT onboarding/upgrade path
+ * (`agents setup secrets`, the bootstrap upgrade self-heal). When a bundled or
+ * locally-built `.app` ships (the common case, and always true this release
+ * stage), it installs that copy with NO network. When the tarball lacks the
+ * bundle (a fresh `npm i -g` whose tarball dropped it), it fetches the signed +
+ * notarized release asset for the running CLI version — sha256 + codesign +
+ * Team + notarization verified before install — and installs from the cached
+ * copy. The sync `getKeychainHelperPath()` never routes here: it stays sync +
+ * network-free and fails loud toward this command when no source exists.
+ */
+export async function ensureKeychainHelperInstalledAsync(opts = {}) {
+    assertDarwin();
+    const bundled = bundledSourceAppPathOrNull();
+    const src = bundled ?? (await downloadKeychainHelperApp(helperFloor('keychain')));
+    installKeychainHelperFromSource(src, opts);
+}
+/**
+ * Copy `src` (a verified `.app` bundle) to the stable user path, then verify.
+ * Shared by the sync (bundled-source) and async (download-capable) installers.
+ */
+function installKeychainHelperFromSource(src, opts = {}) {
     const dest = installedAppPath();
     const upToDate = () => fs.existsSync(dest) && codesignVerify(dest).ok && !installedHelperIsStale();
     // Fast path: already installed, valid, and current — no lock, no copy.
@@ -134,7 +171,6 @@ export function ensureKeychainHelperInstalled(opts = {}) {
     withInstallLock(dest, (heartbeat) => {
         if (!opts.forceReinstall && upToDate())
             return;
-        const src = sourceAppPath();
         copyAppBundle(src, dest);
         heartbeat(); // cp -R done; keep the lock fresh across the codesign/spctl spawns
         const verify = codesignVerify(dest);
@@ -160,7 +196,12 @@ export function ensureKeychainHelperInstalled(opts = {}) {
  * `npm i -g`, so this call site is the only one every machine is guaranteed to
  * pass through.
  *
- * Throws on non-darwin.
+ * SYNC and network-free by design: this is the secrets hot path, called by
+ * every keychain op. It never downloads. When no bundled/local source exists
+ * (a tarball that dropped the bundle), the reinstall's `sourceAppPath()` throws
+ * loud, directing the user to `agents setup secrets` — the explicit, async,
+ * download-capable path (`ensureKeychainHelperInstalledAsync`). Throws on
+ * non-darwin.
  */
 export function getKeychainHelperPath() {
     assertDarwin();

package/dist/lib/session/active.js

@@ -2068,10 +2068,26 @@ export function foldHostLink(rows) {
         // disproves. A stored record never yields `attached` (it is background or
         // parked), so clearing only that value drops the derived lie and leaves a
         // real detach record untouched.
-        if (link !== 'connected' && s.presence === 'attached')
+        // Only a POSITIVE loss signal disproves a derived `attached`. `unknown` means
+        // we never looked — a bare terminal with no IDE window and no tmux has
+        // neither input — so it must not clear presence, or every plain-terminal
+        // session the user is sitting in would lose its `attached` marker.
+        if ((link === 'no-client' || link === 'host-gone') && s.presence === 'attached') {
             s.presence = undefined;
+        }
         if (link === 'host-gone' && s.status === 'closed')
             s.status = 'crashed';
+        // Only idle/input_required are promoted — a `running` session keeps its
+        // status (SES-18a). Extending this to a running agent with no client was
+        // tried and reverted: since RUSH-3125 wraps every remote interactive run in
+        // a detached tmux pane, "running with zero attached clients" is the NORMAL
+        // steady state between check-ins, and that path writes no detach record, so
+        // `deliberatelyDetached` is false for it. Promoting it would relabel every
+        // remote agent as orphaned whenever nobody is looking — the over-reporting
+        // this file's header calls worthless. Telling a stranded agent from a
+        // healthy unattended one needs to know a client was EXPECTED and LOST, which
+        // no signal available here carries; that belongs with the peer-side pane
+        // ownership work, not this function.
         else if (link === 'no-client' && (s.status === 'idle' || s.status === 'input_required')) {
             s.status = 'orphaned';
         }