@phnx-labs/agents-cli 1.20.21 → 1.20.23

package/dist/lib/menubar/MenubarHelper.app/Contents/_CodeSignature/CodeResources

@@ -0,0 +1,115 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>files</key>
+	<dict/>
+	<key>files2</key>
+	<dict/>
+	<key>rules</key>
+	<dict>
+		<key>^Resources/</key>
+		<true/>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^version.plist$</key>
+		<true/>
+	</dict>
+	<key>rules2</key>
+	<dict>
+		<key>.*\.dSYM($|/)</key>
+		<dict>
+			<key>weight</key>
+			<real>11</real>
+		</dict>
+		<key>^(.*/)?\.DS_Store$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>2000</real>
+		</dict>
+		<key>^(Frameworks|SharedFrameworks|PlugIns|Plug-ins|XPCServices|Helpers|MacOS|Library/(Automator|Spotlight|LoginItems))/</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^.*</key>
+		<true/>
+		<key>^Info\.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^PkgInfo$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^[^/]+$</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^embedded\.provisionprofile$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^version\.plist$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+	</dict>
+</dict>
+</plist>

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

@@ -0,0 +1,57 @@
+/**
+ * Install + lifecycle for the macOS menu-bar helper (`MenubarHelper.app`).
+ *
+ * Mirrors `src/lib/secrets/install-helper.ts` (stable Application Support path,
+ * survives npm re-sign) and the secrets-agent launchd pattern in
+ * `src/lib/secrets/agent.ts` (RunAtLoad + KeepAlive user service).
+ *
+ * The helper is a no-Dock `.accessory` status-bar app. It reads live agent
+ * state directly from disk and shells `agents` only for actions, so the plist
+ * bakes in the node interpreter + entry point + bin path so the GUI process can
+ * find the CLI without a login PATH.
+ *
+ * Opt-out is sticky: `agents menubar disable` drops a sentinel that the upgrade
+ * migration (`installMenubarLaunchAgent` in migrate.ts) honors, so a disabled
+ * menu bar never silently comes back on the next release.
+ */
+/** True if the user explicitly disabled the menu bar (don't auto-enable on upgrade). */
+export declare function menubarDisabledByUser(): boolean;
+/** True if the launchd plist for the menu-bar service is installed. */
+export declare function menubarServiceInstalled(): boolean;
+/**
+ * Copy the bundled `.app` to the stable user path (idempotent unless forced).
+ * Returns the installed executable path, or null if no source bundle ships
+ * with this install (e.g. Linux package, or a build without the helper).
+ */
+export declare function ensureMenubarAppInstalled(opts?: {
+    forceReinstall?: boolean;
+}): string | null;
+/**
+ * Install + start the menu-bar helper as a launchd user service (idempotent).
+ * Clears the sticky opt-out, installs the .app, writes the plist, and
+ * bootstraps it into the GUI domain. Returns false on non-darwin or when no
+ * helper bundle ships with this install.
+ */
+export declare function enableMenubarService(opts?: {
+    clearOptOut?: boolean;
+}): boolean;
+/**
+ * Stop + remove the menu-bar service and write the sticky opt-out so the
+ * upgrade migration won't re-enable it.
+ */
+export declare function disableMenubarService(): void;
+/**
+ * Upgrade-time auto-enable. Runs from runMigration() once per sentinel bump.
+ * No-ops if: not darwin, the user opted out, no helper bundle ships, or the
+ * service is already installed. Best-effort — never throws into migration.
+ */
+export declare function installMenubarLaunchAgentOnUpgrade(): void;
+export interface MenubarStatus {
+    platform: string;
+    source: string | null;
+    installedApp: string | null;
+    serviceInstalled: boolean;
+    running: boolean;
+    disabledByUser: boolean;
+}
+export declare function getMenubarStatus(): MenubarStatus;

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

@@ -0,0 +1,291 @@
+/**
+ * Install + lifecycle for the macOS menu-bar helper (`MenubarHelper.app`).
+ *
+ * Mirrors `src/lib/secrets/install-helper.ts` (stable Application Support path,
+ * survives npm re-sign) and the secrets-agent launchd pattern in
+ * `src/lib/secrets/agent.ts` (RunAtLoad + KeepAlive user service).
+ *
+ * The helper is a no-Dock `.accessory` status-bar app. It reads live agent
+ * state directly from disk and shells `agents` only for actions, so the plist
+ * bakes in the node interpreter + entry point + bin path so the GUI process can
+ * find the CLI without a login PATH.
+ *
+ * Opt-out is sticky: `agents menubar disable` drops a sentinel that the upgrade
+ * migration (`installMenubarLaunchAgent` in migrate.ts) honors, so a disabled
+ * menu bar never silently comes back on the next release.
+ */
+import { fileURLToPath } from 'url';
+import { execFileSync, spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { getRuntimeStateDir, getHelpersDir } from '../state.js';
+const APP_BUNDLE_NAME = 'MenubarHelper.app';
+const INSTALL_DIR_NAME = 'agents-cli';
+const SERVICE_LABEL = 'com.phnx-labs.agents-menubar';
+function onDarwin() {
+    return process.platform === 'darwin';
+}
+/** ~/Library/Application Support/agents-cli/MenubarHelper.app */
+function installedAppPath() {
+    return path.join(os.homedir(), 'Library', 'Application Support', INSTALL_DIR_NAME, APP_BUNDLE_NAME);
+}
+/** Executable inside the installed bundle. */
+function installedExecutablePath() {
+    return path.join(installedAppPath(), 'Contents', 'MacOS', 'MenubarHelper');
+}
+/** ~/Library/LaunchAgents/com.phnx-labs.agents-menubar.plist */
+function servicePlistPath() {
+    return path.join(os.homedir(), 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
+}
+/** Sticky opt-out marker written by `agents menubar disable`. */
+function disabledSentinelPath() {
+    return path.join(getRuntimeStateDir(), 'menubar.disabled');
+}
+/** True if the user explicitly disabled the menu bar (don't auto-enable on upgrade). */
+export function menubarDisabledByUser() {
+    return fs.existsSync(disabledSentinelPath());
+}
+/** True if the launchd plist for the menu-bar service is installed. */
+export function menubarServiceInstalled() {
+    return onDarwin() && fs.existsSync(servicePlistPath());
+}
+/**
+ * Locate the source `.app` shipped alongside the compiled JS.
+ *   1. dist/lib/menubar/MenubarHelper.app — npm install layout (sibling of this file)
+ *   2. <repo>/bin/MenubarHelper.app       — raw working tree (tsx/dev)
+ *   3. <repo>/packages/menubar-helper/dist/MenubarHelper.app — fresh local build
+ */
+function sourceAppPath() {
+    const candidates = [];
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        candidates.push(path.join(here, APP_BUNDLE_NAME));
+        candidates.push(path.resolve(here, '..', '..', '..', 'bin', APP_BUNDLE_NAME));
+        candidates.push(path.resolve(here, '..', '..', '..', 'packages', 'menubar-helper', 'dist', APP_BUNDLE_NAME));
+    }
+    catch {
+        /* import.meta.url unavailable */
+    }
+    for (const c of candidates) {
+        if (fs.existsSync(c))
+            return c;
+    }
+    return null;
+}
+/** Resolve the `agents` launcher binary on PATH-less GUI processes. */
+function resolveAgentsBin() {
+    const home = os.homedir();
+    const candidates = [
+        path.join(home, '.local', 'bin', 'agents'),
+        '/opt/homebrew/bin/agents',
+        '/usr/local/bin/agents',
+        path.join(home, '.npm-global', 'bin', 'agents'),
+    ];
+    for (const c of candidates) {
+        try {
+            fs.accessSync(c, fs.constants.X_OK);
+            return c;
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return null;
+}
+/** Resolve the compiled CLI entry (dist/index.js) so the helper can exec node directly. */
+function resolveCliEntry() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        // dist/lib/menubar/install-menubar.js -> dist/index.js
+        const entry = path.resolve(here, '..', '..', 'index.js');
+        if (fs.existsSync(entry))
+            return entry;
+    }
+    catch {
+        /* ignore */
+    }
+    return null;
+}
+function copyAppBundle(src, dest) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    if (fs.existsSync(dest))
+        fs.rmSync(dest, { recursive: true, force: true });
+    // `cp -R` preserves the bundle's signature and resource forks (see install-helper.ts).
+    const r = spawnSync('cp', ['-R', src, dest], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+    if (r.status !== 0) {
+        const msg = (r.stderr || r.stdout || '').toString().trim();
+        throw new Error(`Failed to copy ${src} -> ${dest}: ${msg || 'unknown error'}`);
+    }
+}
+/**
+ * Copy the bundled `.app` to the stable user path (idempotent unless forced).
+ * Returns the installed executable path, or null if no source bundle ships
+ * with this install (e.g. Linux package, or a build without the helper).
+ */
+export function ensureMenubarAppInstalled(opts = {}) {
+    if (!onDarwin())
+        return null;
+    const src = sourceAppPath();
+    if (!src)
+        return null;
+    const dest = installedAppPath();
+    if (!opts.forceReinstall && fs.existsSync(dest))
+        return installedExecutablePath();
+    copyAppBundle(src, dest);
+    return installedExecutablePath();
+}
+function xmlEscape(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function generateServicePlist(execPath) {
+    const home = os.homedir();
+    const logPath = path.join(getHelpersDir(), 'menubar', 'menubar.log');
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    // Bake interpreter + entry + bin so the GUI helper can reach the CLI with no
+    // login PATH. AgentsCLI.swift prefers [AGENTS_NODE, AGENTS_ENTRY] when both
+    // exist, else falls back to AGENTS_BIN, else probes well-known paths.
+    const env = {
+        PATH: `/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${path.dirname(process.execPath)}:${home}/.local/bin`,
+    };
+    const node = process.execPath;
+    const entry = resolveCliEntry();
+    const bin = resolveAgentsBin();
+    if (node && entry) {
+        env.AGENTS_NODE = node;
+        env.AGENTS_ENTRY = entry;
+    }
+    if (bin)
+        env.AGENTS_BIN = bin;
+    const envXml = Object.entries(env)
+        .map(([k, v]) => `    <key>${xmlEscape(k)}</key>\n    <string>${xmlEscape(v)}</string>`)
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(execPath)}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Interactive</string>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(logPath)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envXml}
+  </dict>
+</dict>
+</plist>`;
+}
+/**
+ * Install + start the menu-bar helper as a launchd user service (idempotent).
+ * Clears the sticky opt-out, installs the .app, writes the plist, and
+ * bootstraps it into the GUI domain. Returns false on non-darwin or when no
+ * helper bundle ships with this install.
+ */
+export function enableMenubarService(opts = { clearOptOut: true }) {
+    if (!onDarwin())
+        return false;
+    const exec = ensureMenubarAppInstalled({ forceReinstall: true });
+    if (!exec)
+        return false;
+    if (opts.clearOptOut) {
+        try {
+            fs.rmSync(disabledSentinelPath(), { force: true });
+        }
+        catch { /* already gone */ }
+    }
+    const plist = servicePlistPath();
+    fs.mkdirSync(path.dirname(plist), { recursive: true });
+    fs.writeFileSync(plist, generateServicePlist(exec));
+    const uid = process.getuid?.() ?? 0;
+    try {
+        execFileSync('launchctl', ['bootstrap', `gui/${uid}`, plist], { stdio: ['ignore', 'ignore', 'ignore'] });
+    }
+    catch {
+        try {
+            execFileSync('launchctl', ['load', '-w', plist], { stdio: ['ignore', 'ignore', 'ignore'] });
+        }
+        catch { /* may already be loaded */ }
+    }
+    try {
+        execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+    }
+    catch { /* best effort */ }
+    return true;
+}
+/**
+ * Stop + remove the menu-bar service and write the sticky opt-out so the
+ * upgrade migration won't re-enable it.
+ */
+export function disableMenubarService() {
+    if (!onDarwin())
+        return;
+    const plist = servicePlistPath();
+    const uid = process.getuid?.() ?? 0;
+    try {
+        execFileSync('launchctl', ['bootout', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+    }
+    catch {
+        try {
+            execFileSync('launchctl', ['unload', '-w', plist], { stdio: ['ignore', 'ignore', 'ignore'] });
+        }
+        catch { /* not loaded */ }
+    }
+    try {
+        fs.unlinkSync(plist);
+    }
+    catch { /* already gone */ }
+    try {
+        fs.mkdirSync(path.dirname(disabledSentinelPath()), { recursive: true });
+        fs.writeFileSync(disabledSentinelPath(), `disabled ${new Date().toISOString()}\n`);
+    }
+    catch { /* best effort */ }
+}
+/**
+ * Upgrade-time auto-enable. Runs from runMigration() once per sentinel bump.
+ * No-ops if: not darwin, the user opted out, no helper bundle ships, or the
+ * service is already installed. Best-effort — never throws into migration.
+ */
+export function installMenubarLaunchAgentOnUpgrade() {
+    try {
+        if (!onDarwin())
+            return;
+        if (menubarDisabledByUser())
+            return;
+        if (menubarServiceInstalled())
+            return;
+        if (!sourceAppPath())
+            return;
+        enableMenubarService({ clearOptOut: false });
+    }
+    catch {
+        /* never block migration on the menu bar */
+    }
+}
+export function getMenubarStatus() {
+    const dest = installedAppPath();
+    let running = false;
+    if (onDarwin()) {
+        const r = spawnSync('pgrep', ['-f', 'MenubarHelper'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
+        running = r.status === 0 && (r.stdout || '').trim().length > 0;
+    }
+    return {
+        platform: process.platform,
+        source: sourceAppPath(),
+        installedApp: fs.existsSync(dest) ? dest : null,
+        serviceInstalled: menubarServiceInstalled(),
+        running,
+        disabledByUser: menubarDisabledByUser(),
+    };
+}

package/dist/lib/secrets/agent.d.ts

@@ -46,6 +46,13 @@ export declare function secretsAgentServiceInstalled(): boolean;
  * so it can boot even when the machine is loaded. Returns true once reachable.
  */
 export declare function installSecretsAgentService(timeoutMs?: number): Promise<boolean>;
+/**
+ * Kickstart the already-installed persistent broker so launchd relaunches it
+ * onto the current on-disk code. Used by postinstall heal-on-upgrade. No-op if
+ * the service isn't installed; never rewrites the plist or waits, so it's safe
+ * and fast to call from an installer.
+ */
+export declare function kickstartSecretsAgentService(): void;
 /** Stop + remove the persistent broker service, and wipe whatever it held. */
 export declare function uninstallSecretsAgentService(): Promise<void>;
 export type Request = {
@@ -69,6 +76,7 @@ export type Response = {
     ok: true;
     cmd: 'ping';
     version: number;
+    cliVersion: string;
 } | {
     ok: true;
     cmd: 'get';
@@ -127,7 +135,7 @@ export declare function secretsAgentAutoEnabled(): boolean;
 /**
  * Fire-and-forget: populate the broker with a freshly-resolved bundle so the
  * NEXT process reads it without a prompt. Used by the auto-cache path after a
- * real keychain read of a `session`-tier bundle. Adds no latency to the caller
+ * real keychain read of a `daily`-policy bundle. Adds no latency to the caller
  * — it spawns a detached `secrets _agent-load` worker (passing the resolved env
  * over stdin, never argv) and returns immediately.
  *

package/dist/lib/secrets/agent.js

@@ -30,6 +30,7 @@ import { spawn, spawnSync, execFileSync } from 'child_process';
 import { getHelpersDir, readMeta } from '../state.js';
 import { isAlive } from '../platform/process.js';
 import { getKeychainHelperPath } from './install-helper.js';
+import { getCliVersion, getCliVersionFresh } from '../version.js';
 /** Bumped when the wire protocol changes; a client that pings a mismatched
  * server kills and respawns it rather than talking a stale dialect. */
 const PROTOCOL_VERSION = 1;
@@ -164,12 +165,27 @@ export async function installSecretsAgentService(timeoutMs = 30000) {
     catch { /* best effort */ }
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        if (await agentPing())
+        if ((await agentPing()).reachable)
             return true;
         await new Promise((r) => setTimeout(r, 200));
     }
     return false;
 }
+/**
+ * Kickstart the already-installed persistent broker so launchd relaunches it
+ * onto the current on-disk code. Used by postinstall heal-on-upgrade. No-op if
+ * the service isn't installed; never rewrites the plist or waits, so it's safe
+ * and fast to call from an installer.
+ */
+export function kickstartSecretsAgentService() {
+    if (!onDarwin() || !secretsAgentServiceInstalled())
+        return;
+    const uid = process.getuid?.() ?? 0;
+    try {
+        execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+    }
+    catch { /* best effort */ }
+}
 /** Stop + remove the persistent broker service, and wipe whatever it held. */
 export async function uninstallSecretsAgentService() {
     if (!onDarwin())
@@ -201,7 +217,11 @@ export async function uninstallSecretsAgentService() {
 export function handleAgentRequest(store, req, now = Date.now()) {
     switch (req.cmd) {
         case 'ping':
-            return { ok: true, cmd: 'ping', version: PROTOCOL_VERSION };
+            // Report the version of the code this broker is RUNNING (getCliVersion
+            // caches the value from the broker's startup), not the on-disk version.
+            // A client compares this to its own fresh on-disk read; a mismatch means
+            // the broker is running pre-upgrade code and should be restarted.
+            return { ok: true, cmd: 'ping', version: PROTOCOL_VERSION, cliVersion: getCliVersion() };
         case 'get': {
             const e = store.get(req.name);
             if (!e || now >= e.expiresAt) {
@@ -278,11 +298,25 @@ export async function runSecretsAgent(opts = {}) {
         fs.unlinkSync(sock);
     }
     catch { /* no stale socket */ }
+    // Capture the version of the code we're running so the sweep can detect when
+    // an in-place upgrade has landed and self-heal onto it. getCliVersion caches
+    // this value for the process lifetime; getCliVersionFresh re-reads on disk.
+    const runningVersion = getCliVersion();
     const sweep = () => {
         const now = Date.now();
         for (const [name, e] of store)
             if (now >= e.expiresAt)
                 store.delete(name);
+        // Self-heal: a newer version was installed in place — exit so launchd
+        // relaunches us on the new code. Only meaningful when launchd will restart
+        // us (persistent); a one-off broker just keeps serving until idle.
+        if (persistent) {
+            const onDisk = getCliVersionFresh();
+            if (onDisk !== 'unknown' && runningVersion !== 'unknown' && onDisk !== runningVersion) {
+                shutdown(0); // KeepAlive relaunches on the new code
+                return;
+            }
+        }
         if (store.size === 0) {
             if (!persistent && now - emptySince >= IDLE_EXIT_MS)
                 shutdown(0);
@@ -489,7 +523,7 @@ export function secretsAgentAutoEnabled() {
 /**
  * Fire-and-forget: populate the broker with a freshly-resolved bundle so the
  * NEXT process reads it without a prompt. Used by the auto-cache path after a
- * real keychain read of a `session`-tier bundle. Adds no latency to the caller
+ * real keychain read of a `daily`-policy bundle. Adds no latency to the caller
  * — it spawns a detached `secrets _agent-load` worker (passing the resolved env
  * over stdin, never argv) and returns immediately.
  *
@@ -556,12 +590,16 @@ export async function agentStatus() {
     const r = await request({ cmd: 'status' });
     return r?.ok === true && r.cmd === 'status' ? r.entries : [];
 }
-/** Is a broker live and speaking our protocol version? */
+/** Ping result: whether a broker is reachable + speaking our protocol, and the
+ * version of the code it's running (for staleness detection). */
 async function agentPing() {
     if (!agentSocketExists())
-        return false;
+        return { reachable: false };
     const r = await request({ cmd: 'ping' });
-    return r?.ok === true && r.cmd === 'ping' && r.version === PROTOCOL_VERSION;
+    if (r?.ok === true && r.cmd === 'ping' && r.version === PROTOCOL_VERSION) {
+        return { reachable: true, cliVersion: r.cliVersion };
+    }
+    return { reachable: false };
 }
 /**
  * Ensure a broker is running and reachable. Returns true once the socket answers
@@ -576,8 +614,16 @@ async function agentPing() {
 export async function ensureAgentRunning(timeoutMs = 5000) {
     if (!onDarwin())
         return false;
-    if (await agentPing())
-        return true;
+    // Self-heal: if a broker is reachable but running pre-upgrade code (its
+    // reported version != the version on disk now), tear it down so the paths
+    // below bring up a fresh one on current code. A current, reachable broker is
+    // accepted immediately.
+    const ping = await agentPing();
+    if (ping.reachable) {
+        if (ping.cliVersion === undefined || ping.cliVersion === getCliVersionFresh())
+            return true;
+        await teardownStaleBroker();
+    }
     // Path 1: the persistent service. installSecretsAgentService is idempotent and
     // waits for the socket; for an already-installed service we kickstart and wait.
     try {
@@ -593,7 +639,7 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
             catch { /* may already be running */ }
             const d = Date.now() + timeoutMs;
             while (Date.now() < d) {
-                if (await agentPing())
+                if ((await agentPing()).reachable)
                     return true;
                 await new Promise((r) => setTimeout(r, 150));
             }
@@ -627,9 +673,44 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
     spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        if (await agentPing())
+        if ((await agentPing()).reachable)
             return true;
         await new Promise((r) => setTimeout(r, 100));
     }
     return false;
 }
+/**
+ * Tear down a stale broker (running pre-upgrade code) so a fresh one can take
+ * over. If the persistent service is installed, bootout makes launchd relaunch
+ * it on the new code; otherwise kill the process and clear its socket/pid.
+ */
+async function teardownStaleBroker() {
+    if (secretsAgentServiceInstalled()) {
+        const uid = process.getuid?.() ?? 0;
+        try {
+            execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+        }
+        catch { /* best effort */ }
+        return; // kickstart -k restarts the service onto current code; socket/pid managed by it
+    }
+    const pid = (() => { try {
+        return parseInt(fs.readFileSync(pidPath(), 'utf-8').trim(), 10);
+    }
+    catch {
+        return NaN;
+    } })();
+    if (!isNaN(pid) && isAlive(pid)) {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch { /* gone */ }
+    }
+    try {
+        fs.unlinkSync(socketPath());
+    }
+    catch { /* gone */ }
+    try {
+        fs.unlinkSync(pidPath());
+    }
+    catch { /* gone */ }
+}