@agenticmail/core 0.5.56 → 0.5.59

package/dist/index.cjs

@@ -1238,7 +1238,8 @@ var InboxWatcher = class extends import_node_events.EventEmitter {
         this.emit("close");
         this._scheduleReconnect();
       });
-      this._lock = lock;
+      lock.release();
+      this._lock = null;
     } catch (err) {
       lock.release();
       throw err;
@@ -1917,7 +1918,15 @@ var AccountManager = class {
     }
     const principalName = options.name.toLowerCase();
     const email = `${principalName}@${domain}`;
+    const existingAgent = await this.getByName(options.name);
+    if (existingAgent != null) {
+      throw new Error(`Account already exists: ${options.name}`);
+    }
     await this.stalwart.ensureDomain(domain);
+    try {
+      await this.stalwart.deletePrincipal(principalName);
+    } catch {
+    }
     await this.stalwart.createPrincipal({
       type: "individual",
       name: principalName,
@@ -7068,6 +7077,8 @@ var import_node_child_process4 = require("child_process");
 var import_node_fs6 = require("fs");
 var import_node_path7 = require("path");
 var import_node_os6 = require("os");
+var import_node_module = require("module");
+var import_meta = {};
 var PLIST_LABEL = "com.agenticmail.server";
 var SYSTEMD_UNIT = "agenticmail.service";
 var ServiceManager = class {
@@ -7094,42 +7105,59 @@ var ServiceManager = class {
   }
   /**
    * Find the API server entry point.
-   * Searches common locations where agenticmail is installed.
+   *
+   * Issue #26 — Robust path resolution.
+   *
+   * The original implementation hard-coded `node_modules/agenticmail` (the
+   * old unscoped package name). After the rename to `@agenticmail/cli`, that
+   * directory no longer exists, so the resolver fell back to the stale
+   * `~/.agenticmail/api-entry.path` cache and the launchd plist kept pointing
+   * at a deleted path — causing the boot crash loop reported in #26.
+   *
+   * We now prefer `require.resolve('@agenticmail/api')` so the resolution
+   * follows the actual installed location regardless of npm prefix, the
+   * scoped vs unscoped package name, or the package manager (npm global,
+   * pnpm, yarn global, local node_modules). Cached paths are always
+   * validated against the filesystem before being returned.
    */
   getApiEntryPath() {
-    const searchDirs = [
-      // Global npm install
-      (0, import_node_path7.join)((0, import_node_os6.homedir)(), "node_modules", "agenticmail"),
-      // npx cache / global prefix
-      ...(() => {
-        try {
-          const prefix = (0, import_node_child_process4.execSync)("npm prefix -g", { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
-          return [
-            (0, import_node_path7.join)(prefix, "lib", "node_modules", "agenticmail"),
-            (0, import_node_path7.join)(prefix, "node_modules", "agenticmail")
-          ];
-        } catch {
-          return [];
-        }
-      })(),
-      // Homebrew on macOS
-      "/opt/homebrew/lib/node_modules/agenticmail",
-      "/usr/local/lib/node_modules/agenticmail"
+    try {
+      const req = (0, import_node_module.createRequire)(import_meta.url);
+      const resolved = req.resolve("@agenticmail/api");
+      if ((0, import_node_fs6.existsSync)(resolved)) return resolved;
+    } catch {
+    }
+    const parentPackages = [
+      (0, import_node_path7.join)("@agenticmail", "cli"),
+      // current scoped package
+      "agenticmail"
+      // legacy unscoped package
     ];
-    for (const base of searchDirs) {
-      const apiPaths = [
-        (0, import_node_path7.join)(base, "node_modules", "@agenticmail", "api", "dist", "index.js"),
-        (0, import_node_path7.join)(base, "..", "@agenticmail", "api", "dist", "index.js")
-      ];
-      for (const p of apiPaths) {
-        if ((0, import_node_fs6.existsSync)(p)) return p;
+    const baseDirs = [
+      // user-local install
+      (0, import_node_path7.join)((0, import_node_os6.homedir)(), "node_modules")
+    ];
+    try {
+      const prefix = (0, import_node_child_process4.execSync)("npm prefix -g", { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+      baseDirs.push((0, import_node_path7.join)(prefix, "lib", "node_modules"));
+      baseDirs.push((0, import_node_path7.join)(prefix, "node_modules"));
+    } catch {
+    }
+    baseDirs.push("/opt/homebrew/lib/node_modules");
+    baseDirs.push("/usr/local/lib/node_modules");
+    for (const base of baseDirs) {
+      const sibling = (0, import_node_path7.join)(base, "@agenticmail", "api", "dist", "index.js");
+      if ((0, import_node_fs6.existsSync)(sibling)) return sibling;
+      for (const parent of parentPackages) {
+        const nested = (0, import_node_path7.join)(base, parent, "node_modules", "@agenticmail", "api", "dist", "index.js");
+        if ((0, import_node_fs6.existsSync)(nested)) return nested;
       }
     }
     const dataDir = (0, import_node_path7.join)((0, import_node_os6.homedir)(), ".agenticmail");
     const entryCache = (0, import_node_path7.join)(dataDir, "api-entry.path");
     if ((0, import_node_fs6.existsSync)(entryCache)) {
       const cached = (0, import_node_fs6.readFileSync)(entryCache, "utf-8").trim();
-      if ((0, import_node_fs6.existsSync)(cached)) return cached;
+      if (cached && (0, import_node_fs6.existsSync)(cached)) return cached;
     }
     throw new Error("Could not find @agenticmail/api entry point. Run `agenticmail start` first to populate the cache.");
   }
@@ -7143,25 +7171,49 @@ var ServiceManager = class {
   }
   /**
    * Get the current package version.
+   *
+   * Issue #26 — resolve the CLI package.json via require.resolve so the
+   * version reflects the *currently installed* @agenticmail/cli, not a
+   * leftover unscoped `agenticmail` package directory.
    */
   getVersion() {
     try {
-      const pkgPaths = [
-        (0, import_node_path7.join)((0, import_node_os6.homedir)(), "node_modules", "agenticmail", "package.json"),
-        (0, import_node_path7.join)((0, import_node_os6.homedir)(), ".agenticmail", "package-version.json")
-      ];
-      try {
-        const prefix = (0, import_node_child_process4.execSync)("npm prefix -g", { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
-        pkgPaths.push((0, import_node_path7.join)(prefix, "lib", "node_modules", "agenticmail", "package.json"));
-      } catch {
+      const req = (0, import_node_module.createRequire)(import_meta.url);
+      const pkgJson = req.resolve("@agenticmail/cli/package.json");
+      if ((0, import_node_fs6.existsSync)(pkgJson)) {
+        const pkg = JSON.parse((0, import_node_fs6.readFileSync)(pkgJson, "utf-8"));
+        if (pkg.version) return pkg.version;
       }
-      for (const p of pkgPaths) {
+    } catch {
+    }
+    try {
+      const apiEntry = this.getApiEntryPath();
+      const apiPkg = (0, import_node_path7.join)(apiEntry, "..", "..", "package.json");
+      if ((0, import_node_fs6.existsSync)(apiPkg)) {
+        const pkg = JSON.parse((0, import_node_fs6.readFileSync)(apiPkg, "utf-8"));
+        if (pkg.version) return pkg.version;
+      }
+    } catch {
+    }
+    const candidates = [
+      (0, import_node_path7.join)((0, import_node_os6.homedir)(), "node_modules", "@agenticmail", "cli", "package.json"),
+      (0, import_node_path7.join)((0, import_node_os6.homedir)(), "node_modules", "agenticmail", "package.json"),
+      (0, import_node_path7.join)((0, import_node_os6.homedir)(), ".agenticmail", "package-version.json")
+    ];
+    try {
+      const prefix = (0, import_node_child_process4.execSync)("npm prefix -g", { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+      candidates.push((0, import_node_path7.join)(prefix, "lib", "node_modules", "@agenticmail", "cli", "package.json"));
+      candidates.push((0, import_node_path7.join)(prefix, "lib", "node_modules", "agenticmail", "package.json"));
+    } catch {
+    }
+    for (const p of candidates) {
+      try {
         if ((0, import_node_fs6.existsSync)(p)) {
           const pkg = JSON.parse((0, import_node_fs6.readFileSync)(p, "utf-8"));
           if (pkg.version) return pkg.version;
         }
+      } catch {
       }
-    } catch {
     }
     return "unknown";
   }
@@ -7467,6 +7519,86 @@ WantedBy=default.target
     this.uninstall();
     return this.install();
   }
+  /**
+   * Issue #26 — Detect a stale service installation.
+   *
+   * Background: when a user upgrades from the old unscoped `agenticmail`
+   * package to the new `@agenticmail/cli` scoped package, the old
+   * ~/Library/LaunchAgents/com.agenticmail.server.plist and
+   * ~/.agenticmail/bin/start-server.sh files keep pointing at
+   * /opt/homebrew/lib/node_modules/agenticmail/... — a path that no longer
+   * exists post-rename. The result is a launchd crash loop.
+   *
+   * `needsRepair()` returns a non-null reason whenever:
+   *  - the service file exists but the start-server.sh it launches is
+   *    missing or references a node_modules path that no longer resolves;
+   *  - the embedded service version drifts from the running CLI version
+   *    (so service files get refreshed on every upgrade — including
+   *    in-place version bumps that don't change the install path);
+   *  - the cached API entry path no longer exists on disk.
+   *
+   * Returns null when everything checks out — callers should treat that as
+   * "no action needed".
+   *
+   * Platform-aware: only inspects launchd artefacts on darwin and systemd
+   * artefacts on linux. Returns null on unsupported platforms so this can
+   * be called unconditionally from the CLI's start path.
+   */
+  needsRepair() {
+    if (this.os !== "darwin" && this.os !== "linux") return null;
+    const servicePath = this.getServicePath();
+    if (!(0, import_node_fs6.existsSync)(servicePath)) return null;
+    let serviceContent = "";
+    try {
+      serviceContent = (0, import_node_fs6.readFileSync)(servicePath, "utf-8");
+    } catch {
+      return { reason: "Service file unreadable" };
+    }
+    const startScript = (0, import_node_path7.join)((0, import_node_os6.homedir)(), ".agenticmail", "bin", "start-server.sh");
+    if (serviceContent.includes(startScript)) {
+      if (!(0, import_node_fs6.existsSync)(startScript)) {
+        return { reason: "start-server.sh is missing" };
+      }
+      let scriptContent = "";
+      try {
+        scriptContent = (0, import_node_fs6.readFileSync)(startScript, "utf-8");
+      } catch {
+        return { reason: "start-server.sh unreadable" };
+      }
+      const apiPathMatch = scriptContent.match(/(\/[^"\s]+@agenticmail\/api\/dist\/index\.js)/);
+      if (apiPathMatch) {
+        const referenced = apiPathMatch[1];
+        if (!(0, import_node_fs6.existsSync)(referenced)) {
+          return { reason: `start-server.sh references missing path: ${referenced}` };
+        }
+      }
+      if (/node_modules\/agenticmail\/(?!.*@agenticmail\/cli)/.test(scriptContent)) {
+        const stale = /(\S*node_modules\/agenticmail\/\S*)/.exec(scriptContent)?.[1];
+        if (stale && !(0, import_node_fs6.existsSync)(stale)) {
+          return { reason: `start-server.sh references legacy unscoped path: ${stale}` };
+        }
+      }
+    } else {
+      return { reason: "Service file does not reference the wrapper script" };
+    }
+    const currentVersion = this.getVersion();
+    if (currentVersion !== "unknown") {
+      if (!serviceContent.includes(`v${currentVersion}`) || !serviceContent.includes(`AGENTICMAIL_SERVICE_VERSION`) || !serviceContent.includes(currentVersion)) {
+        return { reason: `Service version drift (current CLI is v${currentVersion})` };
+      }
+    }
+    const entryCache = (0, import_node_path7.join)((0, import_node_os6.homedir)(), ".agenticmail", "api-entry.path");
+    if ((0, import_node_fs6.existsSync)(entryCache)) {
+      try {
+        const cached = (0, import_node_fs6.readFileSync)(entryCache, "utf-8").trim();
+        if (cached && !(0, import_node_fs6.existsSync)(cached)) {
+          return { reason: `Cached API entry path no longer exists: ${cached}` };
+        }
+      } catch {
+      }
+    }
+    return null;
+  }
 };
 
 // src/setup/index.ts

package/dist/index.d.cts

@@ -1558,7 +1558,20 @@ declare class ServiceManager {
     private getNodePath;
     /**
      * Find the API server entry point.
-     * Searches common locations where agenticmail is installed.
+     *
+     * Issue #26 — Robust path resolution.
+     *
+     * The original implementation hard-coded `node_modules/agenticmail` (the
+     * old unscoped package name). After the rename to `@agenticmail/cli`, that
+     * directory no longer exists, so the resolver fell back to the stale
+     * `~/.agenticmail/api-entry.path` cache and the launchd plist kept pointing
+     * at a deleted path — causing the boot crash loop reported in #26.
+     *
+     * We now prefer `require.resolve('@agenticmail/api')` so the resolution
+     * follows the actual installed location regardless of npm prefix, the
+     * scoped vs unscoped package name, or the package manager (npm global,
+     * pnpm, yarn global, local node_modules). Cached paths are always
+     * validated against the filesystem before being returned.
      */
     private getApiEntryPath;
     /**
@@ -1567,6 +1580,10 @@ declare class ServiceManager {
     cacheApiEntryPath(entryPath: string): void;
     /**
      * Get the current package version.
+     *
+     * Issue #26 — resolve the CLI package.json via require.resolve so the
+     * version reflects the *currently installed* @agenticmail/cli, not a
+     * leftover unscoped `agenticmail` package directory.
      */
     private getVersion;
     /**
@@ -1619,6 +1636,34 @@ declare class ServiceManager {
         installed: boolean;
         message: string;
     };
+    /**
+     * Issue #26 — Detect a stale service installation.
+     *
+     * Background: when a user upgrades from the old unscoped `agenticmail`
+     * package to the new `@agenticmail/cli` scoped package, the old
+     * ~/Library/LaunchAgents/com.agenticmail.server.plist and
+     * ~/.agenticmail/bin/start-server.sh files keep pointing at
+     * /opt/homebrew/lib/node_modules/agenticmail/... — a path that no longer
+     * exists post-rename. The result is a launchd crash loop.
+     *
+     * `needsRepair()` returns a non-null reason whenever:
+     *  - the service file exists but the start-server.sh it launches is
+     *    missing or references a node_modules path that no longer resolves;
+     *  - the embedded service version drifts from the running CLI version
+     *    (so service files get refreshed on every upgrade — including
+     *    in-place version bumps that don't change the install path);
+     *  - the cached API entry path no longer exists on disk.
+     *
+     * Returns null when everything checks out — callers should treat that as
+     * "no action needed".
+     *
+     * Platform-aware: only inspects launchd artefacts on darwin and systemd
+     * artefacts on linux. Returns null on unsupported platforms so this can
+     * be called unconditionally from the CLI's start path.
+     */
+    needsRepair(): {
+        reason: string;
+    } | null;
 }
 
 interface SetupConfig {

package/dist/index.d.ts

@@ -1558,7 +1558,20 @@ declare class ServiceManager {
     private getNodePath;
     /**
      * Find the API server entry point.
-     * Searches common locations where agenticmail is installed.
+     *
+     * Issue #26 — Robust path resolution.
+     *
+     * The original implementation hard-coded `node_modules/agenticmail` (the
+     * old unscoped package name). After the rename to `@agenticmail/cli`, that
+     * directory no longer exists, so the resolver fell back to the stale
+     * `~/.agenticmail/api-entry.path` cache and the launchd plist kept pointing
+     * at a deleted path — causing the boot crash loop reported in #26.
+     *
+     * We now prefer `require.resolve('@agenticmail/api')` so the resolution
+     * follows the actual installed location regardless of npm prefix, the
+     * scoped vs unscoped package name, or the package manager (npm global,
+     * pnpm, yarn global, local node_modules). Cached paths are always
+     * validated against the filesystem before being returned.
      */
     private getApiEntryPath;
     /**
@@ -1567,6 +1580,10 @@ declare class ServiceManager {
     cacheApiEntryPath(entryPath: string): void;
     /**
      * Get the current package version.
+     *
+     * Issue #26 — resolve the CLI package.json via require.resolve so the
+     * version reflects the *currently installed* @agenticmail/cli, not a
+     * leftover unscoped `agenticmail` package directory.
      */
     private getVersion;
     /**
@@ -1619,6 +1636,34 @@ declare class ServiceManager {
         installed: boolean;
         message: string;
     };
+    /**
+     * Issue #26 — Detect a stale service installation.
+     *
+     * Background: when a user upgrades from the old unscoped `agenticmail`
+     * package to the new `@agenticmail/cli` scoped package, the old
+     * ~/Library/LaunchAgents/com.agenticmail.server.plist and
+     * ~/.agenticmail/bin/start-server.sh files keep pointing at
+     * /opt/homebrew/lib/node_modules/agenticmail/... — a path that no longer
+     * exists post-rename. The result is a launchd crash loop.
+     *
+     * `needsRepair()` returns a non-null reason whenever:
+     *  - the service file exists but the start-server.sh it launches is
+     *    missing or references a node_modules path that no longer resolves;
+     *  - the embedded service version drifts from the running CLI version
+     *    (so service files get refreshed on every upgrade — including
+     *    in-place version bumps that don't change the install path);
+     *  - the cached API entry path no longer exists on disk.
+     *
+     * Returns null when everything checks out — callers should treat that as
+     * "no action needed".
+     *
+     * Platform-aware: only inspects launchd artefacts on darwin and systemd
+     * artefacts on linux. Returns null on unsupported platforms so this can
+     * be called unconditionally from the CLI's start path.
+     */
+    needsRepair(): {
+        reason: string;
+    } | null;
 }
 
 interface SetupConfig {

package/dist/index.js

@@ -484,7 +484,8 @@ var InboxWatcher = class extends EventEmitter {
         this.emit("close");
         this._scheduleReconnect();
       });
-      this._lock = lock;
+      lock.release();
+      this._lock = null;
     } catch (err) {
       lock.release();
       throw err;
@@ -1163,7 +1164,15 @@ var AccountManager = class {
     }
     const principalName = options.name.toLowerCase();
     const email = `${principalName}@${domain}`;
+    const existingAgent = await this.getByName(options.name);
+    if (existingAgent != null) {
+      throw new Error(`Account already exists: ${options.name}`);
+    }
     await this.stalwart.ensureDomain(domain);
+    try {
+      await this.stalwart.deletePrincipal(principalName);
+    } catch {
+    }
     await this.stalwart.createPrincipal({
       type: "individual",
       name: principalName,
@@ -6310,6 +6319,7 @@ import { execFileSync as execFileSync3, execSync as execSync2 } from "child_proc
 import { existsSync as existsSync6, readFileSync as readFileSync3, writeFileSync as writeFileSync4, unlinkSync, mkdirSync as mkdirSync5, chmodSync } from "fs";
 import { join as join8 } from "path";
 import { homedir as homedir7, platform as platform4 } from "os";
+import { createRequire } from "module";
 var PLIST_LABEL = "com.agenticmail.server";
 var SYSTEMD_UNIT = "agenticmail.service";
 var ServiceManager = class {
@@ -6336,42 +6346,59 @@ var ServiceManager = class {
   }
   /**
    * Find the API server entry point.
-   * Searches common locations where agenticmail is installed.
+   *
+   * Issue #26 — Robust path resolution.
+   *
+   * The original implementation hard-coded `node_modules/agenticmail` (the
+   * old unscoped package name). After the rename to `@agenticmail/cli`, that
+   * directory no longer exists, so the resolver fell back to the stale
+   * `~/.agenticmail/api-entry.path` cache and the launchd plist kept pointing
+   * at a deleted path — causing the boot crash loop reported in #26.
+   *
+   * We now prefer `require.resolve('@agenticmail/api')` so the resolution
+   * follows the actual installed location regardless of npm prefix, the
+   * scoped vs unscoped package name, or the package manager (npm global,
+   * pnpm, yarn global, local node_modules). Cached paths are always
+   * validated against the filesystem before being returned.
    */
   getApiEntryPath() {
-    const searchDirs = [
-      // Global npm install
-      join8(homedir7(), "node_modules", "agenticmail"),
-      // npx cache / global prefix
-      ...(() => {
-        try {
-          const prefix = execSync2("npm prefix -g", { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
-          return [
-            join8(prefix, "lib", "node_modules", "agenticmail"),
-            join8(prefix, "node_modules", "agenticmail")
-          ];
-        } catch {
-          return [];
-        }
-      })(),
-      // Homebrew on macOS
-      "/opt/homebrew/lib/node_modules/agenticmail",
-      "/usr/local/lib/node_modules/agenticmail"
+    try {
+      const req = createRequire(import.meta.url);
+      const resolved = req.resolve("@agenticmail/api");
+      if (existsSync6(resolved)) return resolved;
+    } catch {
+    }
+    const parentPackages = [
+      join8("@agenticmail", "cli"),
+      // current scoped package
+      "agenticmail"
+      // legacy unscoped package
     ];
-    for (const base of searchDirs) {
-      const apiPaths = [
-        join8(base, "node_modules", "@agenticmail", "api", "dist", "index.js"),
-        join8(base, "..", "@agenticmail", "api", "dist", "index.js")
-      ];
-      for (const p of apiPaths) {
-        if (existsSync6(p)) return p;
+    const baseDirs = [
+      // user-local install
+      join8(homedir7(), "node_modules")
+    ];
+    try {
+      const prefix = execSync2("npm prefix -g", { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+      baseDirs.push(join8(prefix, "lib", "node_modules"));
+      baseDirs.push(join8(prefix, "node_modules"));
+    } catch {
+    }
+    baseDirs.push("/opt/homebrew/lib/node_modules");
+    baseDirs.push("/usr/local/lib/node_modules");
+    for (const base of baseDirs) {
+      const sibling = join8(base, "@agenticmail", "api", "dist", "index.js");
+      if (existsSync6(sibling)) return sibling;
+      for (const parent of parentPackages) {
+        const nested = join8(base, parent, "node_modules", "@agenticmail", "api", "dist", "index.js");
+        if (existsSync6(nested)) return nested;
       }
     }
     const dataDir = join8(homedir7(), ".agenticmail");
     const entryCache = join8(dataDir, "api-entry.path");
     if (existsSync6(entryCache)) {
       const cached = readFileSync3(entryCache, "utf-8").trim();
-      if (existsSync6(cached)) return cached;
+      if (cached && existsSync6(cached)) return cached;
     }
     throw new Error("Could not find @agenticmail/api entry point. Run `agenticmail start` first to populate the cache.");
   }
@@ -6385,25 +6412,49 @@ var ServiceManager = class {
   }
   /**
    * Get the current package version.
+   *
+   * Issue #26 — resolve the CLI package.json via require.resolve so the
+   * version reflects the *currently installed* @agenticmail/cli, not a
+   * leftover unscoped `agenticmail` package directory.
    */
   getVersion() {
     try {
-      const pkgPaths = [
-        join8(homedir7(), "node_modules", "agenticmail", "package.json"),
-        join8(homedir7(), ".agenticmail", "package-version.json")
-      ];
-      try {
-        const prefix = execSync2("npm prefix -g", { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
-        pkgPaths.push(join8(prefix, "lib", "node_modules", "agenticmail", "package.json"));
-      } catch {
+      const req = createRequire(import.meta.url);
+      const pkgJson = req.resolve("@agenticmail/cli/package.json");
+      if (existsSync6(pkgJson)) {
+        const pkg = JSON.parse(readFileSync3(pkgJson, "utf-8"));
+        if (pkg.version) return pkg.version;
       }
-      for (const p of pkgPaths) {
+    } catch {
+    }
+    try {
+      const apiEntry = this.getApiEntryPath();
+      const apiPkg = join8(apiEntry, "..", "..", "package.json");
+      if (existsSync6(apiPkg)) {
+        const pkg = JSON.parse(readFileSync3(apiPkg, "utf-8"));
+        if (pkg.version) return pkg.version;
+      }
+    } catch {
+    }
+    const candidates = [
+      join8(homedir7(), "node_modules", "@agenticmail", "cli", "package.json"),
+      join8(homedir7(), "node_modules", "agenticmail", "package.json"),
+      join8(homedir7(), ".agenticmail", "package-version.json")
+    ];
+    try {
+      const prefix = execSync2("npm prefix -g", { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+      candidates.push(join8(prefix, "lib", "node_modules", "@agenticmail", "cli", "package.json"));
+      candidates.push(join8(prefix, "lib", "node_modules", "agenticmail", "package.json"));
+    } catch {
+    }
+    for (const p of candidates) {
+      try {
         if (existsSync6(p)) {
           const pkg = JSON.parse(readFileSync3(p, "utf-8"));
           if (pkg.version) return pkg.version;
         }
+      } catch {
       }
-    } catch {
     }
     return "unknown";
   }
@@ -6709,6 +6760,86 @@ WantedBy=default.target
     this.uninstall();
     return this.install();
   }
+  /**
+   * Issue #26 — Detect a stale service installation.
+   *
+   * Background: when a user upgrades from the old unscoped `agenticmail`
+   * package to the new `@agenticmail/cli` scoped package, the old
+   * ~/Library/LaunchAgents/com.agenticmail.server.plist and
+   * ~/.agenticmail/bin/start-server.sh files keep pointing at
+   * /opt/homebrew/lib/node_modules/agenticmail/... — a path that no longer
+   * exists post-rename. The result is a launchd crash loop.
+   *
+   * `needsRepair()` returns a non-null reason whenever:
+   *  - the service file exists but the start-server.sh it launches is
+   *    missing or references a node_modules path that no longer resolves;
+   *  - the embedded service version drifts from the running CLI version
+   *    (so service files get refreshed on every upgrade — including
+   *    in-place version bumps that don't change the install path);
+   *  - the cached API entry path no longer exists on disk.
+   *
+   * Returns null when everything checks out — callers should treat that as
+   * "no action needed".
+   *
+   * Platform-aware: only inspects launchd artefacts on darwin and systemd
+   * artefacts on linux. Returns null on unsupported platforms so this can
+   * be called unconditionally from the CLI's start path.
+   */
+  needsRepair() {
+    if (this.os !== "darwin" && this.os !== "linux") return null;
+    const servicePath = this.getServicePath();
+    if (!existsSync6(servicePath)) return null;
+    let serviceContent = "";
+    try {
+      serviceContent = readFileSync3(servicePath, "utf-8");
+    } catch {
+      return { reason: "Service file unreadable" };
+    }
+    const startScript = join8(homedir7(), ".agenticmail", "bin", "start-server.sh");
+    if (serviceContent.includes(startScript)) {
+      if (!existsSync6(startScript)) {
+        return { reason: "start-server.sh is missing" };
+      }
+      let scriptContent = "";
+      try {
+        scriptContent = readFileSync3(startScript, "utf-8");
+      } catch {
+        return { reason: "start-server.sh unreadable" };
+      }
+      const apiPathMatch = scriptContent.match(/(\/[^"\s]+@agenticmail\/api\/dist\/index\.js)/);
+      if (apiPathMatch) {
+        const referenced = apiPathMatch[1];
+        if (!existsSync6(referenced)) {
+          return { reason: `start-server.sh references missing path: ${referenced}` };
+        }
+      }
+      if (/node_modules\/agenticmail\/(?!.*@agenticmail\/cli)/.test(scriptContent)) {
+        const stale = /(\S*node_modules\/agenticmail\/\S*)/.exec(scriptContent)?.[1];
+        if (stale && !existsSync6(stale)) {
+          return { reason: `start-server.sh references legacy unscoped path: ${stale}` };
+        }
+      }
+    } else {
+      return { reason: "Service file does not reference the wrapper script" };
+    }
+    const currentVersion = this.getVersion();
+    if (currentVersion !== "unknown") {
+      if (!serviceContent.includes(`v${currentVersion}`) || !serviceContent.includes(`AGENTICMAIL_SERVICE_VERSION`) || !serviceContent.includes(currentVersion)) {
+        return { reason: `Service version drift (current CLI is v${currentVersion})` };
+      }
+    }
+    const entryCache = join8(homedir7(), ".agenticmail", "api-entry.path");
+    if (existsSync6(entryCache)) {
+      try {
+        const cached = readFileSync3(entryCache, "utf-8").trim();
+        if (cached && !existsSync6(cached)) {
+          return { reason: `Cached API entry path no longer exists: ${cached}` };
+        }
+      } catch {
+      }
+    }
+    return null;
+  }
 };
 
 // src/setup/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/core",
-  "version": "0.5.56",
+  "version": "0.5.59",
   "description": "Core SDK for AgenticMail — email, SMS, and phone number access for AI agents",
   "type": "module",
   "main": "dist/index.js",