@phnx-labs/agents-cli 1.22.102 → 1.22.103

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.22.103
+
+- **`agents run claude` no longer dies with `secrets request failed: spawnSync sh ETIMEDOUT` on a loaded machine (PHNX-4078).** Every synchronous secrets request spawns a fresh `secrets __serve` process, so its bound has to cover a cold Node boot of the standalone, not just the tens-of-milliseconds operation. The bound was 3 s; on a desktop at load average ~100 each spawn measured 0.4–2.6 s and sometimes more, so the account listing on the launch path timed out and the run aborted before Claude started (also why AGI EXT tabs opened to a bare shell there). The sync bound is now 30 s — enough to boot under load, still well under the standalone's own 60 s self-deadline — and a timeout names the cause ("the standalone secrets CLI did not answer within 30s … check with secrets --version") instead of the raw `spawnSync` errno. Source: `cli/src/lib/secrets-client.ts`, `cli/src/lib/secrets-client.test.ts`, `cli/docs/secrets-client.md`.
+
 ## 1.22.102
 
 - **AGI Menu updates itself on npm-installed Macs (PHNX-4036).** The npm tarball ships no helper bundle, and the startup self-heal is network-free by design, so an `npm i -g` Mac kept whatever helper it had — the crashing 1.1.2, a dead 0.1.0 — until someone ran `agents menubar setup` by hand. The detached background sync now downloads and verifies the floor release into the helper cache whenever the installed helper is behind it (or no service exists yet and the user has not opted out), and the self-heal treats that cached bundle as a source, so the next `agents` invocation installs it with no foreground network. `agents menubar status` names the pending download instead of "missing (cannot enable)". Source: `cli/src/lib/menubar/install-menubar.ts`, `cli/src/lib/auto-pull-worker.ts`.

package/dist/bootstrap.js

@@ -385,6 +385,21 @@ async function installResolvedPackage(metadata) {
     // The macOS Keychain helper this used to force-refresh on upgrade moved with
     // the standalone `secrets` engine (PHNX-3989) — it downloads and verifies its
     // own helper release now, off this CLI's upgrade path entirely.
+    //
+    // The menu-bar helper still rides this path: an installed release build moves
+    // to the newest published one (verified download, atomic swap at the same
+    // path and identity so the Accessibility grant survives, restart). The new
+    // package is on disk, so the import resolves the fresh module. Best-effort;
+    // the daemon's self-heal tick repeats it every six hours.
+    if (process.platform === 'darwin') {
+        try {
+            const { updateMenubarHelperIfNewer } = await import('./lib/menubar/install-menubar.js');
+            await updateMenubarHelperIfNewer({ force: true });
+        }
+        catch {
+            // Non-fatal.
+        }
+    }
 }
 /** Present an interactive upgrade prompt (TTY) or a one-line hint (non-TTY). */
 async function promptUpgrade(latestVersion) {

package/dist/lib/helper-versions.js

@@ -36,7 +36,7 @@
  * helper release now, off this table entirely.
  */
 export const HELPER_RELEASES = {
-    menubar: { tagPrefix: 'menubar', floor: '1.2.3' },
+    menubar: { tagPrefix: 'menubar', floor: '1.3.0' },
     'computer-mac': { tagPrefix: 'computer-mac', floor: '1.0.0' },
     // The Windows helper is a bare .exe, not an .app bundle, so it does not share
     // helper-download.ts's zip/codesign/notarize machinery -- but it has the same

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

@@ -70,6 +70,20 @@ export declare function menubarDisabledByUser(): boolean;
 export declare function menubarServiceInstalled(): boolean;
 /** Where a downloaded copy of the floor release sits once fetched and verified. */
 export declare function cachedFloorBundlePath(): string;
+/**
+ * Where the downloaded copy of the RESOLVED release sits (`cachedMenubarVersion`,
+ * so the floor's cache dir until this machine has resolved something newer).
+ * The startup self-heal installs from here, network-free.
+ */
+export declare function cachedReleaseBundlePath(): string;
+/**
+ * The release version an explicit install should fetch: the newest published
+ * build, but never below what this Mac already runs — a release deleted after
+ * it was installed must not roll the helper back through `setup`/`enable`.
+ */
+export declare function menubarVersionToInstall(opts?: {
+    force?: boolean;
+}): Promise<string>;
 /** True when the bundle carries a signature the kernel will accept at launch. */
 export declare function codesignVerifies(appPath: string): boolean;
 /**
@@ -511,3 +525,45 @@ export declare function isMenubarProcessStaleAgainstBundle(pidStartedAtMs: numbe
  * remains the command that fixes what this reports.
  */
 export declare function buildMenubarDoctorReport(): MenubarDoctorReport;
+/** Outcome of one auto-update pass (`updateMenubarHelperIfNewer`). */
+export interface MenubarUpdateResult {
+    outcome: 'updated' | 'current' | 'skipped' | 'failed';
+    installed: string | null;
+    available: string;
+    detail: string;
+}
+/**
+ * Bring an installed release helper up to the newest published build, without
+ * a human running `agents menubar setup`.
+ *
+ * Runs from the daemon's self-heal tick and right after `agents upgrade`. It
+ * only ever moves a RELEASE install forward: a machine whose helper came from a
+ * local build (a dev checkout) keeps it, a machine that never enabled the menu
+ * bar or opted out is left alone, and the ownership contest that bounds
+ * multi-install churn (`mayInstallMenubarHelper`) still applies. The bundle is
+ * downloaded and verified by the same path every install uses (sha256,
+ * codesign, Team, designated-requirement pin, notarization), swapped
+ * atomically under the install lock at the same path and identity — which is
+ * what keeps the Accessibility grant — and the running helper is restarted
+ * from the new binary (`restartMenubarHelperAfterSwap`; launchd's KeepAlive
+ * relaunches it within seconds). `dryRun` reports what would happen. Never
+ * throws.
+ */
+/**
+ * Pure (no I/O): whether an auto-update pass should proceed, and why not.
+ * `shipped` is a bundle that ships WITH this install (never a downloaded
+ * release cache) — CLI upgrades own that one. Returns null to proceed.
+ */
+export declare function menubarUpdateSkipReason(opts: {
+    darwin: boolean;
+    disabledByUser: boolean;
+    serviceInstalled: boolean;
+    shipped: boolean;
+    installed: MenubarStamp | null;
+}): string | null;
+/** Pure (no I/O): what the pass does given the installed and available versions. */
+export declare function menubarUpdateOutcome(installed: string, available: string): 'current' | 'updated';
+export declare function updateMenubarHelperIfNewer(opts?: {
+    dryRun?: boolean;
+    force?: boolean;
+}): Promise<MenubarUpdateResult>;

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

@@ -27,6 +27,7 @@ import { compareVersions } from '../agent-spec/primitives.js';
 import { namespacedServiceLabel, serviceManifestHomeEnv, serviceManagerRegistrationAllowed } from '../service-manifest.js';
 import { downloadMenubarHelperApp, menubarHelperCacheDir } from './download-menubar.js';
 import { helperFloor } from '../helper-versions.js';
+import { cachedMenubarVersion, resolveMenubarVersion } from './resolve-version.js';
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 const SERVICE_LABEL_BASE = 'com.phnx-labs.agents-menubar';
@@ -171,15 +172,30 @@ export function menubarServiceInstalled() {
  *      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
  *      `agents` launcher symlink.
- *   4. the verified download cache for the FLOOR release — the npm tarball ships
- *      no bundle (PHNX-4036), so on an `npm i -g` machine this is the only
- *      source there is. It is filled by `agents menubar setup` or by the
- *      detached background worker (`prefetchMenubarHelper`), never here: this
- *      resolver stays network-free so the startup self-heal stays cheap. Last
- *      so a bundle that ships with the build always wins; keyed by the floor
- *      version so an older cached release is never picked up.
+ *   4. the verified download cache for the RELEASE this machine has resolved
+ *      (`cachedMenubarVersion`: the newest published build it last saw, never
+ *      below the floor, the floor itself before any resolution) — the npm
+ *      tarball ships no bundle (PHNX-4036), so on an `npm i -g` machine this is
+ *      the only source there is. It is filled by `agents menubar setup` or by
+ *      the detached background worker (`prefetchMenubarHelper`), never here:
+ *      this resolver stays network-free so the startup self-heal stays cheap.
+ *      Last so a bundle that ships with the build always wins; keyed by the
+ *      resolved version so an older cached release is never picked up.
+ *
+ * `shippedAppPath` is candidates 1–3 alone: a bundle that ships WITH this
+ * install, which CLI upgrades own. The auto-update pass replaces a cached
+ * release (candidate 4) but never a shipped bundle.
  */
 function sourceAppPath() {
+    const shipped = shippedAppPath();
+    if (shipped)
+        return shipped;
+    const cached = cachedReleaseBundlePath();
+    if (fs.existsSync(cached))
+        return cached;
+    return null;
+}
+function shippedAppPath() {
     const candidates = [];
     try {
         const here = path.dirname(fileURLToPath(import.meta.url));
@@ -203,15 +219,32 @@ function sourceAppPath() {
         if (fs.existsSync(p))
             return p;
     }
-    const cached = cachedFloorBundlePath();
-    if (fs.existsSync(cached))
-        return cached;
     return null;
 }
 /** Where a downloaded copy of the floor release sits once fetched and verified. */
 export function cachedFloorBundlePath() {
     return path.join(menubarHelperCacheDir(helperFloor('menubar')), APP_BUNDLE_NAME);
 }
+/**
+ * Where the downloaded copy of the RESOLVED release sits (`cachedMenubarVersion`,
+ * so the floor's cache dir until this machine has resolved something newer).
+ * The startup self-heal installs from here, network-free.
+ */
+export function cachedReleaseBundlePath() {
+    return path.join(menubarHelperCacheDir(cachedMenubarVersion()), APP_BUNDLE_NAME);
+}
+/**
+ * The release version an explicit install should fetch: the newest published
+ * build, but never below what this Mac already runs — a release deleted after
+ * it was installed must not roll the helper back through `setup`/`enable`.
+ */
+export async function menubarVersionToInstall(opts = {}) {
+    const resolved = await resolveMenubarVersion({ force: opts.force });
+    const installed = readInstalledMenubarStamp();
+    if (installed?.source === 'release' && compareVersions(installed.helperVersion, resolved) > 0)
+        return installed.helperVersion;
+    return resolved;
+}
 /** Resolve the compiled CLI entry (dist/index.js) so the helper can exec node directly. */
 function resolveCliEntry() {
     try {
@@ -517,9 +550,11 @@ function startMenubarServiceFromSource(opts = {}) {
 export async function enableMenubarService(opts = { clearOptOut: true }) {
     if (!onDarwin())
         return false;
-    let src = sourceAppPath();
+    // A shipped bundle wins; otherwise fetch the newest published build (a cache
+    // hit when the background prefetch already has it), never below what runs.
+    let src = shippedAppPath();
     if (!src)
-        src = await downloadMenubarHelperApp(helperFloor('menubar'));
+        src = await downloadMenubarHelperApp(await menubarVersionToInstall());
     return startMenubarServiceFromSource({ ...opts, sourceAppPath: src });
 }
 /** Drop the sticky `agents menubar disable` sentinel. */
@@ -567,8 +602,10 @@ export function stampVersionLabel(stamp) {
 function availableStamp() {
     const src = sourceAppPath();
     // No local bundle means the release path: what would be installed is the
-    // helper version the floor names.
-    return src ? stampFor(src) : { source: 'release', helperVersion: helperFloor('menubar') };
+    // newest published helper this machine has resolved (cached, day-old at
+    // most), never below the floor — and the floor itself before the first
+    // resolution or offline.
+    return src ? stampFor(src) : { source: 'release', helperVersion: cachedMenubarVersion() };
 }
 /** The helper version this install would put on disk right now, for display. */
 function availableHelperLabel() {
@@ -687,7 +724,7 @@ export async function prefetchMenubarHelper() {
     });
     if (!needed)
         return null;
-    return downloadMenubarHelperApp(helperFloor('menubar'));
+    return downloadMenubarHelperApp(await menubarVersionToInstall());
 }
 /**
  * Pure decision (no I/O): did THIS heal actually replace bundle content a live
@@ -1086,10 +1123,10 @@ export async function runMenubarSetup() {
     // 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();
+    let src = shippedAppPath();
     if (!src) {
         try {
-            src = await downloadMenubarHelperApp(helperFloor('menubar'));
+            src = await downloadMenubarHelperApp(await menubarVersionToInstall({ force: true }));
         }
         catch (e) {
             step('bundle', 'failed', `no AGI Menu bundle ships with this install, and the release-asset download failed: ${e.message}`);
@@ -1354,3 +1391,82 @@ export function buildMenubarDoctorReport() {
         accessibilityHintNeeded: signingIdentity === 'ad-hoc' || staleRunningProcess.some((p) => p.stale),
     };
 }
+/**
+ * Bring an installed release helper up to the newest published build, without
+ * a human running `agents menubar setup`.
+ *
+ * Runs from the daemon's self-heal tick and right after `agents upgrade`. It
+ * only ever moves a RELEASE install forward: a machine whose helper came from a
+ * local build (a dev checkout) keeps it, a machine that never enabled the menu
+ * bar or opted out is left alone, and the ownership contest that bounds
+ * multi-install churn (`mayInstallMenubarHelper`) still applies. The bundle is
+ * downloaded and verified by the same path every install uses (sha256,
+ * codesign, Team, designated-requirement pin, notarization), swapped
+ * atomically under the install lock at the same path and identity — which is
+ * what keeps the Accessibility grant — and the running helper is restarted
+ * from the new binary (`restartMenubarHelperAfterSwap`; launchd's KeepAlive
+ * relaunches it within seconds). `dryRun` reports what would happen. Never
+ * throws.
+ */
+/**
+ * Pure (no I/O): whether an auto-update pass should proceed, and why not.
+ * `shipped` is a bundle that ships WITH this install (never a downloaded
+ * release cache) — CLI upgrades own that one. Returns null to proceed.
+ */
+export function menubarUpdateSkipReason(opts) {
+    if (!opts.darwin)
+        return 'macOS only';
+    if (opts.disabledByUser)
+        return 'the menu bar is disabled (agents menubar disable)';
+    if (!opts.serviceInstalled)
+        return 'the menu bar is not installed on this Mac';
+    if (opts.shipped)
+        return 'this install ships its own helper bundle; the startup self-heal owns it';
+    if (!opts.installed || opts.installed.source !== 'release') {
+        return `installed helper is ${stampVersionLabel(opts.installed) ?? 'unstamped'}, not a release`;
+    }
+    return null;
+}
+/** Pure (no I/O): what the pass does given the installed and available versions. */
+export function menubarUpdateOutcome(installed, available) {
+    return compareVersions(available, installed) > 0 ? 'updated' : 'current';
+}
+export async function updateMenubarHelperIfNewer(opts = {}) {
+    const installedStamp = readInstalledMenubarStamp();
+    const installed = stampVersionLabel(installedStamp);
+    const skip = (detail, available = cachedMenubarVersion()) => ({ outcome: 'skipped', installed, available, detail });
+    const reason = menubarUpdateSkipReason({
+        darwin: onDarwin(),
+        disabledByUser: menubarDisabledByUser(),
+        serviceInstalled: menubarServiceInstalled(),
+        shipped: Boolean(shippedAppPath()),
+        installed: installedStamp,
+    });
+    if (reason)
+        return skip(reason);
+    const release = installedStamp;
+    const available = await resolveMenubarVersion({ force: opts.force });
+    if (menubarUpdateOutcome(release.helperVersion, available) === 'current') {
+        return { outcome: 'current', installed, available, detail: `AGI Menu ${installed} is the newest published build` };
+    }
+    if (!mayHealMenubar(false))
+        return skip(`another install owns the helper; it will update on its own cooldown`, available);
+    if (opts.dryRun)
+        return { outcome: 'updated', installed, available, detail: `would update AGI Menu ${installed} → ${available}` };
+    try {
+        const src = await downloadMenubarHelperApp(available);
+        const exec = ensureMenubarAppInstalled({ forceReinstall: true, sourceAppPath: src });
+        if (!exec)
+            return { outcome: 'failed', installed, available, detail: 'the verified bundle could not be installed' };
+        try {
+            fs.writeFileSync(installedVersionMarkerPath(), JSON.stringify(stampFor(src)));
+        }
+        catch { /* best effort */ }
+        stampMenubarHeal();
+        restartMenubarHelperAfterSwap(process.getuid?.() ?? 0, liveMenubarProcesses().own);
+        return { outcome: 'updated', installed, available, detail: `AGI Menu ${installed} → ${available}` };
+    }
+    catch (e) {
+        return { outcome: 'failed', installed, available, detail: e.message };
+    }
+}

package/dist/lib/menubar/resolve-version.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Which menu-bar helper build to install: the newest published release at or
+ * above this CLI's floor.
+ *
+ * `helper-versions.ts` records a FLOOR (the build this CLI was tested against)
+ * and promised that resolution "may pick a NEWER build; it must never pick an
+ * older one". Until now nothing resolved upward: every install path downloaded
+ * the floor, so a helper fix reached a machine only after a CLI release bumped
+ * the floor and the user ran `agents menubar setup`. This module is the
+ * missing half — discovery — and it is what makes the helper auto-update.
+ *
+ * Discovery reads the public release list of `phnx-labs/agi-cli` and keeps
+ * only tags shaped `menubar/v<x.y.z>` that carry the helper asset AND its
+ * sha256 sidecar (a half-uploaded release is not a candidate). The answer is
+ * cached for a day under the CLI's cache dir so the sync startup path and the
+ * daemon read a file, never the network; the floor stays the offline answer
+ * whenever the network or the cache cannot do better. The verified download
+ * (`downloadMenubarHelperApp`: sha256, codesign, Team, designated-requirement
+ * pin, notarization) is unchanged — resolution only chooses the version.
+ */
+/** The repo whose releases carry `menubar/v*` tags (same as the download URL). */
+export declare const MENUBAR_RELEASES_API = "https://api.github.com/repos/phnx-labs/agi-cli/releases?per_page=100";
+/** How long a resolved answer is trusted before the release list is re-read. */
+export declare const MENUBAR_RESOLVE_TTL_MS: number;
+/** One release as the resolver sees it — the subset of the GitHub shape it reads. */
+export interface ReleaseCandidate {
+    tagName: string;
+    assets: string[];
+    draft?: boolean;
+    prerelease?: boolean;
+}
+export interface MenubarResolveCache {
+    /** Epoch ms of the release-list read this answer came from. */
+    checkedAt: number;
+    /** The newest published helper version at that time (never below the floor then). */
+    version: string;
+}
+/**
+ * Pure: the newest candidate at or above `floor`, else the floor. A tag must be
+ * exactly `menubar/v<x.y.z>` (no pre-release suffix), not a draft or
+ * pre-release, and carry both the zip and its `.sha256`.
+ */
+export declare function pickNewestMenubarVersion(candidates: ReleaseCandidate[], floor: string): string;
+/** Where the resolved answer lives: beside the helper's own download cache. */
+export declare function menubarResolveCachePath(): string;
+export declare function readMenubarResolveCache(file: string): MenubarResolveCache | null;
+/**
+ * The cached answer when it is usable offline: at or above the floor, of any
+ * age. Sync and network-free — this is what the startup self-heal and the
+ * status/doctor displays read.
+ */
+export declare function cachedMenubarVersion(opts?: {
+    floor?: string;
+    cacheFile?: string;
+}): string;
+type FetchLike = (input: string, init?: {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+/** Read the release list. Unauthenticated: release metadata is public and this runs at most once a day per machine. */
+export declare function fetchMenubarReleaseCandidates(fetchImpl?: FetchLike): Promise<ReleaseCandidate[]>;
+/**
+ * The helper version to install now: the newest published build >= floor.
+ *
+ * Reads the day-old cache first; re-reads the release list when the cache is
+ * missing, stale, or `force` is set; falls back to the cached answer, then the
+ * floor, when the network cannot answer. Never throws, never returns a version
+ * below the floor.
+ */
+export declare function resolveMenubarVersion(opts?: {
+    floor?: string;
+    cacheFile?: string;
+    now?: number;
+    ttlMs?: number;
+    force?: boolean;
+    fetchImpl?: FetchLike;
+}): Promise<string>;
+export {};

package/dist/lib/menubar/resolve-version.js

@@ -0,0 +1,133 @@
+/**
+ * Which menu-bar helper build to install: the newest published release at or
+ * above this CLI's floor.
+ *
+ * `helper-versions.ts` records a FLOOR (the build this CLI was tested against)
+ * and promised that resolution "may pick a NEWER build; it must never pick an
+ * older one". Until now nothing resolved upward: every install path downloaded
+ * the floor, so a helper fix reached a machine only after a CLI release bumped
+ * the floor and the user ran `agents menubar setup`. This module is the
+ * missing half — discovery — and it is what makes the helper auto-update.
+ *
+ * Discovery reads the public release list of `phnx-labs/agi-cli` and keeps
+ * only tags shaped `menubar/v<x.y.z>` that carry the helper asset AND its
+ * sha256 sidecar (a half-uploaded release is not a candidate). The answer is
+ * cached for a day under the CLI's cache dir so the sync startup path and the
+ * daemon read a file, never the network; the floor stays the offline answer
+ * whenever the network or the cache cannot do better. The verified download
+ * (`downloadMenubarHelperApp`: sha256, codesign, Team, designated-requirement
+ * pin, notarization) is unchanged — resolution only chooses the version.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getCacheDir } from '../state.js';
+import { compareVersions } from '../agent-spec/primitives.js';
+import { helperFloor } from '../helper-versions.js';
+import { getCliVersion } from '../version.js';
+import { MENUBAR_HELPER_ASSET } from './download-menubar.js';
+/** The repo whose releases carry `menubar/v*` tags (same as the download URL). */
+export const MENUBAR_RELEASES_API = 'https://api.github.com/repos/phnx-labs/agi-cli/releases?per_page=100';
+/** How long a resolved answer is trusted before the release list is re-read. */
+export const MENUBAR_RESOLVE_TTL_MS = 24 * 60 * 60 * 1000;
+const TAG = /^menubar\/v(\d+\.\d+\.\d+)$/;
+/**
+ * Pure: the newest candidate at or above `floor`, else the floor. A tag must be
+ * exactly `menubar/v<x.y.z>` (no pre-release suffix), not a draft or
+ * pre-release, and carry both the zip and its `.sha256`.
+ */
+export function pickNewestMenubarVersion(candidates, floor) {
+    let best = floor;
+    for (const c of candidates) {
+        if (c.draft || c.prerelease)
+            continue;
+        const m = TAG.exec(c.tagName);
+        if (!m)
+            continue;
+        if (!c.assets.includes(MENUBAR_HELPER_ASSET) || !c.assets.includes(`${MENUBAR_HELPER_ASSET}.sha256`))
+            continue;
+        if (compareVersions(m[1], best) > 0)
+            best = m[1];
+    }
+    return best;
+}
+/** Where the resolved answer lives: beside the helper's own download cache. */
+export function menubarResolveCachePath() {
+    return path.join(getCacheDir(), 'menubar', 'latest.json');
+}
+export function readMenubarResolveCache(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (typeof parsed.checkedAt === 'number' && typeof parsed.version === 'string' && /^\d+\.\d+\.\d+$/.test(parsed.version)) {
+            return { checkedAt: parsed.checkedAt, version: parsed.version };
+        }
+    }
+    catch { /* absent or unreadable: no cache */ }
+    return null;
+}
+function writeMenubarResolveCache(file, cache) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(cache));
+        fs.renameSync(tmp, file);
+    }
+    catch { /* a cache that cannot be written is just a cache miss next time */ }
+}
+/**
+ * The cached answer when it is usable offline: at or above the floor, of any
+ * age. Sync and network-free — this is what the startup self-heal and the
+ * status/doctor displays read.
+ */
+export function cachedMenubarVersion(opts = {}) {
+    const floor = opts.floor ?? helperFloor('menubar');
+    const cache = readMenubarResolveCache(opts.cacheFile ?? menubarResolveCachePath());
+    return cache && compareVersions(cache.version, floor) >= 0 ? cache.version : floor;
+}
+/** Read the release list. Unauthenticated: release metadata is public and this runs at most once a day per machine. */
+export async function fetchMenubarReleaseCandidates(fetchImpl = fetch) {
+    const res = await fetchImpl(MENUBAR_RELEASES_API, {
+        headers: {
+            Accept: 'application/vnd.github+json',
+            'X-GitHub-Api-Version': '2022-11-28',
+            'User-Agent': `agents-cli/${getCliVersion()}`,
+        },
+        signal: AbortSignal.timeout(5_000),
+    });
+    if (!res.ok)
+        throw new Error(`release list: HTTP ${res.status}`);
+    const body = (await res.json());
+    if (!Array.isArray(body))
+        throw new Error('release list: not an array');
+    return body.map((r) => ({
+        tagName: r.tag_name ?? '',
+        draft: r.draft,
+        prerelease: r.prerelease,
+        assets: (r.assets ?? []).map((a) => a.name ?? ''),
+    }));
+}
+/**
+ * The helper version to install now: the newest published build >= floor.
+ *
+ * Reads the day-old cache first; re-reads the release list when the cache is
+ * missing, stale, or `force` is set; falls back to the cached answer, then the
+ * floor, when the network cannot answer. Never throws, never returns a version
+ * below the floor.
+ */
+export async function resolveMenubarVersion(opts = {}) {
+    const floor = opts.floor ?? helperFloor('menubar');
+    const file = opts.cacheFile ?? menubarResolveCachePath();
+    const now = opts.now ?? Date.now();
+    const ttl = opts.ttlMs ?? MENUBAR_RESOLVE_TTL_MS;
+    const cached = readMenubarResolveCache(file);
+    if (cached && !opts.force && now - cached.checkedAt < ttl && compareVersions(cached.version, floor) >= 0) {
+        return cached.version;
+    }
+    try {
+        const version = pickNewestMenubarVersion(await fetchMenubarReleaseCandidates(opts.fetchImpl), floor);
+        writeMenubarResolveCache(file, { checkedAt: now, version });
+        return version;
+    }
+    catch {
+        return cached && compareVersions(cached.version, floor) >= 0 ? cached.version : floor;
+    }
+}

package/dist/lib/profiles.js

@@ -11,7 +11,7 @@ import * as crypto from 'node:crypto';
 import * as yaml from 'yaml';
 import { ALL_AGENT_IDS } from './agents.js';
 import { getUserAgentsDir } from './state.js';
-import { deleteKeychainTokenSync, getKeychainTokenSync, hasKeychainTokenSync, isSecretsClientError, profileKeychainItem } from './secrets-client.js';
+import { deleteKeychainTokenSync, getKeychainTokenSync, hasKeychainTokenSync, isSecretsClientError, isSecretsTransportError, profileKeychainItem, } from './secrets-client.js';
 import { getPreset } from './profiles-presets.js';
 import { MODEL_TIERS, isTierToken } from './model-tiers.js';
 import { addAccount, findAccount, resolveCredentialAccount } from './account-registry.js';
@@ -250,7 +250,18 @@ export function profileAuthLabel(profile) {
         return `${provider} ${maskToken(token)}`;
     }
     if (profile.auth) {
-        return `${provider} ${hasKeychainTokenSync(profile.auth.keychainItem) ? 'stored' : 'missing'}`;
+        // A status row, like the provider-account rows: a wedged or missing
+        // standalone degrades this one label instead of aborting the whole render.
+        let stored;
+        try {
+            stored = hasKeychainTokenSync(profile.auth.keychainItem);
+        }
+        catch (err) {
+            if (isSecretsTransportError(err))
+                return `${provider} unavailable`;
+            throw err;
+        }
+        return `${provider} ${stored ? 'stored' : 'missing'}`;
     }
     return provider;
 }

package/dist/lib/secrets-client.d.ts

@@ -5,6 +5,24 @@ import type { SecretsBundle, SecretsBackend, ResolveBundleOptions, WriteBundleOp
  * independent client legitimately re-declares rather than imports.
  */
 export declare const PROTOCOL_VERSION = 1;
+/**
+ * The synchronous path serves the surfaces that resolve secrets before they can
+ * continue — `agents view`, the account-catalog rows, and the account listing and
+ * setup-token read on the `agents run` launch path. Those must never hang for the
+ * standalone's own 60s deadline (the exact hang PHNX-3989 hit when the child ran
+ * under Bun), so the sync serve carries a hard bound below it instead of the
+ * async path's 65s. The bound covers a COLD PROCESS, not just the operation: every
+ * request spawns `secrets __serve` afresh, so it pays a Node boot plus the
+ * standalone's module load before the tens-of-milliseconds op runs: ~0.3s on a
+ * quiet box, 0.4–2.6s and occasionally more on a desktop at load average ~100
+ * (measured 2026-09-12), where the previous 3s bound turned load into a failed
+ * launch (`secrets request failed: spawnSync sh ETIMEDOUT` from `agents run`).
+ * 30s absorbs that boot under load and still fails a broken or wedged standalone
+ * well before its 60s self-deadline. It is NOT a fallback to the embedded engine
+ * (DIST-1); the standalone stays the only implementation. Exported so the
+ * real-standalone test can assert a round-trip beats the bound.
+ */
+export declare const SYNC_SERVE_TIMEOUT_MS = 30000;
 export interface SecretsContext {
     /** Bundle allowlist; absent ⇒ full trust (the local agents client today). */
     allowedBundles?: string[];
@@ -111,6 +129,8 @@ export declare function secretsRequest<T = unknown>(op: string, args?: unknown[]
 export declare function secretsRequestSync<T = unknown>(op: string, args?: unknown[], context?: SecretsContext): T;
 /** Test hook: forget the cached binary + handshake so a new env is re-resolved. */
 export declare function _resetSecretsClientForTest(): void;
+/** Shorten the sync bound for a test that plants a hanging standalone; reset restores it. */
+export declare function _setSyncServeTimeoutForTest(ms: number): void;
 export declare function readAndResolveBundleEnv(name: string, opts?: ResolveBundleOptions, context?: SecretsContext): Promise<{
     bundle: SecretsBundle;
     env: Record<string, string>;

package/dist/lib/secrets-client.js

@@ -25,9 +25,10 @@
  *     is load-bearing: the standalone wraps fd 3 in a `net.Socket`, and a Socket
  *     over a NAMED FIFO reads the request but never fires EOF on macOS, so the
  *     older FIFO wiring hung the read loop for the full timeout. Bounded to
- *     `SYNC_SERVE_TIMEOUT_MS` so a broken standalone fails fast, never for the
- *     server's 60s deadline. POSIX only; Windows fails loud pointing at the
- *     async path.
+ *     `SYNC_SERVE_TIMEOUT_MS` (30s — sized for a cold Node boot of the
+ *     standalone on a loaded box, see the constant) so a broken standalone
+ *     fails before the server's 60s deadline. POSIX only; Windows fails loud
+ *     pointing at the async path.
  *
  * State root (MIG-1): the standalone selects its state root from `SECRETS_HOME`.
  * agents-cli points it at the user agents dir (`~/.agents`) by default so the
@@ -59,20 +60,25 @@ const MAX_PROTOCOL_BYTES = 8 * 1024 * 1024;
 /** Just over the server's own 60s deadline, so the server times out first. */
 const SERVE_TIMEOUT_MS = 65_000;
 /**
- * The synchronous path only serves read-only STATUS surfaces — `agents view`,
- * the account-catalog rows, and run-config / account-rotation resolution on the
- * `agents run` hot path. Those must never hang the whole render or launch on a
- * missing or unreachable standalone, so the sync serve carries a short, hard
- * bound instead of the async path's 65s: a broken `secrets` fails loud in a few
- * seconds and the caller renders the rest of its output (or launches on the
- * native login) with one clear line, rather than sitting for the standalone's
- * own 60s deadline (the exact 60s hang PHNX-3989 hit when the child ran under
- * Bun). A real sync op (a handshake, a bundle list, one item read) completes in
- * tens of milliseconds, so this is ~100x headroom. It is NOT a fallback to the
- * embedded engine (DIST-1); the standalone stays the only implementation, it
- * just fails fast.
+ * The synchronous path serves the surfaces that resolve secrets before they can
+ * continue — `agents view`, the account-catalog rows, and the account listing and
+ * setup-token read on the `agents run` launch path. Those must never hang for the
+ * standalone's own 60s deadline (the exact hang PHNX-3989 hit when the child ran
+ * under Bun), so the sync serve carries a hard bound below it instead of the
+ * async path's 65s. The bound covers a COLD PROCESS, not just the operation: every
+ * request spawns `secrets __serve` afresh, so it pays a Node boot plus the
+ * standalone's module load before the tens-of-milliseconds op runs: ~0.3s on a
+ * quiet box, 0.4–2.6s and occasionally more on a desktop at load average ~100
+ * (measured 2026-09-12), where the previous 3s bound turned load into a failed
+ * launch (`secrets request failed: spawnSync sh ETIMEDOUT` from `agents run`).
+ * 30s absorbs that boot under load and still fails a broken or wedged standalone
+ * well before its 60s self-deadline. It is NOT a fallback to the embedded engine
+ * (DIST-1); the standalone stays the only implementation. Exported so the
+ * real-standalone test can assert a round-trip beats the bound.
  */
-const SYNC_SERVE_TIMEOUT_MS = 3_000;
+export const SYNC_SERVE_TIMEOUT_MS = 30_000;
+/** Test seam: a hang test plants a never-answering standalone and must not wait 30s. */
+let syncServeTimeoutMs = SYNC_SERVE_TIMEOUT_MS;
 /** Serialize `Map`s the way the server's `decodeWire` expects to receive them. */
 export function encodeWire(value) {
     if (value instanceof Map) {
@@ -413,13 +419,25 @@ function serveOnceSync(op, args, context) {
         input: request,
         stdio: ['pipe', 'pipe', 'inherit'],
         env: buildServeEnv(),
-        timeout: SYNC_SERVE_TIMEOUT_MS,
+        timeout: syncServeTimeoutMs,
         maxBuffer: MAX_PROTOCOL_BYTES + 4096,
     });
     if (result.error) {
         const err = result.error;
-        const code = err.code === 'ETIMEDOUT' ? 'TIMEOUT' : 'SPAWN_FAILED';
-        throw new SecretsClientError(code, `secrets request failed: ${err.message}`);
+        if (err.code === 'ETIMEDOUT') {
+            throw new SecretsClientError('TIMEOUT', `the standalone \`secrets\` CLI did not answer within ${Math.round(syncServeTimeoutMs / 1000)}s ` +
+                `(${[command, ...prefix, '__serve'].join(' ')}). The machine may be too loaded to boot it in time, or the install is broken: ` +
+                'check with `secrets --version`.');
+        }
+        // A standalone that exits before draining fd 3 leaves `spawnSync`'s stdin
+        // write with EPIPE, yet its exit status and everything it wrote to fd 4 are
+        // still returned. Like the async path (`input.on('error', () => {})`), the
+        // outcome is whatever reached fd 4 — an empty or non-JSON answer is the
+        // diagnostic, not the errno. Seen on the GitHub-hosted runner, where a
+        // planted `exit 0` standalone exits faster than the request is written.
+        if (err.code !== 'EPIPE') {
+            throw new SecretsClientError('SPAWN_FAILED', `secrets request failed: ${err.message}`);
+        }
     }
     const raw = result.stdout ?? Buffer.alloc(0);
     if (raw.length > MAX_PROTOCOL_BYTES) {
@@ -483,6 +501,11 @@ export function _resetSecretsClientForTest() {
     handshakeReady = false;
     handshakePromise = null;
     requestCounter = 0;
+    syncServeTimeoutMs = SYNC_SERVE_TIMEOUT_MS;
+}
+/** Shorten the sync bound for a test that plants a hanging standalone; reset restores it. */
+export function _setSyncServeTimeoutForTest(ms) {
+    syncServeTimeoutMs = ms;
 }
 // --- typed wrappers -------------------------------------------------------
 //

package/dist/lib/self-heal/checks/menubar-helper.d.ts

@@ -0,0 +1,2 @@
+import type { HealCheck } from '../types.js';
+export declare const menubarHelperCheck: HealCheck;

package/dist/lib/self-heal/checks/menubar-helper.js

@@ -0,0 +1,21 @@
+// menubar-helper check — keeps the installed AGI Menu on the newest published
+// build. Discovery + trigger for the helper's auto-update: the daemon runs this
+// on the periodic cadence; the same call runs right after `agents upgrade`.
+// Detect-only under dryRun (what `agents doctor` shows); the repair is the
+// verified download + atomic swap + restart in `updateMenubarHelperIfNewer`.
+import { resultOf } from '../types.js';
+export const menubarHelperCheck = {
+    id: 'menubar-helper',
+    title: 'AGI Menu helper is the newest published build',
+    platforms: ['darwin'],
+    cadence: 'periodic',
+    async run(ctx) {
+        const { updateMenubarHelperIfNewer } = await import('../../menubar/install-menubar.js');
+        const r = await updateMenubarHelperIfNewer({ dryRun: ctx.dryRun });
+        switch (r.outcome) {
+            case 'updated': return resultOf([r.detail], []);
+            case 'failed': return resultOf([], [`AGI Menu ${r.installed ?? '?'} → ${r.available}: ${r.detail}`]);
+            default: return resultOf([], []);
+        }
+    },
+};

package/dist/lib/self-heal/registry.js

@@ -11,6 +11,7 @@ import { shimsCheck } from './checks/shims.js';
 import { shadowingCheck } from './checks/shadowing.js';
 import { pathCheck } from './checks/path.js';
 import { installStagingCheck } from './checks/install-staging.js';
+import { menubarHelperCheck } from './checks/menubar-helper.js';
 // Order matters: cheap structural fixes (shims, shadow adoption, PATH, generated
 // hook wrappers) before the heavier resource reconciliation, so a freshly-
 // repaired shim is in place first.
@@ -24,6 +25,8 @@ export const HEAL_CHECKS = [
     hookManifestCheck,
     resourcesCheck,
     installStagingCheck,
+    // Last and network-touching: the menu-bar helper's auto-update (macOS only).
+    menubarHelperCheck,
 ];
 /** Run the selected checks, isolating per-check failures. */
 export async function runSelfHeal(opts = {}) {

package/dist/lib/self-heal/types.d.ts

@@ -1,4 +1,4 @@
-export type HealCheckId = 'resources' | 'hook-runtime' | 'hook-manifest' | 'shims' | 'shadowing' | 'path' | 'install-staging';
+export type HealCheckId = 'resources' | 'hook-runtime' | 'hook-manifest' | 'shims' | 'shadowing' | 'path' | 'install-staging' | 'menubar-helper';
 /** When the daemon schedules a check. */
 export type HealCadence = 'startup' | 'frequent' | 'periodic';
 export interface HealCtx {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.102",
+  "version": "1.22.103",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",