@phnx-labs/agents-cli 1.22.101 → 1.22.103

package/dist/lib/auth-health.js

@@ -32,14 +32,18 @@ export const LIVE_PROBE_AGENTS = new Set(['claude', 'kimi', 'droid']);
 // ---------------------------------------------------------------------------
 // Pure classifiers / render (unit-tested; no network, no fs)
 // ---------------------------------------------------------------------------
-/** Map an HTTP status from a live probe to a verdict. */
+/** Map an HTTP status from a live probe to a verdict. Probe 429 never yields `rate_limited` (PHNX-4051). */
 export function classifyHttpStatus(status) {
     if (status >= 200 && status < 300)
         return 'live';
     if (status === 401 || status === 403)
         return 'revoked';
+    // 429 is probe throttling, not an account throttle — the account's real
+    // throttle state comes from the usage snapshot (deriveUsageStatusFromSnapshot).
+    // Treating it as `rate_limited` let a burst-throttled endpoint mark every
+    // account LIMITED. See mergeAuthHealthEntries for the keep-or-unverified path.
     if (status === 429)
-        return 'rate_limited';
+        return 'error';
     return 'error';
 }
 /** Turn a raw provider probe (from usage.ts) into a verdict. */
@@ -62,6 +66,8 @@ export function probeDetail(probe) {
     if (probe.reason === 'usage_scope') {
         return probe.error ?? USAGE_HEADLESS_SCOPE_MARKER;
     }
+    if (probe.status === 429)
+        return 'probe throttled (HTTP 429)';
     if (probe.status != null && (probe.status < 200 || probe.status >= 300))
         return `HTTP ${probe.status}`;
     if (probe.error)
@@ -345,10 +351,22 @@ export function readFleetAuthRows(host) {
  * known verdict — otherwise one 8s timeout flips a `live` chip to `error`,
  * exactly the "cry wolf" the verdict model avoids for `expired`. This is the
  * behaviour promised by the `error` doc on AuthVerdict ("keep the last known
- * one"). Pure, so it's unit-tested directly. */
+ * one"). A probe-throttled 429 (detail `probe throttled (HTTP 429)`) keeps the
+ * previous real verdict when one exists within {@link AUTH_PROBE_MAX_AGE_MS},
+ * otherwise becomes `unverified` (PHNX-4051). Pure, so it's unit-tested directly. */
 export function mergeAuthHealthEntries(current, incoming) {
     const merged = { ...current };
     for (const [key, health] of Object.entries(incoming)) {
+        const isProbeThrottled = health.detail === 'probe throttled (HTTP 429)';
+        if (isProbeThrottled) {
+            const prev = merged[key];
+            const fresh = !!prev && prev.verdict !== 'error' && prev.verdict !== 'unconfigured'
+                && (health.checkedAt - prev.checkedAt < AUTH_PROBE_MAX_AGE_MS);
+            if (fresh)
+                continue; // keep previous real verdict
+            merged[key] = { ...health, verdict: 'unverified' };
+            continue;
+        }
         if (health.verdict === 'error' && merged[key])
             continue; // keep last known
         merged[key] = health;
@@ -470,13 +488,22 @@ export async function probeAuthHealth(agent, home, opts) {
  * per-install probe (also the `unconfigured` case dropped downstream). Pure: no
  * fs, no network, so the dedup decision is unit-tested directly.
  */
+/** Small fixed delay between live probes so one box no longer fires 16 requests in 4s (PHNX-4051). */
+export const AUTH_PROBE_SPACING_MS = 150;
 export function groupFleetAuthInstalls(installs, isMergeable = () => true) {
     const groups = new Map();
     for (const inst of installs) {
-        // The `acct:` / `ver:` tokens make the two branches disjoint, so an account
-        // label can never collide with a version fallback key no matter its content.
-        const key = inst.account && isMergeable(inst)
-            ? `${inst.agent} acct:${inst.account}`
+        // Prefer stable accountId (identity) — a version home and its slot share the
+        // same id, so they collapse to ONE probe per identity (PHNX-4051). Fallback
+        // to the display label when no id is known. The `id:`/`acct:`/`ver:` tokens
+        // keep the three branches disjoint.
+        const mergeKey = inst.accountId
+            ? `id:${inst.accountId}`
+            : inst.account
+                ? `acct:${inst.account}`
+                : null;
+        const key = mergeKey && isMergeable(inst)
+            ? `${inst.agent} ${mergeKey}`
             : `${inst.agent} ver:${inst.version}`;
         const existing = groups.get(key);
         if (existing)
@@ -514,26 +541,37 @@ export async function probeLocalFleetAuth(opts) {
         // A slot already knows its account; a version home is joined by identity.
         inst.accountId ??= findNativeAccountByIdentity(meta, inst.agent, inst.info)?.id;
     }
-    // Probe once per (agent, account) — but only for the network-probing agents
+    // Probe once per (agent, identity) — but only for the network-probing agents
     // that can actually 429; best-effort agents stay per-install (see
-    // groupFleetAuthInstalls). Groups run in parallel: they target distinct
-    // accounts, so no same-account concurrency is left to trip the throttle.
-    const perGroup = await Promise.all(groupFleetAuthInstalls(installs, (inst) => LIVE_PROBE_AGENTS.has(inst.agent)).map(async (group) => {
+    // groupFleetAuthInstalls). Groups are probed SEQUENTIALLY with a small fixed
+    // delay between them (PHNX-4051) so one box no longer fires 16 requests in
+    // 4s; they target distinct identities, so no same-account concurrency remains.
+    const groups = groupFleetAuthInstalls(installs, (inst) => LIVE_PROBE_AGENTS.has(inst.agent));
+    const perGroup = [];
+    for (let idx = 0; idx < groups.length; idx++) {
+        const group = groups[idx];
         const rep = group.probe;
         const health = await probeAuthHealth(rep.agent, rep.home, { cliVersion: opts?.cliVersion, info: rep.info, forceLive: opts?.forceLive, signal: opts?.signal });
         health.account = authAccountLabel(rep.info);
         health.accountId = rep.accountId;
-        if (health.verdict === 'unconfigured')
-            return [];
-        return group.members.map((inst) => ({
-            agent: inst.agent,
-            version: inst.version,
-            account: health.account,
-            accountId: inst.accountId ?? health.accountId,
-            // A distinct object per row so a later mutation of one can't bleed across.
-            health: { ...health },
-        }));
-    }));
+        if (health.verdict === 'unconfigured') {
+            perGroup.push([]);
+        }
+        else {
+            perGroup.push(group.members.map((inst) => ({
+                agent: inst.agent,
+                version: inst.version,
+                account: health.account,
+                accountId: inst.accountId ?? health.accountId,
+                // A distinct object per row so a later mutation of one can't bleed across.
+                health: { ...health },
+            })));
+        }
+        // Space probes; not after the last group and not if the tick is being aborted.
+        if (idx < groups.length - 1 && !opts?.signal?.aborted) {
+            await new Promise((resolve) => setTimeout(resolve, AUTH_PROBE_SPACING_MS));
+        }
+    }
     return perGroup.flat();
 }
 /**

package/dist/lib/auto-pull-worker.js

@@ -51,6 +51,13 @@ function tryAcquireLock(alias) {
         return false;
     }
 }
+function touchLock(alias) {
+    const now = new Date();
+    try {
+        fs.utimesSync(lockFilePath(alias), now, now);
+    }
+    catch { /* lock gone; nothing to extend */ }
+}
 function releaseLock(alias) {
     try {
         fs.unlinkSync(lockFilePath(alias));
@@ -118,6 +125,36 @@ async function processTarget(target) {
         releaseLock(target.alias);
     }
 }
+/**
+ * macOS only: fetch the floor AGI Menu release into the verified cache when the
+ * installed helper is behind it and no bundle ships with this install, so the
+ * next foreground invocation's network-free self-heal has a source to install
+ * from (`sourceAppPath` candidate 4). Same lock discipline as the repo targets.
+ */
+async function prefetchMenubarHelperTarget() {
+    if (process.platform !== 'darwin')
+        return;
+    const alias = 'menubar-helper';
+    if (!tryAcquireLock(alias))
+        return;
+    // The zip fetch may run up to 15 min (helper-download.ts) while the lock
+    // reads as stale after SYNC_LOCK_TTL_MS, and the download lands through one
+    // shared partial file — so keep the lock's mtime fresh for as long as this
+    // worker is actually fetching, or a second worker races onto the same bytes.
+    const heartbeat = setInterval(() => touchLock(alias), SYNC_LOCK_TTL_MS / 2);
+    heartbeat.unref();
+    try {
+        const { prefetchMenubarHelper } = await import('./menubar/install-menubar.js');
+        await prefetchMenubarHelper();
+    }
+    catch {
+        /* network / verification failures are non-fatal; the next cycle retries */
+    }
+    finally {
+        clearInterval(heartbeat);
+        releaseLock(alias);
+    }
+}
 async function main() {
     const targets = [];
     const systemDir = getSystemAgentsDir();
@@ -133,7 +170,7 @@ async function main() {
             targets.push({ alias: extra.alias, dir: extra.dir, mode: 'notify' });
         }
     }
-    await Promise.all(targets.map(processTarget));
+    await Promise.all([...targets.map(processTarget), prefetchMenubarHelperTarget()]);
     // Stamp the cycle so the next foreground CLI invocation can skip the ~7ms
     // detached spawn for SYNC_LOCK_TTL_MS (RUSH-2324). Written even when every
     // target was lock-skipped or the target list was empty — "nothing to do"

package/dist/lib/devices/harness-inventory.d.ts

@@ -36,6 +36,10 @@ export interface HarnessRow {
     reason?: string;
     verdict: AccountVerdict;
     fix: string | null;
+    /** The live usage snapshot backing `quota`, or null when none was collected. */
+    snapshot: UsageSnapshot | null;
+    /** Raw error string from the usage fetch, if any (headless scope, expired, etc.). */
+    usageError: string | null;
 }
 /** One host's rows, or the reason it produced none. */
 export interface HostHarnessResult {

package/dist/lib/devices/harness-inventory.js

@@ -123,7 +123,7 @@ export function applyUsageHonesty(verdict, usage) {
         }
         return { verdict, usage: stripped };
     }
-    if (usage.status === 'rate_limited' && (verdict === 'live' || verdict === 'unverified')) {
+    if ((usage.status === 'rate_limited' || usage.status === 'out_of_credits') && (verdict === 'live' || verdict === 'unverified')) {
         return { verdict: 'rate_limited', usage };
     }
     return { verdict, usage };
@@ -204,6 +204,8 @@ export async function collectLocalHarnessInventory(opts) {
             reason,
             verdict,
             fix: fixFor({ agent, verdict, name: saved?.name, version, provisioning }),
+            snapshot,
+            usageError: usage?.error ?? null,
         };
     });
 }

package/dist/lib/feed/pr-status.d.ts

@@ -1,4 +1,6 @@
 import type { ActiveSession } from '../session/active.js';
+import type { DetectedPr } from '../session/state.js';
+import type { GhExec } from '../github/pr-mergeable.js';
 import type { PullRequestAttentionSignal } from './attention.js';
 export declare const PR_STATUS_TTL_MS = 45000;
 export declare const PR_STATUS_FIELDS = "number,title,state,isDraft,reviewDecision,mergeable,statusCheckRollup";
@@ -9,6 +11,22 @@ export interface PullRequestStatus extends PullRequestAttentionSignal {
 export declare function readPullRequestStatus(session: ActiveSession, options?: {
     nowMs?: number;
     ttlMs?: number;
+    gh?: GhExec;
 }): Promise<PullRequestStatus | undefined>;
 export declare function projectPullRequestBoard(sessions: ActiveSession[]): Promise<PullRequestStatus[]>;
 export declare function resetPullRequestStatusCache(): void;
+/**
+ * The check rollup folded to one verdict; undefined when the PR has no checks.
+ * `statusCheckRollup` mixes Checks-API runs (`conclusion` + `status`) with
+ * legacy Status-API contexts (`state` only), so both shapes are read.
+ */
+export declare function checksVerdict(rollup?: unknown[]): DetectedPr['checks'];
+/**
+ * The row with its `pr` carrying the fetched status, so a consumer that only
+ * sees the agent row (the menu bar, the extension) can color the chip without
+ * its own `gh` call. A row without a PR, or a status that never resolved, is
+ * returned as is.
+ */
+export declare function withPullRequestStatus<T extends {
+    pr?: DetectedPr;
+}>(row: T, status?: PullRequestStatus): T;

package/dist/lib/feed/pr-status.js

@@ -24,12 +24,10 @@ export async function readPullRequestStatus(session, options = {}) {
     const hit = cache.get(key);
     if (hit && hit.expiresAt > now)
         return hit.value;
+    const cwd = session.cwd;
+    const gh = options.gh ?? (async (args) => (await execFileAsync('gh', args, { cwd, timeout: 15_000, maxBuffer: 1024 * 1024 })).stdout);
     try {
-        const { stdout } = await execFileAsync('gh', ['pr', 'view', String(ref), '--json', PR_STATUS_FIELDS], {
-            cwd: session.cwd,
-            timeout: 15_000,
-            maxBuffer: 1024 * 1024,
-        });
+        const stdout = await gh(['pr', 'view', String(ref), '--json', PR_STATUS_FIELDS]);
         const raw = JSON.parse(stdout);
         const value = { ...raw, url: session.pr?.url, needsHuman: needsHuman(raw) };
         cache.set(key, { expiresAt: now + (options.ttlMs ?? PR_STATUS_TTL_MS), value });
@@ -45,3 +43,43 @@ export async function projectPullRequestBoard(sessions) {
     return rows.filter((row) => row !== undefined);
 }
 export function resetPullRequestStatusCache() { cache.clear(); }
+/**
+ * The check rollup folded to one verdict; undefined when the PR has no checks.
+ * `statusCheckRollup` mixes Checks-API runs (`conclusion` + `status`) with
+ * legacy Status-API contexts (`state` only), so both shapes are read.
+ */
+export function checksVerdict(rollup) {
+    if (!rollup || rollup.length === 0)
+        return undefined;
+    let pending = false;
+    for (const check of rollup) {
+        const row = check;
+        const verdict = (row.conclusion || row.state || '').toUpperCase();
+        if (['FAILURE', 'ERROR', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED', 'STARTUP_FAILURE'].includes(verdict))
+            return 'failing';
+        if (verdict === '' ? (row.status ?? '').toUpperCase() !== 'COMPLETED' : ['PENDING', 'EXPECTED', 'STALE'].includes(verdict))
+            pending = true;
+    }
+    return pending ? 'pending' : 'passing';
+}
+/**
+ * The row with its `pr` carrying the fetched status, so a consumer that only
+ * sees the agent row (the menu bar, the extension) can color the chip without
+ * its own `gh` call. A row without a PR, or a status that never resolved, is
+ * returned as is.
+ */
+export function withPullRequestStatus(row, status) {
+    if (!row.pr || !status)
+        return row;
+    const pr = {
+        ...row.pr,
+        ...(status.state !== undefined ? { state: status.state } : {}),
+        ...(status.isDraft !== undefined ? { isDraft: status.isDraft } : {}),
+        ...(status.reviewDecision !== undefined ? { reviewDecision: status.reviewDecision } : {}),
+        ...(status.mergeable !== undefined ? { mergeable: status.mergeable } : {}),
+    };
+    const checks = checksVerdict(status.statusCheckRollup);
+    if (checks)
+        pr.checks = checks;
+    return { ...row, pr };
+}

package/dist/lib/feed/watch.d.ts

@@ -1,6 +1,7 @@
 import { type SessionWatchEnvelope, type SessionWatchRow, type SessionWatchScopeStatus, type WatchLocalOptions } from '../session/watch.js';
 import { type AttentionItem } from './attention.js';
 import { type ActivityEvent } from './activity.js';
+import type { GhExec } from '../github/pr-mergeable.js';
 export declare const FEED_WATCH_VERSION: 1;
 type Base = {
     v: 1;
@@ -47,7 +48,7 @@ export declare class FeedWatchState {
     constructor(streamId?: `${string}-${string}-${string}-${string}-${string}`);
     emit(event: FeedWatchPayload): FeedWatchEnvelope;
 }
-export declare function projectSessionEnvelope(event: SessionWatchEnvelope, state: FeedWatchState): Promise<FeedWatchEnvelope[]>;
+export declare function projectSessionEnvelope(event: SessionWatchEnvelope, state: FeedWatchState, gh?: GhExec): Promise<FeedWatchEnvelope[]>;
 export interface WatchLocalFeedOptions {
     scope: string;
     signal: AbortSignal;
@@ -58,6 +59,8 @@ export interface WatchLocalFeedOptions {
     reconcileMs?: number;
     /** Session-watch inputs, forwarded verbatim to {@link watchLocalSessions}. */
     sessions?: Pick<WatchLocalOptions, 'readCache' | 'readPrevious' | 'journalPath' | 'journalPollMs' | 'heartbeatMs'>;
+    /** The `gh` runner behind PR status; a test passes a recorded table. */
+    gh?: GhExec;
 }
 export declare function watchLocalFeed(options: WatchLocalFeedOptions): Promise<void>;
 export declare function watchFleetFeed(options: {

package/dist/lib/feed/watch.js

@@ -11,7 +11,7 @@ import { watchLocalSessions } from '../session/watch.js';
 import { readBlock, readResolution, blockIdForSession } from './feed.js';
 import { reconcileAttention } from './attention.js';
 import { ActivityStream } from './activity-stream.js';
-import { PR_STATUS_TTL_MS, readPullRequestStatus } from './pr-status.js';
+import { PR_STATUS_TTL_MS, readPullRequestStatus, withPullRequestStatus } from './pr-status.js';
 export const FEED_WATCH_VERSION = 1;
 export class FeedWatchState {
     streamId;
@@ -21,36 +21,51 @@ export class FeedWatchState {
         return { v: 1, streamId: this.streamId, sequence: ++this.sequence, ...event };
     }
 }
-async function attentionFor(agent) {
-    // Durable Previous rows share the operator stream for Sessions history, but
-    // they are not live work and must never synthesize Needs-you attention.
-    if (!agent.sessionId || agent.previous || agent.context === 'recent')
+/**
+ * Live rows only: durable Previous rows share the operator stream for Sessions
+ * history, but they are not live work and must never synthesize Needs-you
+ * attention or a PR lookup.
+ */
+function isLive(agent) {
+    return Boolean(agent.sessionId) && !agent.previous && agent.context !== 'recent';
+}
+// ActiveSession.host names the terminal app; the feed contract's host is the
+// device scope. Normalize only the reconciler input so lifecycle/PR keys are
+// routable across the fleet while the projected agent row stays compatible.
+function reconcilerSession(agent) {
+    return { ...agent, context: agent.context, host: agent.sourceDevice, viewingIn: undefined };
+}
+/** One `gh pr view` (cached 45 s) feeds both the attention verdict and the row's `pr` status. */
+async function pullRequestFor(agent, gh) {
+    if (!isLive(agent) || !agent.pr)
+        return undefined;
+    return readPullRequestStatus(reconcilerSession(agent), { gh });
+}
+function attentionFor(agent, pullRequest) {
+    if (!isLive(agent) || !agent.sessionId)
         return undefined;
     const blockId = blockIdForSession(agent.sessionId);
-    // ActiveSession.host names the terminal app; the feed contract's host is the
-    // device scope. Normalize only the reconciler input so lifecycle/PR keys are
-    // routable across the fleet while the projected agent row stays compatible.
-    const session = {
-        ...agent,
-        context: agent.context,
-        host: agent.sourceDevice,
-        viewingIn: undefined,
-    };
     return reconcileAttention({
-        block: readBlock(blockId), session,
+        block: readBlock(blockId), session: reconcilerSession(agent),
         resolution: readResolution(blockId),
-        pullRequest: await readPullRequestStatus(session), nowMs: Date.now(),
+        pullRequest, nowMs: Date.now(),
     });
 }
-export async function projectSessionEnvelope(event, state) {
+/** The row as the feed projects it: the session row with its PR status attached. */
+async function projectAgent(agent, gh) {
+    const pullRequest = await pullRequestFor(agent, gh);
+    return { agent: withPullRequestStatus(agent, pullRequest), attention: attentionFor(agent, pullRequest) };
+}
+export async function projectSessionEnvelope(event, state, gh) {
     if (event.type === 'reset') {
-        const attention = (await Promise.all(event.rows.map(attentionFor))).filter((item) => item !== undefined);
-        return [state.emit({ type: 'reset', capturedAt: event.capturedAt, scope: event.scope, agents: event.rows, attention })];
+        const projected = await Promise.all(event.rows.map((row) => projectAgent(row, gh)));
+        const attention = projected.map((p) => p.attention).filter((item) => item !== undefined);
+        return [state.emit({ type: 'reset', capturedAt: event.capturedAt, scope: event.scope, agents: projected.map((p) => p.agent), attention })];
     }
     if (event.type === 'upsert') {
-        const attention = await attentionFor(event.row);
+        const { agent, attention } = await projectAgent(event.row, gh);
         return [
-            state.emit({ type: 'agent.upsert', scope: event.scope, rowKey: event.rowKey, agent: event.row }),
+            state.emit({ type: 'agent.upsert', scope: event.scope, rowKey: event.rowKey, agent }),
             attention
                 ? state.emit({ type: 'attention.upsert', scope: event.scope, rowKey: event.rowKey, attention })
                 : state.emit({ type: 'attention.remove', scope: event.scope, rowKey: event.rowKey }),
@@ -99,10 +114,18 @@ export async function watchLocalFeed(options) {
     let activityCursor = Date.now();
     const agents = new Map();
     const attention = new Map();
+    // The PR status last projected onto each row, so a merge or a check verdict
+    // that lands between session events still reaches the row's consumers.
+    const prStatus = new Map();
     let pending = Promise.resolve();
     const reconcileRows = async () => {
-        for (const [rowKey, agent] of agents) {
-            const item = await attentionFor(agent);
+        for (const [rowKey, raw] of agents) {
+            const { agent, attention: item } = await projectAgent(raw, options.gh);
+            const nextPr = agent.pr ? JSON.stringify(agent.pr) : '';
+            if (agent.pr && prStatus.get(rowKey) !== nextPr) {
+                prStatus.set(rowKey, nextPr);
+                options.emit(state.emit({ type: 'agent.upsert', scope: options.scope, rowKey, agent }));
+            }
             const next = item ? JSON.stringify(item) : '';
             if (attention.get(rowKey) === next)
                 continue;
@@ -150,19 +173,28 @@ export async function watchLocalFeed(options) {
                 else if (event.type === 'remove') {
                     agents.delete(event.rowKey);
                     attention.delete(event.rowKey);
+                    prStatus.delete(event.rowKey);
                 }
-                pending = pending.then(() => projectSessionEnvelope(event, state)).then((events) => {
+                pending = pending.then(() => projectSessionEnvelope(event, state, options.gh)).then((events) => {
                     for (const projected of events) {
                         if (projected.type === 'reset') {
                             attention.clear();
-                            for (const row of projected.agents)
+                            prStatus.clear();
+                            for (const row of projected.agents) {
                                 attention.set(row.rowKey, '');
+                                if (row.pr)
+                                    prStatus.set(row.rowKey, JSON.stringify(row.pr));
+                            }
                             for (const item of projected.attention) {
                                 const row = projected.agents.find((agent) => agent.sessionId === item.sessionId);
                                 if (row)
                                     attention.set(row.rowKey, JSON.stringify(item));
                             }
                         }
+                        else if (projected.type === 'agent.upsert') {
+                            if (projected.agent.pr)
+                                prStatus.set(projected.rowKey, JSON.stringify(projected.agent.pr));
+                        }
                         else if (projected.type === 'attention.upsert')
                             attention.set(projected.rowKey, JSON.stringify(projected.attention));
                         else if (projected.type === 'attention.remove')

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.1.4' },
+    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

@@ -68,6 +68,22 @@ export declare function resolveInstalledMenubarExecutable(): string | null;
 export declare function menubarDisabledByUser(): boolean;
 /** True if the launchd plist for the menu-bar service is installed. */
 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;
 /**
@@ -203,6 +219,33 @@ export declare function isMenubarStale(opts: {
     available: MenubarStamp;
     execExists: boolean;
 }): boolean;
+/**
+ * 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 declare function menubarHelperPrefetchNeeded(opts: {
+    darwin: boolean;
+    disabledByUser: boolean;
+    /** `sourceAppPath()` found a bundle (shipped or already cached). */
+    hasSource: boolean;
+    serviceInstalled: boolean;
+    stale: boolean;
+}): boolean;
+/**
+ * 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 declare function prefetchMenubarHelper(): Promise<string | null>;
 /**
  * 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?
@@ -482,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>;