@phnx-labs/agents-cli 1.22.101 → 1.22.103

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,8 +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 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));
@@ -198,6 +221,30 @@ function sourceAppPath() {
     }
     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 {
@@ -503,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. */
@@ -553,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() {
@@ -640,6 +691,41 @@ function menubarSetupStale() {
         execExists: fs.existsSync(installedExecutablePath()),
     });
 }
+/**
+ * Pure decision (no I/O): should the detached background worker download the
+ * floor release into the cache so the next startup self-heal has a source?
+ *
+ * The self-heal (`installMenubarLaunchAgentOnUpgrade`) is deliberately
+ * network-free, and the npm tarball ships no bundle, so without this step an
+ * `npm i -g` Mac keeps whatever helper it has — a crashing 1.1.2, a dead 0.1.0 —
+ * until someone runs `agents menubar setup` by hand. The worker fetches only
+ * when the fetch would change something: nothing else can act as a source, the
+ * user has not opted out, and either no service exists yet (the auto-enable the
+ * bootstrap promises) or the installed helper is older than the floor.
+ */
+export function menubarHelperPrefetchNeeded(opts) {
+    if (!opts.darwin || opts.disabledByUser || opts.hasSource)
+        return false;
+    return !opts.serviceInstalled || opts.stale;
+}
+/**
+ * Background half of the release-path self-heal: download + verify the floor
+ * release into the cache when `menubarHelperPrefetchNeeded` says so. Returns
+ * the cached path, or null when nothing was fetched. Run from the detached
+ * auto-pull worker; the foreground CLI never waits on it.
+ */
+export async function prefetchMenubarHelper() {
+    const needed = menubarHelperPrefetchNeeded({
+        darwin: onDarwin(),
+        disabledByUser: menubarDisabledByUser(),
+        hasSource: Boolean(sourceAppPath()),
+        serviceInstalled: menubarServiceInstalled(),
+        stale: menubarSetupStale(),
+    });
+    if (!needed)
+        return null;
+    return downloadMenubarHelperApp(await menubarVersionToInstall());
+}
 /**
  * Pure decision (no I/O): did THIS heal actually replace bundle content a live
  * process could be running stale, as opposed to a plist-only repoint?
@@ -1037,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}`);
@@ -1305,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 = {}) {