@phnx-labs/agents-cli 1.22.49 → 1.22.51

package/dist/lib/installations/versions.js

@@ -34,7 +34,7 @@ import { discoverPermissionGroups, getActivePermissionPresetName, readPermission
 import { parseMcpConfigForScan, isProjectMcpTrusted } from '../mcp.js';
 import { createVersionedAlias, removeVersionedAlias, switchConfigSymlink, getConfigSymlinkVersion, ensureClaudeInsideSymlink, assertIsolationBoundary, isIsolationProtected, } from './shims.js';
 import { importInstallScriptBinary } from '../import.js';
-import { createInstallation, getBinaryPath, getCliVersionFromPath, getGlobalDefault, getIsolatedDefault, getLiveVersion, getVersionDir, getVersionHomePath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, isGlobalBinaryAgent, isVersionInstalled, isVersionIsolated, listInstalledVersions, pickCanonicalGlobalBinaryVersion, resolveVersion, } from './store.js';
+import { createInstallation, getBinaryPath, getCliVersionFromPath, getGlobalDefault, getIsolatedDefault, getLiveVersion, getVersionDir, getVersionHomePath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, isGlobalBinaryAgent, isVersionInstalled, isVersionIsolated, listInstalledVersions, pickCanonicalGlobalBinaryVersion, resolveGrokFallbackBinary, resolveVersion, } from './store.js';
 export * from './store.js';
 import { INSTALLATION_RECORD_FILE } from './types.js';
 import { composeWin32CommandLine } from '../platform/index.js';
@@ -1032,9 +1032,9 @@ export function setIsolatedDefault(agent, version) {
 /**
  * Move any `grok-<installedVersion>-...` binary (and its generic platform
  * copy) found directly under `sourceDownloads` into `targetDownloads`.
- * Returns true if the versioned binary was moved.
+ * Returns true if the versioned binary was transferred.
  */
-function tryMoveGrokDownloads(sourceDownloads, targetDownloads, installedVersion) {
+function transferGrokDownloads(sourceDownloads, targetDownloads, copy) {
     if (!fs.existsSync(sourceDownloads))
         return false;
     if (path.resolve(sourceDownloads) === path.resolve(targetDownloads))
@@ -1042,42 +1042,36 @@ function tryMoveGrokDownloads(sourceDownloads, targetDownloads, installedVersion
     const entries = fs.readdirSync(sourceDownloads).filter((e) => e.startsWith('grok-'));
     if (entries.length === 0)
         return false;
-    const escapedVersion = installedVersion.replace(/\./g, '\\.');
-    const versionedPattern = new RegExp(`^grok-${escapedVersion}-`);
-    const movedPaths = [];
-    // Move the versioned binary first — only create the target dir once we
-    // know there is something to move into it.
-    for (const entry of entries) {
-        if (!versionedPattern.test(entry))
-            continue;
-        const src = path.join(sourceDownloads, entry);
-        const dst = path.join(targetDownloads, entry);
-        if (fs.existsSync(dst))
-            continue;
-        try {
-            fs.mkdirSync(targetDownloads, { recursive: true });
-            fs.renameSync(src, dst);
-            movedPaths.push(dst);
-        }
-        catch {
-            /* ignore per-file failures */
-        }
+    const realBinary = resolveGrokFallbackBinary(sourceDownloads);
+    if (!realBinary)
+        return false;
+    const transferred = path.join(targetDownloads, path.basename(realBinary));
+    try {
+        fs.mkdirSync(targetDownloads, { recursive: true });
+        if (copy)
+            fs.copyFileSync(realBinary, transferred);
+        else
+            fs.renameSync(realBinary, transferred);
     }
-    if (movedPaths.length === 0)
+    catch {
         return false;
+    }
     // The installer also creates a generic platform binary (e.g. grok-macos-aarch64)
     // that is a copy of the versioned binary. Move it too if its size matches.
-    const movedSize = fs.statSync(movedPaths[0]).size;
+    const movedSize = fs.statSync(transferred).size;
     for (const entry of entries) {
-        if (versionedPattern.test(entry))
-            continue; // already handled
+        if (entry === path.basename(realBinary))
+            continue;
         const src = path.join(sourceDownloads, entry);
         const dst = path.join(targetDownloads, entry);
         if (fs.existsSync(dst))
             continue;
         try {
             if (fs.statSync(src).size === movedSize) {
-                fs.renameSync(src, dst);
+                if (copy)
+                    fs.copyFileSync(src, dst);
+                else
+                    fs.renameSync(src, dst);
             }
         }
         catch {
@@ -1099,7 +1093,7 @@ function tryMoveGrokDownloads(sourceDownloads, targetDownloads, installedVersion
  * whatever version was default at the time), sweep every other installed
  * grok version home for the missing file before giving up.
  */
-function relocateGrokBinaryToVersionHome(installedVersion) {
+function relocateGrokBinaryToVersionHome(installationLabel, copyExisting) {
     const hostGrokLink = path.join(getHomeDir(), agentConfigDirName('grok'));
     let sourceDownloads;
     try {
@@ -1108,16 +1102,16 @@ function relocateGrokBinaryToVersionHome(installedVersion) {
     catch {
         sourceDownloads = path.join(hostGrokLink, 'downloads');
     }
-    const targetDownloads = path.join(getVersionHomePath('grok', installedVersion), agentConfigDirName('grok'), 'downloads');
-    if (tryMoveGrokDownloads(sourceDownloads, targetDownloads, installedVersion))
+    const targetDownloads = path.join(getVersionHomePath('grok', installationLabel), agentConfigDirName('grok'), 'downloads');
+    if (transferGrokDownloads(sourceDownloads, targetDownloads, copyExisting))
         return;
     for (const version of listInstalledVersions('grok')) {
-        if (version === installedVersion)
+        if (version === installationLabel)
             continue;
         const candidate = path.join(getVersionHomePath('grok', version), agentConfigDirName('grok'), 'downloads');
         if (path.resolve(candidate) === path.resolve(sourceDownloads))
             continue; // already tried
-        if (tryMoveGrokDownloads(candidate, targetDownloads, installedVersion))
+        if (transferGrokDownloads(candidate, targetDownloads, copyExisting))
             return;
     }
 }
@@ -1158,6 +1152,7 @@ async function checkGrokAccountCollision(installedVersion) {
  */
 export async function installVersion(agent, version, onProgress, opts) {
     const agentConfig = AGENTS[agent];
+    const requestedLabel = version;
     if (isAgentHardDeprecated(agent)) {
         return { success: false, installedVersion: version, error: hardDeprecationError(agent) };
     }
@@ -1189,7 +1184,7 @@ export async function installVersion(agent, version, onProgress, opts) {
             }
             version = 'latest';
         }
-        let installedVersion = version;
+        let releaseVersion = version;
         try {
             if (runInstaller) {
                 const script = agentConfig.installScript.replaceAll('VERSION', version);
@@ -1218,13 +1213,19 @@ export async function installVersion(agent, version, onProgress, opts) {
                         error: `${agentConfig.name} installed but its version could not be determined after several attempts.`,
                     };
                 }
-                installedVersion = probed;
+                releaseVersion = probed;
                 // Fold any stale literal `latest` dir from an earlier probe-failed
                 // install into the real version so it stops shadowing `agents view`.
-                await reconcileStaleLatestDir(agent, installedVersion);
+                await reconcileStaleLatestDir(agent, releaseVersion);
             }
+            // Self-updating installers always fetch the current vendor release, but a
+            // concrete requested token is still the stable installation/account slot.
+            // Keeping the two strings separate lets several homes carry the same
+            // release without sharing credentials. `latest` remains the convenient
+            // release-named slot; concrete tokens remain exactly addressable.
+            const installationLabel = requestedLabel === 'latest' ? releaseVersion : requestedLabel;
             if (agent === 'grok') {
-                await checkGrokAccountCollision(installedVersion);
+                await checkGrokAccountCollision(installationLabel);
             }
             onProgress?.(`${agentConfig.name} installed. Setting up agents-cli version home for isolation...`);
         }
@@ -1233,14 +1234,15 @@ export async function installVersion(agent, version, onProgress, opts) {
             return { success: false, installedVersion: version, error: `${agentConfig.name} installer failed: ${err.message}` };
         }
         ensureAgentsDir();
-        const versionDir = getVersionDir(agent, installedVersion);
+        const installationLabel = requestedLabel === 'latest' ? releaseVersion : requestedLabel;
+        const versionDir = getVersionDir(agent, installationLabel);
         fs.mkdirSync(versionDir, { recursive: true });
         fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
         // Grok's installer drops the binary into ~/.grok/downloads, which currently
         // resolves to the PREVIOUS default home. Move it into the target version home
         // so version isolation is correct.
         if (agent === 'grok') {
-            relocateGrokBinaryToVersionHome(installedVersion);
+            relocateGrokBinaryToVersionHome(installationLabel, !runInstaller);
         }
         // Symlink the installed binary into the version's node_modules/.bin so
         // listInstalledVersions (which checks getBinaryPath) sees this version as
@@ -1265,26 +1267,26 @@ export async function installVersion(agent, version, onProgress, opts) {
             // that exec-loops forever).
             const installedBinary = findInPath(agentConfig.cliCommand);
             if (installedBinary) {
-                importInstallScriptBinary({ agentId: agent, npmPackage: agentConfig.npmPackage, cliCommand: agentConfig.cliCommand }, installedVersion, installedBinary, versionDir);
+                importInstallScriptBinary({ agentId: agent, npmPackage: agentConfig.npmPackage, cliCommand: agentConfig.cliCommand }, installationLabel, installedBinary, versionDir);
             }
             /* If null: binary missing from PATH (install script failed silently) or
                only our shim is present. Leave the version dir empty so getBinaryPath
                correctly reports it uninstalled. */
         }
-        createVersionedAlias(agent, installedVersion);
+        createVersionedAlias(agent, installationLabel);
         // Freeze this installation's identity. The dir name is its stable label from
         // here on; the release it carries is recorded separately so `agents update`
         // can move the release without invalidating any reference to the label.
-        createInstallation(agent, installedVersion, installedVersion);
-        const trackerInstall = await installSessionTrackerHook(agent, installedVersion);
+        createInstallation(agent, installationLabel, releaseVersion);
+        const trackerInstall = await installSessionTrackerHook(agent, installationLabel);
         if (!trackerInstall.installed && trackerInstall.error) {
-            console.warn(`agents: SessionStart hook not installed for ${agent}@${installedVersion}: ${trackerInstall.error}`);
+            console.warn(`agents: SessionStart hook not installed for ${agent}@${installationLabel}: ${trackerInstall.error}`);
         }
         // The self-updating binary just changed on disk — drop the cached
         // `--version` so `agents view` reflects the freshly-installed release.
         invalidateLiveVersionCache(agent);
-        emit('version.install', { agent, version: installedVersion });
-        return { success: true, installedVersion };
+        emit('version.install', { agent, version: installationLabel });
+        return { success: true, installedVersion: installationLabel };
     }
     // Resolve the `latest`/`oldest` aliases to a concrete npm version up front so
     // the rest of the install path treats them as an ordinary pinned install.

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,