@agenticmail/core 0.5.58 → 0.5.61

package/dist/index.cjs

@@ -1918,13 +1918,14 @@ 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);
-    const existsInSqlite = await this.getByName(options.name) != null;
-    if (!existsInSqlite) {
-      try {
-        await this.stalwart.deletePrincipal(principalName);
-      } catch {
-      }
+    try {
+      await this.stalwart.deletePrincipal(principalName);
+    } catch {
     }
     await this.stalwart.createPrincipal({
       type: "individual",
@@ -3652,6 +3653,40 @@ var import_nodemailer2 = __toESM(require("nodemailer"), 1);
 var import_mail_composer2 = __toESM(require("nodemailer/lib/mail-composer/index.js"), 1);
 var import_imapflow3 = require("imapflow");
 var import_mailparser2 = require("mailparser");
+function formatPollError(err) {
+  if (!err) return "unknown error (no error object)";
+  if (typeof err !== "object") return String(err);
+  const e = err;
+  const parts = [];
+  const head = (e.message ?? String(err)).toString().trim();
+  if (head) parts.push(head);
+  if (e.code && e.code !== head) parts.push(`code=${e.code}`);
+  if (typeof e.errno === "number") parts.push(`errno=${e.errno}`);
+  if (e.syscall) parts.push(`syscall=${e.syscall}`);
+  if (e.hostname) parts.push(`host=${e.hostname}`);
+  if (typeof e.port === "number") parts.push(`port=${e.port}`);
+  if (e.responseText && e.responseText !== head) {
+    parts.push(`response=${truncate(String(e.responseText), 240)}`);
+  } else if (e.response && e.response !== head) {
+    parts.push(`response=${truncate(String(e.response), 240)}`);
+  }
+  if (e.command) parts.push(`command=${e.command}`);
+  if (typeof e.exitCode === "number") parts.push(`exit=${e.exitCode}`);
+  else if (e.code && /^\d+$/.test(String(e.code))) parts.push(`exit=${e.code}`);
+  if (e.signal) parts.push(`signal=${e.signal}`);
+  const stderr = (e.stderr ?? "").toString().trim();
+  if (stderr) parts.push(`stderr=${truncate(stderr, 240)}`);
+  const stdout = (e.stdout ?? "").toString().trim();
+  if (stdout && !stderr) parts.push(`stdout=${truncate(stdout, 240)}`);
+  if (parts.length === 1 && /^command failed$/i.test(head)) {
+    return `${head} (no further detail available \u2014 wrapping error did not carry stderr/code/response)`;
+  }
+  return parts.join(" | ");
+}
+function truncate(s, max) {
+  if (s.length <= max) return s;
+  return s.slice(0, max - 1).trimEnd() + "\u2026";
+}
 var RelayGateway = class {
   smtpTransport = null;
   pollTimer = null;
@@ -3826,7 +3861,7 @@ var RelayGateway = class {
       this.consecutiveFailures = 0;
     } catch (err) {
       this.consecutiveFailures++;
-      const msg = err instanceof Error ? err.message : String(err);
+      const msg = formatPollError(err);
       console.error(`[RelayGateway] Poll failed (attempt ${this.consecutiveFailures}): ${msg}`);
       if (this.consecutiveFailures >= 5 && this.consecutiveFailures % 5 === 0) {
         console.error(`[RelayGateway] ${this.consecutiveFailures} consecutive failures \u2014 check IMAP credentials and connectivity (${this.config?.imapHost}:${this.config?.imapPort})`);
@@ -6084,20 +6119,23 @@ var GatewayManager = class {
   }
   /**
    * Resume gateway from saved config (e.g., after server restart).
+   *
+   * Issue #31 — On a Docker container restart the API can come up
+   * before Stalwart / Gmail IMAP / DNS is reachable, so the very first
+   * setup() can fail with a transient network error. Previously that
+   * single failure was logged and never retried, leaving polling
+   * permanently dead until someone noticed and manually revived the
+   * relay. We now schedule background retries with exponential backoff
+   * (5s, 10s, 20s, 40s, 60s cap, indefinite) so the relay
+   * self-recovers as soon as the dependency is reachable again.
    */
   async resume() {
     if (this.config.mode === "relay" && this.config.relay) {
       try {
-        await this.relay.setup(this.config.relay);
-        const savedUid = this.loadLastSeenUid();
-        if (savedUid > 0) {
-          this.relay.setLastSeenUid(savedUid);
-          console.log(`[GatewayManager] Restored lastSeenUid=${savedUid} from database`);
-        }
-        this.relay.onUidAdvance = (uid) => this.saveLastSeenUid(uid);
-        await this.relay.startPolling();
+        await this._resumeRelayOnce();
       } catch (err) {
-        console.error("[GatewayManager] Failed to resume relay:", err);
+        console.error("[GatewayManager] Initial relay resume failed; scheduling retries:", formatPollError(err));
+        this._scheduleRelayResumeRetry();
       }
     }
     if (this.smsManager && this.accountManager) {
@@ -6124,6 +6162,42 @@ var GatewayManager = class {
       }
     }
   }
+  // ─── Issue #31 helpers — resume retry with backoff ───
+  _resumeRetryTimer = null;
+  _resumeRetryAttempt = 0;
+  async _resumeRelayOnce() {
+    if (!this.config.relay) throw new Error("No relay config to resume");
+    await this.relay.setup(this.config.relay);
+    const savedUid = this.loadLastSeenUid();
+    if (savedUid > 0) {
+      this.relay.setLastSeenUid(savedUid);
+      console.log(`[GatewayManager] Restored lastSeenUid=${savedUid} from database`);
+    }
+    this.relay.onUidAdvance = (uid) => this.saveLastSeenUid(uid);
+    await this.relay.startPolling();
+    if (this._resumeRetryAttempt > 0) {
+      console.log(`[GatewayManager] Relay polling resumed after ${this._resumeRetryAttempt} retry attempt${this._resumeRetryAttempt !== 1 ? "s" : ""}`);
+    }
+    this._resumeRetryAttempt = 0;
+  }
+  _scheduleRelayResumeRetry() {
+    if (this._resumeRetryTimer) return;
+    this._resumeRetryAttempt++;
+    const base = Math.min(5e3 * Math.pow(2, this._resumeRetryAttempt - 1), 6e4);
+    const jitter = base * (0.8 + Math.random() * 0.4);
+    const delay = Math.round(jitter);
+    console.log(`[GatewayManager] Will retry relay resume in ${(delay / 1e3).toFixed(1)}s (attempt ${this._resumeRetryAttempt + 1})`);
+    this._resumeRetryTimer = setTimeout(async () => {
+      this._resumeRetryTimer = null;
+      if (this.config.mode !== "relay" || !this.config.relay) return;
+      try {
+        await this._resumeRelayOnce();
+      } catch (err) {
+        console.error(`[GatewayManager] Relay resume retry ${this._resumeRetryAttempt} failed:`, formatPollError(err));
+        this._scheduleRelayResumeRetry();
+      }
+    }, delay);
+  }
   // --- Persistence ---
   loadConfig() {
     const row = this.db.prepare("SELECT * FROM gateway_config WHERE id = ?").get("default");
@@ -7076,6 +7150,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 {
@@ -7102,42 +7178,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.");
   }
@@ -7151,25 +7244,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;
+      }
+    } 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;
       }
-      for (const p of pkgPaths) {
+    } 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";
   }
@@ -7475,6 +7592,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

@@ -1244,8 +1244,21 @@ declare class GatewayManager {
     shutdown(): Promise<void>;
     /**
      * Resume gateway from saved config (e.g., after server restart).
+     *
+     * Issue #31 — On a Docker container restart the API can come up
+     * before Stalwart / Gmail IMAP / DNS is reachable, so the very first
+     * setup() can fail with a transient network error. Previously that
+     * single failure was logged and never retried, leaving polling
+     * permanently dead until someone noticed and manually revived the
+     * relay. We now schedule background retries with exponential backoff
+     * (5s, 10s, 20s, 40s, 60s cap, indefinite) so the relay
+     * self-recovers as soon as the dependency is reachable again.
      */
     resume(): Promise<void>;
+    private _resumeRetryTimer;
+    private _resumeRetryAttempt;
+    private _resumeRelayOnce;
+    private _scheduleRelayResumeRetry;
     private loadConfig;
     private saveConfig;
     private saveLastSeenUid;
@@ -1558,7 +1571,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 +1593,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 +1649,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

@@ -1244,8 +1244,21 @@ declare class GatewayManager {
     shutdown(): Promise<void>;
     /**
      * Resume gateway from saved config (e.g., after server restart).
+     *
+     * Issue #31 — On a Docker container restart the API can come up
+     * before Stalwart / Gmail IMAP / DNS is reachable, so the very first
+     * setup() can fail with a transient network error. Previously that
+     * single failure was logged and never retried, leaving polling
+     * permanently dead until someone noticed and manually revived the
+     * relay. We now schedule background retries with exponential backoff
+     * (5s, 10s, 20s, 40s, 60s cap, indefinite) so the relay
+     * self-recovers as soon as the dependency is reachable again.
      */
     resume(): Promise<void>;
+    private _resumeRetryTimer;
+    private _resumeRetryAttempt;
+    private _resumeRelayOnce;
+    private _scheduleRelayResumeRetry;
     private loadConfig;
     private saveConfig;
     private saveLastSeenUid;
@@ -1558,7 +1571,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 +1593,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 +1649,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

@@ -1164,13 +1164,14 @@ 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);
-    const existsInSqlite = await this.getByName(options.name) != null;
-    if (!existsInSqlite) {
-      try {
-        await this.stalwart.deletePrincipal(principalName);
-      } catch {
-      }
+    try {
+      await this.stalwart.deletePrincipal(principalName);
+    } catch {
     }
     await this.stalwart.createPrincipal({
       type: "individual",
@@ -2895,6 +2896,40 @@ import nodemailer2 from "nodemailer";
 import MailComposer2 from "nodemailer/lib/mail-composer/index.js";
 import { ImapFlow as ImapFlow3 } from "imapflow";
 import { simpleParser as simpleParser2 } from "mailparser";
+function formatPollError(err) {
+  if (!err) return "unknown error (no error object)";
+  if (typeof err !== "object") return String(err);
+  const e = err;
+  const parts = [];
+  const head = (e.message ?? String(err)).toString().trim();
+  if (head) parts.push(head);
+  if (e.code && e.code !== head) parts.push(`code=${e.code}`);
+  if (typeof e.errno === "number") parts.push(`errno=${e.errno}`);
+  if (e.syscall) parts.push(`syscall=${e.syscall}`);
+  if (e.hostname) parts.push(`host=${e.hostname}`);
+  if (typeof e.port === "number") parts.push(`port=${e.port}`);
+  if (e.responseText && e.responseText !== head) {
+    parts.push(`response=${truncate(String(e.responseText), 240)}`);
+  } else if (e.response && e.response !== head) {
+    parts.push(`response=${truncate(String(e.response), 240)}`);
+  }
+  if (e.command) parts.push(`command=${e.command}`);
+  if (typeof e.exitCode === "number") parts.push(`exit=${e.exitCode}`);
+  else if (e.code && /^\d+$/.test(String(e.code))) parts.push(`exit=${e.code}`);
+  if (e.signal) parts.push(`signal=${e.signal}`);
+  const stderr = (e.stderr ?? "").toString().trim();
+  if (stderr) parts.push(`stderr=${truncate(stderr, 240)}`);
+  const stdout = (e.stdout ?? "").toString().trim();
+  if (stdout && !stderr) parts.push(`stdout=${truncate(stdout, 240)}`);
+  if (parts.length === 1 && /^command failed$/i.test(head)) {
+    return `${head} (no further detail available \u2014 wrapping error did not carry stderr/code/response)`;
+  }
+  return parts.join(" | ");
+}
+function truncate(s, max) {
+  if (s.length <= max) return s;
+  return s.slice(0, max - 1).trimEnd() + "\u2026";
+}
 var RelayGateway = class {
   smtpTransport = null;
   pollTimer = null;
@@ -3069,7 +3104,7 @@ var RelayGateway = class {
       this.consecutiveFailures = 0;
     } catch (err) {
       this.consecutiveFailures++;
-      const msg = err instanceof Error ? err.message : String(err);
+      const msg = formatPollError(err);
       console.error(`[RelayGateway] Poll failed (attempt ${this.consecutiveFailures}): ${msg}`);
       if (this.consecutiveFailures >= 5 && this.consecutiveFailures % 5 === 0) {
         console.error(`[RelayGateway] ${this.consecutiveFailures} consecutive failures \u2014 check IMAP credentials and connectivity (${this.config?.imapHost}:${this.config?.imapPort})`);
@@ -5326,20 +5361,23 @@ var GatewayManager = class {
   }
   /**
    * Resume gateway from saved config (e.g., after server restart).
+   *
+   * Issue #31 — On a Docker container restart the API can come up
+   * before Stalwart / Gmail IMAP / DNS is reachable, so the very first
+   * setup() can fail with a transient network error. Previously that
+   * single failure was logged and never retried, leaving polling
+   * permanently dead until someone noticed and manually revived the
+   * relay. We now schedule background retries with exponential backoff
+   * (5s, 10s, 20s, 40s, 60s cap, indefinite) so the relay
+   * self-recovers as soon as the dependency is reachable again.
    */
   async resume() {
     if (this.config.mode === "relay" && this.config.relay) {
       try {
-        await this.relay.setup(this.config.relay);
-        const savedUid = this.loadLastSeenUid();
-        if (savedUid > 0) {
-          this.relay.setLastSeenUid(savedUid);
-          console.log(`[GatewayManager] Restored lastSeenUid=${savedUid} from database`);
-        }
-        this.relay.onUidAdvance = (uid) => this.saveLastSeenUid(uid);
-        await this.relay.startPolling();
+        await this._resumeRelayOnce();
       } catch (err) {
-        console.error("[GatewayManager] Failed to resume relay:", err);
+        console.error("[GatewayManager] Initial relay resume failed; scheduling retries:", formatPollError(err));
+        this._scheduleRelayResumeRetry();
       }
     }
     if (this.smsManager && this.accountManager) {
@@ -5366,6 +5404,42 @@ var GatewayManager = class {
       }
     }
   }
+  // ─── Issue #31 helpers — resume retry with backoff ───
+  _resumeRetryTimer = null;
+  _resumeRetryAttempt = 0;
+  async _resumeRelayOnce() {
+    if (!this.config.relay) throw new Error("No relay config to resume");
+    await this.relay.setup(this.config.relay);
+    const savedUid = this.loadLastSeenUid();
+    if (savedUid > 0) {
+      this.relay.setLastSeenUid(savedUid);
+      console.log(`[GatewayManager] Restored lastSeenUid=${savedUid} from database`);
+    }
+    this.relay.onUidAdvance = (uid) => this.saveLastSeenUid(uid);
+    await this.relay.startPolling();
+    if (this._resumeRetryAttempt > 0) {
+      console.log(`[GatewayManager] Relay polling resumed after ${this._resumeRetryAttempt} retry attempt${this._resumeRetryAttempt !== 1 ? "s" : ""}`);
+    }
+    this._resumeRetryAttempt = 0;
+  }
+  _scheduleRelayResumeRetry() {
+    if (this._resumeRetryTimer) return;
+    this._resumeRetryAttempt++;
+    const base = Math.min(5e3 * Math.pow(2, this._resumeRetryAttempt - 1), 6e4);
+    const jitter = base * (0.8 + Math.random() * 0.4);
+    const delay = Math.round(jitter);
+    console.log(`[GatewayManager] Will retry relay resume in ${(delay / 1e3).toFixed(1)}s (attempt ${this._resumeRetryAttempt + 1})`);
+    this._resumeRetryTimer = setTimeout(async () => {
+      this._resumeRetryTimer = null;
+      if (this.config.mode !== "relay" || !this.config.relay) return;
+      try {
+        await this._resumeRelayOnce();
+      } catch (err) {
+        console.error(`[GatewayManager] Relay resume retry ${this._resumeRetryAttempt} failed:`, formatPollError(err));
+        this._scheduleRelayResumeRetry();
+      }
+    }, delay);
+  }
   // --- Persistence ---
   loadConfig() {
     const row = this.db.prepare("SELECT * FROM gateway_config WHERE id = ?").get("default");
@@ -6318,6 +6392,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 {
@@ -6344,42 +6419,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.");
   }
@@ -6393,25 +6485,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;
+      }
+    } 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;
       }
-      for (const p of pkgPaths) {
+    } 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";
   }
@@ -6717,6 +6833,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.58",
+  "version": "0.5.61",
   "description": "Core SDK for AgenticMail — email, SMS, and phone number access for AI agents",
   "type": "module",
   "main": "dist/index.js",