@phnx-labs/agents-cli 1.22.50 → 1.22.51

package/dist/lib/config-keys.js

@@ -88,6 +88,9 @@ export function parseConfigKey(key) {
     if (raw === 'browser.viewer') {
         return { scope: 'browser', property: 'viewer' };
     }
+    if (raw === 'browser.device') {
+        return { scope: 'browser', property: 'device' };
+    }
     if (raw === 'project.root') {
         return { scope: 'project', property: 'root' };
     }
@@ -110,7 +113,7 @@ export function parseConfigKey(key) {
         throw new Error(`Invalid auto config key '${key}'. Use auto.pool.`);
     }
     if (raw.startsWith('browser.')) {
-        throw new Error(`Invalid browser config key '${key}'. Use browser.profile or browser.viewer.`);
+        throw new Error(`Invalid browser config key '${key}'. Use browser.profile, browser.viewer, or browser.device.`);
     }
     if (raw.startsWith('project.')) {
         throw new Error(`Invalid project config key '${key}'. Use project.root.`);
@@ -149,7 +152,7 @@ export function listKnownConfigKeys() {
     for (const tier of MODEL_TIERS) {
         keys.push(`run.<agent@version>.tier.${tier}`);
     }
-    keys.push('interactive.host', 'auto.pool', 'browser.profile', 'browser.viewer', 'project.root');
+    keys.push('interactive.host', 'auto.pool', 'browser.profile', 'browser.viewer', 'browser.device', 'project.root');
     for (const prop of DEVICE_CONFIG_PROPERTIES) {
         keys.push(`devices.<name>.${prop}`);
     }
@@ -202,6 +205,10 @@ export function configKeyStorageHint(parsed) {
         case 'auto':
             return 'config.autoPool';
         case 'browser': {
+            if (parsed.property === 'device') {
+                // User scope: one value in the central agents.yaml that syncs fleet-wide.
+                return 'config.defaultBrowserDevice (central agents.yaml; syncs fleet-wide)';
+            }
             const yamlKey = parsed.property === 'viewer' ? 'browserViewer' : 'defaultBrowserProfile';
             return parsed.device
                 ? `devices/${parsed.device}/agents.yaml config.${yamlKey}`

package/dist/lib/device-config.js

@@ -94,6 +94,29 @@ export const CONFIG_KEYS = [
         type: 'string',
         description: 'Browser profile `agents browser start` resolves to without --profile (set via `agents browser use`).',
     },
+    {
+        name: 'browser.device',
+        yamlKey: 'defaultBrowserDevice',
+        // user scope, so a SINGLE value in the central agents.yaml syncs to every box:
+        // the fleet's browser hub. A worker with this set forwards its browser drives
+        // to the hub (as if `--device <hub>` was passed) with no per-command flag, so
+        // every agent shares the hub's one logged-in browser. The hub names itself, so
+        // there it resolves to a self-host and runs locally — which is why one synced
+        // value is safe. Unset = drive this box's own browser (today's behavior).
+        scope: 'user',
+        type: 'string',
+        description: 'Fleet browser hub: the device whose browser `agents browser` drive verbs target by default, with no --device. ' +
+            'The hub itself runs locally; every other box forwards to it. Unset = each box drives its own browser.',
+        validate: (v) => {
+            try {
+                assertValidDeviceName(v);
+                return null;
+            }
+            catch (err) {
+                return err?.message ?? String(err);
+            }
+        },
+    },
     {
         name: 'agents.max-concurrent',
         yamlKey: 'maxAgents',

package/dist/lib/factory/snapshot.d.ts

@@ -13,7 +13,7 @@ export declare const FACTORY_PROJECTS: readonly [{
     readonly repo: "phnx-labs/rush-cli";
 }, {
     readonly name: "Agents CLI";
-    readonly repo: "phnx-labs/agents-cli";
+    readonly repo: "phnx-labs/agi-cli";
 }, {
     readonly name: "Linear CLI";
     readonly repo: "phnx-labs/linear-cli";

package/dist/lib/factory/snapshot.js

@@ -25,7 +25,7 @@ export const FACTORY_PROJECTS = [
     { name: 'Prix', repo: 'phnx-labs/prix' },
     { name: 'Rush App', repo: 'phnx-labs/rush' },
     { name: 'Rush CLI', repo: 'phnx-labs/rush-cli' },
-    { name: 'Agents CLI', repo: 'phnx-labs/agents-cli' },
+    { name: 'Agents CLI', repo: 'phnx-labs/agi-cli' },
     { name: 'Linear CLI', repo: 'phnx-labs/linear-cli' },
 ];
 const defaults = () => ({

package/dist/lib/helper-download.d.ts

@@ -16,8 +16,18 @@
  * lands for both helpers at once.
  */
 import { type HelperName } from './helper-versions.js';
-/** GitHub repo whose `v<version>` releases carry the helper assets. */
-export declare const HELPER_RELEASE_REPO = "phnx-labs/agents-cli";
+/**
+ * GitHub repo whose `<helper>/v<version>` releases carry the helper assets.
+ *
+ * This is the SLUG, which is not the npm package name: the package is still
+ * `@phnx-labs/agents-cli`, but the repository was renamed to `agi-cli`. The old
+ * slug kept working only because GitHub redirects a renamed repo, which is a
+ * poor thing to hang signed-binary delivery on — a redirect is one re-created
+ * repo away from resolving somewhere else. What actually protects the download
+ * is the sha256 + codesign + designated-requirement + Team ID verification
+ * below; this just stops relying on the redirect.
+ */
+export declare const HELPER_RELEASE_REPO = "phnx-labs/agi-cli";
 /** Apple Developer ID Team every helper must be signed by ("Developer ID
  *  Application: Muqit Nawaz"). Defense in depth on top of `spctl` notarization. */
 export declare const EXPECTED_TEAM_ID = "2HTP252L87";

package/dist/lib/helper-download.js

@@ -23,8 +23,18 @@ import { pipeline } from 'node:stream/promises';
 import { getCacheDir } from './state.js';
 import { parseSha256Asset, sha256File } from './sha256-asset.js';
 import { helperTag } from './helper-versions.js';
-/** GitHub repo whose `v<version>` releases carry the helper assets. */
-export const HELPER_RELEASE_REPO = 'phnx-labs/agents-cli';
+/**
+ * GitHub repo whose `<helper>/v<version>` releases carry the helper assets.
+ *
+ * This is the SLUG, which is not the npm package name: the package is still
+ * `@phnx-labs/agents-cli`, but the repository was renamed to `agi-cli`. The old
+ * slug kept working only because GitHub redirects a renamed repo, which is a
+ * poor thing to hang signed-binary delivery on — a redirect is one re-created
+ * repo away from resolving somewhere else. What actually protects the download
+ * is the sha256 + codesign + designated-requirement + Team ID verification
+ * below; this just stops relying on the redirect.
+ */
+export const HELPER_RELEASE_REPO = 'phnx-labs/agi-cli';
 /** Apple Developer ID Team every helper must be signed by ("Developer ID
  *  Application: Muqit Nawaz"). Defense in depth on top of `spctl` notarization. */
 export const EXPECTED_TEAM_ID = '2HTP252L87';

package/dist/lib/installations/migrate.js

@@ -298,7 +298,7 @@ function foldUserHooksYamlIntoAgentsYaml() {
     meta.hooks = merged;
     const header = `# agents-cli metadata
 # Auto-generated - do not edit manually
-# https://github.com/phnx-labs/agents-cli
+# https://github.com/phnx-labs/agi-cli
 
 `;
     try {
@@ -414,7 +414,7 @@ function foldBrowserProfilesIntoAgentsYaml() {
     meta.browser = merged;
     const header = `# agents-cli metadata
 # Auto-generated - do not edit manually
-# https://github.com/phnx-labs/agents-cli
+# https://github.com/phnx-labs/agi-cli
 
 `;
     try {
@@ -1641,7 +1641,7 @@ function migrateVersionResourcesToPatterns() {
         }
     }
     if (changed) {
-        const META_HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/cli/schema/agents-yaml.schema.json\n\n';
+        const META_HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agi-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agi-cli/main/cli/schema/agents-yaml.schema.json\n\n';
         fs.writeFileSync(metaFile, META_HEADER + yaml.stringify(meta), 'utf-8');
         console.error('Migrated agents.yaml versions: entries to pattern format');
     }
@@ -1668,7 +1668,7 @@ function migrateSplitDeviceLocalMeta() {
     const agents = meta.agents;
     const versions = meta.versions;
     const hasLocal = (!!agents && Object.keys(agents).length > 0) || (!!versions && Object.keys(versions).length > 0);
-    const HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n\n';
+    const HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agi-cli\n\n';
     // Only rewrite central when it actually carries machine-local fields — a
     // machine whose agents.yaml is already portable-only is left untouched.
     if (hasLocal) {

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

@@ -35,6 +35,26 @@ export declare const MENUBAR_HELPER_EXECUTABLE_NAME = "AGI Menu";
  * hermetic test fork's own teardown boots out the operator's live helper.
  */
 export declare function serviceLabel(): string;
+/**
+ * What the installed helper IS — deliberately not the CLI's version.
+ *
+ * `source` matters because the two install paths have different notions of
+ * "changed": a release bundle is identified by its helper version, while a local
+ * dev build has none (menubar/scripts/build.sh hardcodes CFBundleShortVersionString),
+ * so it is identified by the source path + mtime it was copied from.
+ */
+/** Version label for a bundle that has none of its own (a local dev build). */
+export declare const LOCAL_BUILD_LABEL = "local";
+export type MenubarStamp = {
+    source: 'release';
+    helperVersion: string;
+} | {
+    source: 'local';
+    sourceStamp: string;
+} | {
+    source: 'legacy';
+    raw: string;
+};
 /**
  * Absolute path to the installed menu-bar helper executable if it exists on
  * disk, else null. The desktop notifier (notify-desktop.ts) routes daemon
@@ -136,16 +156,50 @@ export declare function enableMenubarService(opts?: {
     clearOptOut?: boolean;
 }): Promise<boolean>;
 /**
- * Pure staleness decision (no I/O) so the truth table is unit-testable. The
- * installed service is stale when the helper binary is gone, or when it was
- * installed by a different CLI version than the one now running — a version
- * change is the signal that the plist's baked interpreter/entry/bundle paths
- * and the helper binary itself may have drifted. A null installedVersion
- * (pre-stamp install) counts as stale so old installs get re-stamped once.
+ * Render a stamp as a comparable/displayable version string.
+ *
+ * A local build has no version of its own, so it reports `local`; the ownership
+ * contest treats that as "not comparable" and falls through to its owner arm,
+ * which is the correct outcome — a dev build must never win a version contest
+ * against a release.
+ */
+export declare function stampVersionLabel(stamp: MenubarStamp | null): string | null;
+/**
+ * Identify the bundle about to be installed, for the stamp.
+ *
+ * A bundle is a RELEASE iff it sits under the helper's own download cache —
+ * asked of `menubarHelperCacheDir`, not pattern-matched out of the path. A regex
+ * for `/v<x.y.z>/` gets this wrong in both directions: a checkout living under
+ * any directory that happens to contain a version-shaped segment reads as a
+ * release, and a release cache laid out differently reads as local. Either
+ * misclassification flips `source` between invocations, and a kind change is
+ * unconditionally stale — which is a reinstall loop.
+ */
+export declare function stampFor(resolvedSourceAppPath: string): MenubarStamp;
+/**
+ * The helper version a path denotes, iff it is inside that version's cache dir.
+ * Returns null for anything else — including a version-shaped path that is not
+ * actually the cache.
+ */
+export declare function releaseVersionOfCachedBundle(appPath: string, cacheDirFor?: (v: string) => string): string | null;
+/**
+ * Pure staleness decision (no I/O) so the truth table is unit-testable.
+ *
+ * This compares the HELPER axis, not the CLI's. It used to compare the installed
+ * stamp against `getCliVersion()`, which was wrong in both directions once the
+ * helpers gained their own version line: every CLI release made an unchanged
+ * helper look stale and reinstalled it (the #2109 restart storm), while a
+ * genuinely newer helper at the same CLI version never looked stale at all.
+ *
+ * Stale when: the executable is gone; nothing is stamped; the stamp predates the
+ * JSON format (`legacy` — re-stamped once); the install KIND changed
+ * (local <-> release), since a dev build and a release bundle are not
+ * interchangeable; a release install whose available helper version is newer;
+ * or a local install whose source path or mtime moved.
  */
 export declare function isMenubarStale(opts: {
-    installedVersion: string | null;
-    currentVersion: string;
+    installed: MenubarStamp | null;
+    available: MenubarStamp;
     execExists: boolean;
 }): boolean;
 /**
@@ -354,8 +408,12 @@ export interface MenubarStatus {
     platform: string;
     source: string | null;
     installedApp: string | null;
+    /** The installed HELPER's version — not the CLI's. `local` for a dev build. */
     installedVersion: string | null;
+    /** The helper version this install would put on disk right now. */
     currentVersion: string;
+    /** The CLI's own version, reported separately so the two are never conflated. */
+    cliVersion: string;
     stale: boolean;
     serviceInstalled: boolean;
     running: boolean;
@@ -370,8 +428,13 @@ export declare function getMenubarStatus(): MenubarStatus;
 export interface MenubarDoctorReport {
     platform: string;
     installPath: string | null;
+    /** The installed HELPER's version — not the CLI's. `local` for a dev build. */
     installedVersion: string | null;
+    /** The helper version this install would put on disk right now. */
     currentVersion: string;
+    /** The CLI's own version, reported separately so the two are never conflated. */
+    cliVersion: string;
+    /** installed helper vs available helper. Never compares the CLI's version. */
     versionMatches: boolean;
     /** `unknown` on non-darwin or when nothing is installed to inspect. */
     signingIdentity: 'developer-id' | 'ad-hoc' | 'unknown';

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

@@ -25,7 +25,7 @@ import { getCliVersion, resolveAgentsBin, resolveInstalledLayout } from '../vers
 import { copyAppBundle, withInstallLock } from '../app-bundle-install.js';
 import { compareVersions } from '../agent-spec/primitives.js';
 import { namespacedServiceLabel, serviceManifestHomeEnv, serviceManagerRegistrationAllowed } from '../service-manifest.js';
-import { downloadMenubarHelperApp } from './download-menubar.js';
+import { downloadMenubarHelperApp, menubarHelperCacheDir } from './download-menubar.js';
 import { helperFloor } from '../helper-versions.js';
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
 const INSTALL_DIR_NAME = 'agents-cli';
@@ -89,13 +89,42 @@ function installedAppPath() {
 function installedVersionMarkerPath() {
     return path.join(installDir(), '.menubar-version');
 }
-function readInstalledMenubarVersion() {
+/**
+ * What the installed helper IS — deliberately not the CLI's version.
+ *
+ * `source` matters because the two install paths have different notions of
+ * "changed": a release bundle is identified by its helper version, while a local
+ * dev build has none (menubar/scripts/build.sh hardcodes CFBundleShortVersionString),
+ * so it is identified by the source path + mtime it was copied from.
+ */
+/** Version label for a bundle that has none of its own (a local dev build). */
+export const LOCAL_BUILD_LABEL = 'local';
+/**
+ * Read the stamp, tolerating the pre-JSON format.
+ *
+ * Older installs wrote a bare version string — and wrote the CLI's version into
+ * it, which is the bug this replaces. Such a stamp cannot be compared on the
+ * helper axis at all, so it reports `legacy` and is treated as stale exactly
+ * once, which re-stamps it in the new format. That mirrors the existing
+ * null-is-stale rule and is why the migration cannot loop.
+ */
+function readInstalledMenubarStamp() {
+    let raw;
     try {
-        return fs.readFileSync(installedVersionMarkerPath(), 'utf-8').trim() || null;
+        raw = fs.readFileSync(installedVersionMarkerPath(), 'utf-8').trim();
     }
     catch {
         return null;
     }
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && (parsed.source === 'release' || parsed.source === 'local'))
+            return parsed;
+    }
+    catch { /* fall through to legacy */ }
+    return { source: 'legacy', raw };
 }
 /** Executable inside the installed bundle. */
 function installedExecutablePath() {
@@ -425,7 +454,17 @@ export function restartMenubarHelperAfterSwap(uid, ownProcesses, exec = execFile
 function startMenubarServiceFromSource(opts = {}) {
     if (!onDarwin())
         return false;
-    const exec = ensureMenubarAppInstalled({ forceReinstall: true, sourceAppPath: opts.sourceAppPath });
+    // Resolve the source HERE, once, and hand the SAME value to the installer and
+    // the stamp. Passing `opts.sourceAppPath` to both let them disagree: the
+    // installer falls back to `sourceAppPath()` internally, so on the self-heal
+    // path (which passes nothing) it would install a LOCAL build while the stamp
+    // recorded a release version. The next invocation then computed `local`, saw a
+    // kind mismatch, and reinstalled — every time, forever. That is the #2109
+    // storm this whole change exists to stop, so the two must read one variable.
+    const src = opts.sourceAppPath ?? sourceAppPath();
+    if (!src)
+        return false;
+    const exec = ensureMenubarAppInstalled({ forceReinstall: true, sourceAppPath: src });
     if (!exec)
         return false;
     // Never bootstrap a helper macOS will reject at launch: an invalid signature
@@ -441,7 +480,7 @@ function startMenubarServiceFromSource(opts = {}) {
     }
     if (opts.clearOptOut)
         clearMenubarOptOut();
-    installAndStartService(exec);
+    installAndStartService(exec, stampFor(src));
     return true;
 }
 /**
@@ -481,33 +520,121 @@ function clearMenubarOptOut() {
  * particular is what the upgrade self-heal reads to decide staleness, and a
  * path that skipped it would make every later `agents` invocation reinstall.
  */
-function installAndStartService(exec) {
+function installAndStartService(exec, stamp) {
     const plist = servicePlistPath();
     fs.mkdirSync(path.dirname(plist), { recursive: true });
     fs.writeFileSync(plist, generateServicePlist(exec));
     restartMenubarLaunchAgent(process.getuid?.() ?? 0, plist);
     try {
-        fs.writeFileSync(installedVersionMarkerPath(), getCliVersion());
+        fs.writeFileSync(installedVersionMarkerPath(), JSON.stringify(stamp));
+    }
+    catch { /* best effort */ }
+}
+/**
+ * Render a stamp as a comparable/displayable version string.
+ *
+ * A local build has no version of its own, so it reports `local`; the ownership
+ * contest treats that as "not comparable" and falls through to its owner arm,
+ * which is the correct outcome — a dev build must never win a version contest
+ * against a release.
+ */
+export function stampVersionLabel(stamp) {
+    if (!stamp)
+        return null;
+    if (stamp.source === 'release')
+        return stamp.helperVersion;
+    if (stamp.source === 'legacy')
+        return null;
+    return LOCAL_BUILD_LABEL;
+}
+/** What this install would put on disk right now, as a 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') };
+}
+/** The helper version this install would put on disk right now, for display. */
+function availableHelperLabel() {
+    return stampVersionLabel(availableStamp()) ?? LOCAL_BUILD_LABEL;
+}
+/**
+ * Identify the bundle about to be installed, for the stamp.
+ *
+ * A bundle is a RELEASE iff it sits under the helper's own download cache —
+ * asked of `menubarHelperCacheDir`, not pattern-matched out of the path. A regex
+ * for `/v<x.y.z>/` gets this wrong in both directions: a checkout living under
+ * any directory that happens to contain a version-shaped segment reads as a
+ * release, and a release cache laid out differently reads as local. Either
+ * misclassification flips `source` between invocations, and a kind change is
+ * unconditionally stale — which is a reinstall loop.
+ */
+export function stampFor(resolvedSourceAppPath) {
+    const version = releaseVersionOfCachedBundle(resolvedSourceAppPath);
+    if (version)
+        return { source: 'release', helperVersion: version };
+    let mtime = 0;
+    try {
+        mtime = fs.statSync(resolvedSourceAppPath).mtimeMs;
     }
     catch { /* best effort */ }
+    return { source: 'local', sourceStamp: `${resolvedSourceAppPath}@${mtime}` };
+}
+/**
+ * The helper version a path denotes, iff it is inside that version's cache dir.
+ * Returns null for anything else — including a version-shaped path that is not
+ * actually the cache.
+ */
+export function releaseVersionOfCachedBundle(appPath, cacheDirFor = menubarHelperCacheDir) {
+    // Try EVERY version-shaped segment, not just the leftmost. A cached bundle
+    // under a home or mount path that itself contains an unrelated `vX.Y.Z`
+    // (an nvm dir, a versioned volume) would otherwise match that first segment,
+    // fail the prefix check, and be misclassified as a local build.
+    const resolved = path.resolve(appPath);
+    for (const m of appPath.matchAll(/v(\d+\.\d+\.\d+)/g)) {
+        const expected = path.resolve(cacheDirFor(m[1]));
+        if (resolved === expected || resolved.startsWith(expected + path.sep))
+            return m[1];
+    }
+    return null;
 }
 /**
- * Pure staleness decision (no I/O) so the truth table is unit-testable. The
- * installed service is stale when the helper binary is gone, or when it was
- * installed by a different CLI version than the one now running — a version
- * change is the signal that the plist's baked interpreter/entry/bundle paths
- * and the helper binary itself may have drifted. A null installedVersion
- * (pre-stamp install) counts as stale so old installs get re-stamped once.
+ * Pure staleness decision (no I/O) so the truth table is unit-testable.
+ *
+ * This compares the HELPER axis, not the CLI's. It used to compare the installed
+ * stamp against `getCliVersion()`, which was wrong in both directions once the
+ * helpers gained their own version line: every CLI release made an unchanged
+ * helper look stale and reinstalled it (the #2109 restart storm), while a
+ * genuinely newer helper at the same CLI version never looked stale at all.
+ *
+ * Stale when: the executable is gone; nothing is stamped; the stamp predates the
+ * JSON format (`legacy` — re-stamped once); the install KIND changed
+ * (local <-> release), since a dev build and a release bundle are not
+ * interchangeable; a release install whose available helper version is newer;
+ * or a local install whose source path or mtime moved.
  */
 export function isMenubarStale(opts) {
     if (!opts.execExists)
         return true;
-    return opts.installedVersion !== opts.currentVersion;
+    const { installed, available } = opts;
+    if (!installed)
+        return true;
+    if (installed.source === 'legacy')
+        return true;
+    if (installed.source !== available.source)
+        return true;
+    if (installed.source === 'release' && available.source === 'release') {
+        return compareVersions(available.helperVersion, installed.helperVersion) > 0;
+    }
+    if (installed.source === 'local' && available.source === 'local') {
+        return installed.sourceStamp !== available.sourceStamp;
+    }
+    return true;
 }
 function menubarSetupStale() {
     return isMenubarStale({
-        installedVersion: readInstalledMenubarVersion(),
-        currentVersion: getCliVersion(),
+        installed: readInstalledMenubarStamp(),
+        available: availableStamp(),
         execExists: fs.existsSync(installedExecutablePath()),
     });
 }
@@ -662,7 +789,14 @@ export function mayInstallMenubarHelper(opts) {
     // running, nothing deadlocks.
     if (!opts.ownerEntryExists)
         return opts.sourceIsDeveloperId;
-    if (opts.installedVersion && opts.currentVersion) {
+    // `local` is a KIND marker, not a version — a dev build has none. Comparing it
+    // with compareVersions would order it against real semver arbitrarily and let a
+    // dev build win (or lose) a contest it should not enter. When either side is a
+    // local build the version arm is skipped entirely and the owner arm decides,
+    // which is the correct outcome: ownership, not version, distinguishes them.
+    const comparableVersions = opts.installedVersion && opts.currentVersion &&
+        opts.installedVersion !== LOCAL_BUILD_LABEL && opts.currentVersion !== LOCAL_BUILD_LABEL;
+    if (comparableVersions) {
         const versionOrder = compareVersions(opts.currentVersion, opts.installedVersion);
         if (versionOrder > 0)
             return opts.sourceIsDeveloperId;
@@ -730,8 +864,8 @@ function mayHealMenubar(needsDevIdHeal) {
         ownerEntryExists: Boolean(plistEntry) && fs.existsSync(plistEntry),
         helperExecMissing: !fs.existsSync(installedExecutablePath()),
         needsDevIdHeal,
-        installedVersion: readInstalledMenubarVersion(),
-        currentVersion: getCliVersion(),
+        installedVersion: stampVersionLabel(readInstalledMenubarStamp()),
+        currentVersion: availableHelperLabel(),
         msSinceLastHeal: msSinceLastMenubarHeal(),
         cooldownMs: MENUBAR_TAKEOVER_COOLDOWN_MS,
         sourceIsDeveloperId: Boolean(src) && hasDeveloperIdSignature(src),
@@ -931,7 +1065,24 @@ export async function runMenubarSetup() {
         step('bundle', 'failed', 'could not install the helper bundle');
         return { steps, configured: false, status: getMenubarStatus() };
     }
-    step('bundle', before.installedVersion === getCliVersion() ? 'ok' : 'changed', `${installedAppPath()} (${getCliVersion()})`);
+    // The helper axis here too: this label read "ok" only when the installed
+    // helper's stamp happened to equal the CLI's version, which after this change
+    // is never true on a release install.
+    //
+    // Compare the STAMPS, not their labels. `stampVersionLabel` collapses every
+    // local build to the literal 'local', discarding the mtime — so a real dev
+    // rebuild (which the surrounding logic does correctly reinstall) would print
+    // "ok" and hide that anything changed. That is the same collapse already
+    // excluded in `versionMatches` and `mayInstallMenubarHelper`; this was the
+    // third site and the only one still reading through the lossy label.
+    const bundleStamp = readInstalledMenubarStamp();
+    // Reuse the file's canonical comparator rather than a second, serialization
+    // -based one: `JSON.stringify` was sound only because both stamps come from
+    // `stampFor`, which is an implicit key-order dependency with no reason to
+    // exist when isMenubarStale already answers exactly this question.
+    const bundleUnchanged = bundleStamp !== null &&
+        !isMenubarStale({ installed: bundleStamp, available: availableStamp(), execExists: true });
+    step('bundle', bundleUnchanged ? 'ok' : 'changed', `${installedAppPath()} (${stampVersionLabel(bundleStamp) ?? 'unknown'})`);
     if (!(codesignVerifies(installedAppPath()) && gatekeeperAssesses(installedAppPath()))) {
         step('signature', 'failed', 'not notarized/valid on this machine — refusing to start it (Gatekeeper rejects an ' +
             'un-notarized helper as "damaged"). Upgrade to a notarized build of agents-cli.');
@@ -941,7 +1092,7 @@ export async function runMenubarSetup() {
     // Clear the sticky opt-out: running `setup` is an explicit request for the
     // menu bar, so a stale `menubar disable` must not silently win.
     clearMenubarOptOut();
-    installAndStartService(exec);
+    installAndStartService(exec, stampFor(src ?? undefined));
     step('login item', before.serviceInstalled ? 'ok' : 'changed', `${serviceLabel()} — starts at login, restarts if it dies`);
     // launchd's bootstrap+kickstart is asynchronous; give the status item a beat
     // to claim the lock before counting instances, or `setup` reports zero on a
@@ -1043,8 +1194,9 @@ export function getMenubarStatus() {
         platform: process.platform,
         source: sourceAppPath(),
         installedApp: fs.existsSync(dest) ? dest : null,
-        installedVersion: readInstalledMenubarVersion(),
-        currentVersion: getCliVersion(),
+        installedVersion: stampVersionLabel(readInstalledMenubarStamp()),
+        currentVersion: availableHelperLabel(),
+        cliVersion: getCliVersion(),
         stale: onDarwin() && serviceInstalled && menubarSetupStale(),
         serviceInstalled,
         running: own.length > 0,
@@ -1105,6 +1257,7 @@ export function buildMenubarDoctorReport() {
             installPath: null,
             installedVersion: null,
             currentVersion: getCliVersion(),
+            cliVersion: getCliVersion(),
             versionMatches: false,
             signingIdentity: 'unknown',
             running: false,
@@ -1137,7 +1290,13 @@ export function buildMenubarDoctorReport() {
         installPath: appPath,
         installedVersion: status.installedVersion,
         currentVersion: status.currentVersion,
-        versionMatches: status.installedVersion === status.currentVersion,
+        cliVersion: status.cliVersion,
+        // Two local builds are not a version "mismatch" — neither carries a version.
+        // Reporting one told the user to run `setup` for a difference that does not
+        // exist, which is what made the old hint fire forever.
+        versionMatches: status.installedVersion === LOCAL_BUILD_LABEL && status.currentVersion === LOCAL_BUILD_LABEL
+            ? true
+            : status.installedVersion === status.currentVersion,
         signingIdentity,
         running: status.running,
         staleRunningProcess,

package/dist/lib/star-nudge.d.ts

@@ -8,8 +8,8 @@
  * repeats. It is a plain inline line — not a toast, not a nag — and stays out
  * of the way of non-interactive, CI, quiet, and JSON output.
  */
-/** Canonical GitHub repo the nudge points at. */
-export declare const REPO_URL = "https://github.com/phnx-labs/agents-cli";
+/** Canonical GitHub repo the nudge points at (renamed from agents-cli). */
+export declare const REPO_URL = "https://github.com/phnx-labs/agi-cli";
 /** Has the star nudge already been shown on this machine? */
 export declare function hasShownStarNudge(): boolean;
 /** Inputs to the pure show/skip decision (kept side-effect free for testing). */

package/dist/lib/star-nudge.js

@@ -12,8 +12,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
 import { getRuntimeStateDir } from './state.js';
-/** Canonical GitHub repo the nudge points at. */
-export const REPO_URL = 'https://github.com/phnx-labs/agents-cli';
+/** Canonical GitHub repo the nudge points at (renamed from agents-cli). */
+export const REPO_URL = 'https://github.com/phnx-labs/agi-cli';
 /** Sentinel written the first (and only) time the nudge is shown. */
 function nudgeSentinelPath() {
     return path.join(getRuntimeStateDir(), 'star-nudge-shown');

package/dist/lib/state.d.ts

@@ -31,7 +31,7 @@ export declare function getHumansFilePath(): string;
  * file against `schema/agents-yaml.schema.json`. Exported so
  * `lib/devices/config-migration.ts` rewrites a device doc with the same header.
  */
-export declare const META_HEADER = "# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/cli/schema/agents-yaml.schema.json\n\n";
+export declare const META_HEADER = "# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agi-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agi-cli/main/cli/schema/agents-yaml.schema.json\n\n";
 /** Root of the system data directory (~/.agents/.system/). */
 export declare function getAgentsDir(): string;
 /** Root of the system data directory (~/.agents/.system/). */

package/dist/lib/state.js

@@ -167,8 +167,8 @@ const USER_PROMPTCUTS_FILE = path.join(USER_AGENTS_DIR, 'hooks', 'promptcuts.yam
  */
 export const META_HEADER = `# agents-cli metadata
 # Auto-generated - do not edit manually
-# https://github.com/phnx-labs/agents-cli
-# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/cli/schema/agents-yaml.schema.json
+# https://github.com/phnx-labs/agi-cli
+# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agi-cli/main/cli/schema/agents-yaml.schema.json
 
 `;
 // ─── Root getters ─────────────────────────────────────────────────────────────