agendex-cli 0.15.0 → 0.17.0

package/README.md

@@ -57,6 +57,16 @@ AGENDEX_DEV=1 agendex sync
 
 In dev mode the default OAuth site (when you do not pass `--url` and do not set `AGENDEX_SITE_URL`) points at the local EE app URL used for development.
 
+## Sync Provenance
+
+`agendex sync` and the daemon include sync provenance in cloud payload metadata so the web app can show where a plan was synced from. This includes the device ID, hostname, and the host machine's local IP address when one is available.
+
+You can disable local IP address collection from Account settings in the cloud app. Managed or non-interactive environments can also omit the local IP address from sync payloads by setting:
+
+```bash
+AGENDEX_DISABLE_LOCAL_IP=1 agendex sync
+```
+
 ## Daemon Cleanup
 
 `agendex cleanup` manages registered daemon devices in the cloud.

package/dist/cli.js

@@ -1058,10 +1058,10 @@ var init_cleanup = __esm(() => {
 });
 
 // src/cli.ts
-import { spawn as spawn3 } from "node:child_process";
+import { spawn as spawn4 } from "node:child_process";
 import { existsSync as existsSync11, statSync as statSync2, writeSync } from "node:fs";
-import { resolve as resolve7 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { resolve as resolve8 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // ../shared/src/adapters/catalog.ts
 import { homedir as homedir7 } from "node:os";
@@ -2797,12 +2797,14 @@ function normalizeStoredConfig(raw) {
   const cloudToken = typeof raw.cloudToken === "string" && raw.cloudToken.trim() ? raw.cloudToken : undefined;
   const convexUrl = typeof raw.convexUrl === "string" && raw.convexUrl.trim() ? raw.convexUrl : undefined;
   const deviceId = typeof raw.deviceId === "string" && raw.deviceId.trim() ? raw.deviceId : undefined;
+  const collectLocalIpAddress = typeof raw.collectLocalIpAddress === "boolean" ? raw.collectLocalIpAddress : undefined;
   return {
     configVersion: 3,
     token,
     cloudToken,
     convexUrl,
     deviceId,
+    collectLocalIpAddress,
     enabledAdapters: normalizeAdapterIds(raw.enabledAdapters),
     customPlanDirs: normalizeCustomPlanDirs(raw.customPlanDirs)
   };
@@ -2818,6 +2820,7 @@ function saveConfig(config) {
     cloudToken: config.cloudToken,
     convexUrl: config.convexUrl,
     deviceId: config.deviceId,
+    collectLocalIpAddress: config.collectLocalIpAddress,
     enabledAdapters: sanitizeEnabledAdapterIds(config.enabledAdapters),
     customPlanDirs: normalizeCustomPlanDirs(config.customPlanDirs)
   };
@@ -3150,7 +3153,7 @@ function looksLikeExecutionReport(normalized) {
   const hasPastCompletion = /\b(?:fixed|pushed|committed|completed|done|implemented|updated|changed|patched|merged|deployed|passed|failed|resolved|reverted)\b/i.test(normalized);
   const hasReportSection = /^\s*(?:summary|result|results|changes|verification|status)\s*:/im.test(normalized);
   const hasReviewReportMarker = /\b(?:review findings?|review issues?|review comments?)\b/i.test(normalized);
-  const hasCommandMarker = /::[a-z0-9_-]+(?:\{|\[|\s*$)/im.test(normalized) || /`[^`]*(?:bun|npm|pnpm|yarn|git|tsc|biome)[^`]*`/i.test(normalized) || /\b(?:git\s+(?:stage|commit|push|status)|bunx?\s+|npm\s+|pnpm\s+|yarn\s+)\b/i.test(normalized);
+  const hasCommandMarker = /::[a-z0-9_-]+(?:\{|\[|\s*$)/im.test(normalized) || /`[^`]*(?:bun|npm|pnpm|yarn|git|tsc|oxfmt|oxlint|biome)[^`]*`/i.test(normalized) || /\b(?:git\s+(?:stage|commit|push|status)|bunx?\s+|npm\s+|pnpm\s+|yarn\s+)\b/i.test(normalized);
   return hasPastCompletion && (hasReportSection || hasCommandMarker || hasReviewReportMarker);
 }
 function lowValueAssessment(reasons, signals) {
@@ -3882,7 +3885,7 @@ async function refreshStoredToken(currentToken, convexUrl) {
   }
   return refreshed.token;
 }
-async function sendHeartbeat() {
+async function sendHeartbeat(ipAddress) {
   try {
     const { token, convexUrl } = getCloudConfig();
     const pidInfo = readPidInfo();
@@ -3891,7 +3894,8 @@ async function sendHeartbeat() {
       deviceId: cachedDeviceId,
       hostname: pidInfo?.hostname ?? osHostname(),
       startedAtMs: pidInfo?.startedAtMs,
-      pid: pidInfo?.pid
+      pid: pidInfo?.pid,
+      ipAddress: ipAddress ?? null
     });
     let activeToken = token;
     let res = await requestText(`${convexUrl}/api/cli/heartbeat`, {
@@ -3946,6 +3950,42 @@ async function refreshToken(currentToken, convexUrl) {
     return null;
   return { token: body.token, expiresAt: body.expiresAt ?? 0 };
 }
+async function fetchCliPreferences() {
+  try {
+    const { token, convexUrl } = getCloudConfig();
+    let activeToken = token;
+    let res = await requestText(`${convexUrl}/api/cli/preferences`, {
+      method: "GET",
+      headers: authHeaders(activeToken)
+    });
+    if (res.status === 401) {
+      const refreshed = await refreshStoredToken(activeToken, convexUrl);
+      if (refreshed) {
+        activeToken = refreshed;
+        res = await requestText(`${convexUrl}/api/cli/preferences`, {
+          method: "GET",
+          headers: authHeaders(activeToken)
+        });
+      }
+    }
+    if (res.status < 200 || res.status >= 300)
+      return null;
+    const body = JSON.parse(res.body);
+    if (typeof body.collectLocalIpAddress !== "boolean")
+      return null;
+    const config = loadConfig();
+    if (config) {
+      saveConfig({
+        ...config,
+        collectLocalIpAddress: body.collectLocalIpAddress
+      });
+    }
+    return { collectLocalIpAddress: body.collectLocalIpAddress };
+  } catch {
+    return null;
+  }
+}
+var REQUEST_TIMEOUT_MS2 = Number.parseInt(process.env.AGENDEX_HTTP_TIMEOUT_MS ?? "", 10) || 1e4;
 function requestText(urlString, options) {
   const url = new URL(urlString);
   const request = url.protocol === "https:" ? httpsRequest : httpRequest;
@@ -3957,7 +3997,8 @@ function requestText(urlString, options) {
     const req = request(url, {
       agent: false,
       headers,
-      method: options.method
+      method: options.method,
+      timeout: REQUEST_TIMEOUT_MS2
     }, (res) => {
       let body = "";
       res.setEncoding("utf8");
@@ -3973,6 +4014,9 @@ function requestText(urlString, options) {
       res.on("error", reject);
     });
     req.on("error", reject);
+    req.on("timeout", () => {
+      req.destroy(new Error(`Request to ${url.host} timed out after ${REQUEST_TIMEOUT_MS2}ms`));
+    });
     if (options.body) {
       req.write(options.body);
     }
@@ -4107,7 +4151,7 @@ async function deleteDaemons(deviceIds) {
 import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 var PROD_SITE_URL = "https://app.agendex.dev";
-var DEV_SITE_URL = "http://app.agendex.local:5174";
+var DEV_SITE_URL = "http://app.agendex.localhost:5174";
 function getDefaultSiteUrl() {
   if (process.env.AGENDEX_SITE_URL)
     return process.env.AGENDEX_SITE_URL;
@@ -4306,6 +4350,7 @@ function spawnBrowser(command, args, options = {}) {
 
 // src/daemon.ts
 import { spawn as spawn2 } from "node:child_process";
+import { hostname as osHostname2 } from "node:os";
 import { resolve as resolve6 } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -4335,24 +4380,141 @@ function resolveCliAdapterIds(config) {
   return ids;
 }
 
+// src/network.ts
+import { execFileSync } from "node:child_process";
+import { networkInterfaces } from "node:os";
+import { platform } from "node:process";
+var DISABLE_LOCAL_IP_ENV = "AGENDEX_DISABLE_LOCAL_IP";
+function shouldCollectLocalIpAddress(env = process.env) {
+  const value = env[DISABLE_LOCAL_IP_ENV]?.trim().toLowerCase();
+  return !["1", "true", "yes", "on"].includes(value ?? "");
+}
+function getLocalIpAddress(options = {}) {
+  const interfaces = options.interfaces ?? networkInterfaces();
+  const route = options.defaultRoute === undefined ? getDefaultIpv4Route() : options.defaultRoute;
+  const routedAddress = route ? getAddressForRoute(interfaces, route) : undefined;
+  return routedAddress ?? findFirstAddress(interfaces, "IPv4") ?? findFirstAddress(interfaces, "IPv6");
+}
+function getAddressForRoute(interfaces, route) {
+  if (route.sourceAddress && isUsableIpv4Address(route.sourceAddress))
+    return route.sourceAddress;
+  if (route.interfaceName)
+    return findFirstAddress(interfaces, "IPv4", route.interfaceName);
+  return;
+}
+function findFirstAddress(interfaces, family, interfaceName) {
+  const entries = interfaceName ? [[interfaceName, interfaces[interfaceName]]] : Object.entries(interfaces).sort(([left], [right]) => left.localeCompare(right));
+  for (const [, addrs] of entries) {
+    if (!addrs)
+      continue;
+    for (const addr of addrs) {
+      if (addr.internal)
+        continue;
+      if (addr.family === family)
+        return addr.address;
+    }
+  }
+  return;
+}
+function getDefaultIpv4Route() {
+  switch (platform) {
+    case "linux":
+      return parseLinuxRoute(readRouteCommand("ip", ["route", "get", "1.1.1.1"]));
+    case "darwin":
+    case "freebsd":
+    case "netbsd":
+    case "openbsd":
+      return parseBsdRoute(readRouteCommand("route", ["-n", "get", "1.1.1.1"]));
+    case "win32":
+      return getWindowsDefaultRouteAddress();
+    default:
+      return;
+  }
+}
+function readRouteCommand(command, args) {
+  try {
+    return execFileSync(command, args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 1000
+    });
+  } catch {
+    return;
+  }
+}
+function parseLinuxRoute(output) {
+  if (!output)
+    return;
+  return buildRoute({
+    interfaceName: output.match(/\bdev\s+(\S+)/)?.[1],
+    sourceAddress: output.match(/\bsrc\s+(\d{1,3}(?:\.\d{1,3}){3})\b/)?.[1]
+  });
+}
+function parseBsdRoute(output) {
+  if (!output)
+    return;
+  return buildRoute({
+    interfaceName: output.match(/^\s*interface:\s+(\S+)/m)?.[1]
+  });
+}
+function getWindowsDefaultRouteAddress() {
+  const script = [
+    "$route = Get-NetRoute -DestinationPrefix '0.0.0.0/0'",
+    "| Sort-Object -Property @{ Expression = { $_.RouteMetric + $_.InterfaceMetric } }",
+    "| Select-Object -First 1;",
+    "if ($route) {",
+    "Get-NetIPAddress -AddressFamily IPv4 -InterfaceIndex $route.InterfaceIndex",
+    "| Where-Object { $_.IPAddress -notlike '169.254.*' }",
+    "| Select-Object -First 1 -ExpandProperty IPAddress",
+    "}"
+  ].join(" ");
+  const output = readRouteCommand("powershell.exe", [
+    "-NoProfile",
+    "-NonInteractive",
+    "-Command",
+    script
+  ]);
+  const sourceAddress = output?.split(/\r?\n/).map((line) => line.trim()).find(isUsableIpv4Address);
+  return buildRoute({ sourceAddress });
+}
+function buildRoute(route) {
+  return route.interfaceName || route.sourceAddress ? route : undefined;
+}
+function isUsableIpv4Address(address) {
+  if (!isIpv4Address(address))
+    return false;
+  return address !== "0.0.0.0" && !address.startsWith("127.");
+}
+function isIpv4Address(address) {
+  const octets = address.split(".");
+  return octets.length === 4 && octets.every((octet) => {
+    if (!/^\d+$/.test(octet))
+      return false;
+    const value = Number(octet);
+    return value >= 0 && value <= 255;
+  });
+}
+
 // src/payload.ts
 var SYNC_METADATA_KEY = "agendexSync";
 function isRecord4(value) {
   return typeof value === "object" && value !== null;
 }
-function withSyncDeviceMetadata(metadata, deviceId) {
-  if (!deviceId)
+function withSyncDeviceMetadata(metadata, deviceId, hostname2, ipAddress) {
+  if (!deviceId && !hostname2 && !ipAddress)
     return metadata;
   const existing = isRecord4(metadata[SYNC_METADATA_KEY]) ? metadata[SYNC_METADATA_KEY] : {};
   return {
     ...metadata,
     [SYNC_METADATA_KEY]: {
       ...existing,
-      deviceId
+      ...deviceId !== undefined && { deviceId },
+      ...hostname2 !== undefined && { hostname: hostname2 },
+      ...ipAddress !== undefined && { ipAddress }
     }
   };
 }
-function planToSyncPayload(plan, deviceId) {
+function planToSyncPayload(plan, deviceId, hostname2, ipAddress) {
   return {
     localPlanId: plan.id,
     agent: plan.agent,
@@ -4361,7 +4523,7 @@ function planToSyncPayload(plan, deviceId) {
     format: plan.format,
     filePath: plan.filePath,
     workspace: plan.workspace,
-    metadata: withSyncDeviceMetadata(plan.metadata, deviceId),
+    metadata: withSyncDeviceMetadata(plan.metadata, deviceId, hostname2, ipAddress),
     createdAt: plan.createdAt.getTime(),
     updatedAt: plan.updatedAt.getTime()
   };
@@ -4415,6 +4577,16 @@ function computePayloadHash(payload) {
   return createHash2("sha256").update(canonical).digest("hex").slice(0, 20);
 }
 
+// src/sync-privacy.ts
+async function shouldIncludeLocalIpAddressInSync() {
+  if (!shouldCollectLocalIpAddress())
+    return false;
+  const prefs = await fetchCliPreferences();
+  if (prefs)
+    return prefs.collectLocalIpAddress;
+  return loadConfig()?.collectLocalIpAddress ?? true;
+}
+
 // src/writeback-delivery-cache.ts
 import { existsSync as existsSync9, mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join13 } from "node:path";
@@ -4472,15 +4644,25 @@ var PLANNOTATOR_WRITEBACK_EXPIRED_ERROR = "Write-back expired before delivery.";
 var PLANNOTATOR_WRITEBACK_FAILED_ERROR = "No live Plannotator session accepted the request-changes payload.";
 async function runWorker() {
   const config = await loadOrInitConfig();
+  const hostname2 = osHostname2();
   const adapterIds = resolveCliAdapterIds(config);
   const adapters = resolveAdapters(adapterIds);
   setActiveAdapters(adapters);
-  console.log(`[agendex] daemon starting with ${adapterIds.length} adapters`);
-  await sendHeartbeat();
   const syncCache = loadSyncCache();
   const syncQueue = [];
   const pendingWritebackReports = loadPendingWritebackReports();
   let syncing = false;
+  let cachedIpAddress;
+  async function getSyncIpAddress() {
+    if (!await shouldIncludeLocalIpAddressInSync()) {
+      cachedIpAddress = undefined;
+      return;
+    }
+    cachedIpAddress ??= getLocalIpAddress();
+    return cachedIpAddress;
+  }
+  console.log(`[agendex] daemon starting with ${adapterIds.length} adapters`);
+  await sendHeartbeat(await getSyncIpAddress());
   async function tryRefreshToken() {
     const cfg = loadConfig();
     if (!cfg?.cloudToken || !cfg.convexUrl)
@@ -4595,8 +4777,9 @@ async function runWorker() {
     });
     if (ok) {
       const updatedPlan = getById(job.localPlanId);
-      if (updatedPlan)
-        syncQueue.push(planToSyncPayload(updatedPlan, config.deviceId));
+      if (updatedPlan) {
+        syncQueue.push(planToSyncPayload(updatedPlan, config.deviceId, hostname2, await getSyncIpAddress()));
+      }
       pendingWritebackReports.set(job._id, "sent");
       persistPendingWritebackReports();
       await reportPendingWriteback(job._id);
@@ -4636,8 +4819,9 @@ async function runWorker() {
   let initialSkipped = 0;
   let initialQueuedSyncable = 0;
   let initialQueuedLowValue = 0;
+  const initialIpAddress = await getSyncIpAddress();
   for (const plan of plans) {
-    const payload = planToSyncPayload(plan, config.deviceId);
+    const payload = planToSyncPayload(plan, config.deviceId, hostname2, initialIpAddress);
     const hash = computePayloadHash(payload);
     if (syncCache[plan.id] === hash) {
       initialSkipped++;
@@ -4659,16 +4843,25 @@ async function runWorker() {
   const lowValueSuffix = lowValuePlanCount > 0 ? `, ${lowValuePlanCount} low-value hidden/pruned` : "";
   console.log(`[agendex] syncing ${initialQueuedSyncable} plans${lowValueSuffix} (${initialQueuedLowValue} low-value queued, ${initialSkipped} unchanged)...`);
   await processSyncQueue();
-  setInterval(() => void sendHeartbeat(), CLI_DAEMON_HEARTBEAT_INTERVAL_MS);
+  setInterval(() => {
+    (async () => {
+      await sendHeartbeat(await getSyncIpAddress());
+    })().catch(() => {});
+  }, CLI_DAEMON_HEARTBEAT_INTERVAL_MS);
   if (shouldEnablePlannotatorSync(config)) {
     setInterval(() => void pollPlannotatorWritebacks(), PLANNOTATOR_WRITEBACK_POLL_INTERVAL_MS);
     pollPlannotatorWritebacks();
   }
   startWatching((changedPlans) => {
-    for (const plan of changedPlans) {
-      syncQueue.push(planToSyncPayload(plan, config.deviceId));
-    }
-    processSyncQueue();
+    (async () => {
+      const ipAddress = await getSyncIpAddress();
+      for (const plan of changedPlans) {
+        syncQueue.push(planToSyncPayload(plan, config.deviceId, hostname2, ipAddress));
+      }
+      processSyncQueue();
+    })().catch((err) => {
+      console.error("[agendex] failed to queue changed plans:", err);
+    });
   });
   console.log(`[agendex] daemon running. Watching for file changes...`);
   async function gracefulShutdown() {
@@ -4729,8 +4922,11 @@ async function startSupervisor() {
 }
 
 // src/sync.ts
+import { hostname as osHostname3 } from "node:os";
 async function syncAll(force = false) {
   const config = await loadOrInitConfig();
+  const hostname2 = osHostname3();
+  const ipAddress = await shouldIncludeLocalIpAddressInSync() ? getLocalIpAddress() : undefined;
   const adapterIds = resolveCliAdapterIds(config);
   const adapters = resolveAdapters(adapterIds);
   setActiveAdapters(adapters);
@@ -4750,7 +4946,7 @@ async function syncAll(force = false) {
   let failed = 0;
   for (const plan of [...syncablePlans, ...lowValuePlans]) {
     activePlanIds.add(plan.id);
-    const payload = planToSyncPayload(plan, config.deviceId);
+    const payload = planToSyncPayload(plan, config.deviceId, hostname2, ipAddress);
     const hash = computePayloadHash(payload);
     if (!force && cache[plan.id] === hash) {
       skipped++;
@@ -4780,6 +4976,12 @@ async function syncAll(force = false) {
   console.log(`[agendex] Sync complete: ${synced} synced${lowValueSuffix}, ${skipped} unchanged, ${failed} failed`);
 }
 
+// src/upgrade.ts
+import { spawn as spawn3, spawnSync } from "node:child_process";
+import { realpathSync as realpathSync2 } from "node:fs";
+import { dirname as dirname4, resolve as resolve7, sep as sep4 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
 // src/version.ts
 import { existsSync as existsSync10, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "node:fs";
 import { tmpdir } from "node:os";
@@ -4787,19 +4989,18 @@ import { join as join14 } from "node:path";
 // package.json
 var package_default = {
   name: "agendex-cli",
-  version: "0.15.0",
+  version: "0.17.0",
   description: "Agendex CLI for login, sync, and daemon workflows",
   homepage: "https://github.com/Tyru5/Agendex#readme",
+  bugs: {
+    url: "https://github.com/Tyru5/Agendex/issues"
+  },
+  license: "AGPL-3.0-only",
   repository: {
     type: "git",
     url: "git+https://github.com/Tyru5/Agendex.git",
     directory: "packages/cli"
   },
-  bugs: {
-    url: "https://github.com/Tyru5/Agendex/issues"
-  },
-  type: "module",
-  license: "AGPL-3.0-only",
   bin: {
     agendex: "./dist/cli.js"
   },
@@ -4808,12 +5009,10 @@ var package_default = {
     "README.md",
     "LICENSE"
   ],
+  type: "module",
   publishConfig: {
     access: "public"
   },
-  engines: {
-    node: ">=20"
-  },
   scripts: {
     build: "node ./scripts/build-release.mjs --dist-only",
     "build:release": "node ./scripts/build-release.mjs",
@@ -4826,6 +5025,9 @@ var package_default = {
   devDependencies: {
     "@agendex/shared": "workspace:*",
     "@types/bun": "^1.3.9"
+  },
+  engines: {
+    node: ">=20"
   }
 };
 
@@ -4851,11 +5053,13 @@ function writeCache(result) {
     writeFileSync5(CACHE_FILE, JSON.stringify({ result, ts: Date.now() }));
   } catch {}
 }
-async function checkForUpdate() {
+async function checkForUpdate(options = {}) {
   const current = CLI_VERSION;
-  const cached = readCache(current);
-  if (cached)
-    return cached;
+  if (!options.forceRefresh) {
+    const cached = readCache(current);
+    if (cached)
+      return cached;
+  }
   try {
     const controller = new AbortController;
     const timeout = setTimeout(() => controller.abort(), 3000);
@@ -4863,21 +5067,27 @@ async function checkForUpdate() {
       signal: controller.signal
     }).finally(() => clearTimeout(timeout));
     if (!res.ok) {
-      return { updateAvailable: false, current, latest: current };
+      return { checked: false, updateAvailable: false, current, latest: current };
     }
     const data = await res.json();
     const latest = data.version;
-    const result = { updateAvailable: isNewer(latest, current), current, latest };
+    const result = {
+      checked: true,
+      updateAvailable: isNewer(latest, current),
+      current,
+      latest
+    };
     writeCache(result);
     return result;
   } catch {
-    return { updateAvailable: false, current, latest: current };
+    return { checked: false, updateAvailable: false, current, latest: current };
   }
 }
 function normalizeResult(result, current) {
   if (typeof result.latest !== "string")
     return null;
   return {
+    checked: true,
     updateAvailable: isNewer(result.latest, current),
     current,
     latest: result.latest
@@ -4897,6 +5107,195 @@ function isNewer(latest, current) {
   return false;
 }
 
+// src/upgrade.ts
+var PACKAGE_NAME = "agendex-cli";
+var moduleDir = dirname4(fileURLToPath2(import.meta.url));
+function getPackageRoot() {
+  try {
+    return realpathSync2(resolve7(moduleDir, ".."));
+  } catch {
+    return resolve7(moduleDir, "..");
+  }
+}
+function detectPackageManager(packageRoot) {
+  const userAgent = process.env.npm_config_user_agent ?? "";
+  const execpath = process.env.npm_execpath ?? "";
+  if (userAgent.startsWith("bun/") || execpath.includes("bun"))
+    return "bun";
+  if (userAgent.startsWith("pnpm/") || execpath.includes("pnpm"))
+    return "pnpm";
+  if (userAgent.startsWith("yarn/") || execpath.includes("yarn"))
+    return "yarn";
+  const lower = packageRoot.toLowerCase();
+  if (lower.includes(`${sep4}.bun${sep4}`) || lower.includes("/.bun/"))
+    return "bun";
+  if (lower.includes(`${sep4}pnpm${sep4}`) || lower.includes("/pnpm/"))
+    return "pnpm";
+  if (lower.includes(`${sep4}yarn${sep4}`) || lower.includes("/yarn/"))
+    return "yarn";
+  if (typeof globalThis.Bun !== "undefined" || process.versions.bun) {
+    return "bun";
+  }
+  return "npm";
+}
+function readYarnVersion() {
+  const result = spawnSync("yarn", ["--version"], {
+    encoding: "utf8",
+    shell: process.platform === "win32"
+  });
+  if (result.error || result.status !== 0)
+    return null;
+  return result.stdout.trim() || null;
+}
+function parseMajorVersion(version) {
+  const match = version.match(/^(\d+)/);
+  if (!match)
+    return null;
+  const major = Number(match[1]);
+  return Number.isFinite(major) ? major : null;
+}
+function buildGlobalInstallCommand(pm) {
+  const pkgSpec = `${PACKAGE_NAME}@latest`;
+  switch (pm) {
+    case "bun":
+      return {
+        supported: true,
+        command: { bin: "bun", args: ["add", "-g", pkgSpec], display: `bun add -g ${pkgSpec}` }
+      };
+    case "pnpm":
+      return {
+        supported: true,
+        command: {
+          bin: "pnpm",
+          args: ["add", "-g", pkgSpec],
+          display: `pnpm add -g ${pkgSpec}`
+        }
+      };
+    case "yarn": {
+      const yarnVersion = readYarnVersion();
+      const yarnMajorVersion = yarnVersion ? parseMajorVersion(yarnVersion) : null;
+      if (yarnMajorVersion !== null && yarnMajorVersion >= 2) {
+        return {
+          supported: false,
+          reason: `automatic upgrade with Yarn only supports Yarn Classic (v1); detected Yarn v${yarnVersion}.`,
+          manualCommand: `npm install -g ${pkgSpec}`
+        };
+      }
+      return {
+        supported: true,
+        command: {
+          bin: "yarn",
+          args: ["global", "add", pkgSpec],
+          display: `yarn global add ${pkgSpec}`
+        }
+      };
+    }
+    default:
+      return {
+        supported: true,
+        command: {
+          bin: "npm",
+          args: ["install", "-g", pkgSpec],
+          display: `npm install -g ${pkgSpec}`
+        }
+      };
+  }
+}
+function isLikelyGlobalInstall(packageRoot) {
+  const normalized = packageRoot.replace(/\\/g, "/");
+  if (!normalized.includes("/node_modules/")) {
+    return false;
+  }
+  const globalMarkers = [
+    "/lib/node_modules/",
+    "/pnpm/global/",
+    "/yarn/global/",
+    "/.bun/install/global/",
+    "/.bun/install/",
+    "/.config/yarn/global/",
+    "/AppData/Roaming/npm/",
+    "/AppData/Local/Yarn/",
+    "/AppData/Local/pnpm/"
+  ];
+  return globalMarkers.some((marker) => normalized.includes(marker));
+}
+async function runUpgrade(opts) {
+  const packageRoot = getPackageRoot();
+  const pm = detectPackageManager(packageRoot);
+  const isGlobal = isLikelyGlobalInstall(packageRoot);
+  if (!isGlobal) {
+    process.stderr.write(`[agendex] this CLI appears to be running from a local checkout or linked install:
+` + `[agendex]   ${packageRoot}
+` + `[agendex] automatic upgrade only supports global installs.
+` + `[agendex] reinstall globally (e.g. \`npm install -g ${PACKAGE_NAME}@latest\`) or update the source repo manually.
+`);
+    return 1;
+  }
+  const { checked, updateAvailable, current, latest } = await checkForUpdate({
+    forceRefresh: true
+  });
+  if (checked && !updateAvailable && !opts.force) {
+    process.stdout.write(`[agendex] already up to date (v${current})
+`);
+    return 0;
+  }
+  if (!checked) {
+    process.stderr.write(`[agendex] could not verify the latest version; attempting upgrade anyway...
+`);
+  }
+  const commandResult = buildGlobalInstallCommand(pm);
+  if (!commandResult.supported) {
+    process.stderr.write(`[agendex] ${commandResult.reason}
+`);
+    process.stderr.write(`[agendex] install the latest CLI manually, e.g. \`${commandResult.manualCommand}\`.
+`);
+    return 1;
+  }
+  const cmd = commandResult.command;
+  if (checked && updateAvailable) {
+    process.stdout.write(`[agendex] upgrading: v${current} → v${latest}
+`);
+  } else if (opts.force) {
+    process.stdout.write(`[agendex] reinstalling v${CLI_VERSION} (forced)
+`);
+  }
+  process.stdout.write(`[agendex] running: ${cmd.display}
+`);
+  return await new Promise((resolveExit) => {
+    const child = spawn3(cmd.bin, cmd.args, {
+      stdio: "inherit",
+      shell: process.platform === "win32",
+      env: process.env
+    });
+    let didError = false;
+    child.on("error", (err) => {
+      didError = true;
+      process.stderr.write(`[agendex] failed to run ${cmd.bin}: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.stderr.write(`[agendex] you can run it manually: ${cmd.display}
+`);
+      resolveExit(1);
+    });
+    child.on("close", (code) => {
+      if (didError)
+        return;
+      if (code === 0) {
+        process.stdout.write(`[agendex] upgrade complete.
+`);
+        process.stdout.write(`[agendex] note: if the daemon is running, restart it: \`agendex stop && agendex start\`
+`);
+        resolveExit(0);
+        return;
+      }
+      process.stderr.write(`[agendex] upgrade failed with exit code ${code ?? "unknown"}
+`);
+      process.stderr.write(`[agendex] you can run it manually: ${cmd.display}
+`);
+      resolveExit(code ?? 1);
+    });
+  });
+}
+
 // src/web.ts
 async function openAgendexWeb(siteUrlOverride) {
   const base = siteUrlOverride ?? getDefaultSiteUrl();
@@ -4934,7 +5333,7 @@ function firstCommandToken(argv) {
   return;
 }
 var command = firstCommandToken(args) ?? "start";
-var cliEntry = resolve7(process.argv[1] ?? fileURLToPath2(import.meta.url));
+var cliEntry = resolve8(process.argv[1] ?? fileURLToPath3(import.meta.url));
 async function main() {
   const isInternal = args.includes("--daemon") || args.includes("--worker");
   if (command === "--version" || command === "-v") {
@@ -4952,16 +5351,16 @@ async function main() {
     "add-dir",
     "remove-dir",
     "list-dirs",
+    "upgrade",
     "help",
     "--help",
     "-h"
   ].includes(command);
   if (!isInternal && !isPassthrough) {
-    const { updateAvailable, current, latest } = await checkForUpdate();
-    if (updateAvailable) {
-      writeStderr(`[agendex] update required: v${current} → v${latest}`);
-      writeStderr(`[agendex] run: npm i -g agendex-cli`);
-      return 1;
+    const { checked, updateAvailable, current, latest } = await checkForUpdate();
+    if (checked && updateAvailable) {
+      writeStderr(`[agendex] update available: v${current} → v${latest}`);
+      writeStderr(`[agendex] run: agendex upgrade`);
     }
   }
   switch (command) {
@@ -5000,7 +5399,7 @@ async function main() {
       const daemonArgs = [cliEntry, "start", "--daemon"];
       if (devFlag)
         daemonArgs.push("--dev");
-      const child = spawn3(process.execPath, daemonArgs, {
+      const child = spawn4(process.execPath, daemonArgs, {
         detached: true,
         stdio: "ignore",
         env: { ...process.env, ...devFlag ? { AGENDEX_DEV: "1" } : {} }
@@ -5153,7 +5552,7 @@ async function main() {
         const { request } = await import("node:http");
         const body = JSON.stringify({ path: resolved });
         try {
-          const res = await new Promise((resolve8, reject) => {
+          const res = await new Promise((resolve9, reject) => {
             const req = request(`http://localhost:${port}/api/v1/plan-sources`, {
               method: "POST",
               headers: {
@@ -5167,7 +5566,7 @@ async function main() {
               res2.on("data", (chunk) => {
                 data += chunk;
               });
-              res2.on("end", () => resolve8({ status: res2.statusCode ?? 0, body: data }));
+              res2.on("end", () => resolve9({ status: res2.statusCode ?? 0, body: data }));
               res2.on("error", reject);
             });
             req.on("error", reject);
@@ -5277,8 +5676,10 @@ async function main() {
               const uptimeStr = device.startedAtMs != null ? formatDuration(now - device.startedAtMs) : "~";
               const pidStr = device.pid != null ? String(device.pid) : "~";
               const hostnameStr = device.hostname ?? "~";
+              const ipStr = device.ipAddress ?? "~";
               const isLocal = localDeviceId && device.deviceId === localDeviceId;
               writeStdout(`- hostname: ${hostnameStr}${isLocal ? " (this machine)" : ""}
+  ip: ${ipStr}
   pid: ${pidStr}
   uptime: ${uptimeStr}
   status: ${status}`);
@@ -5295,6 +5696,9 @@ async function main() {
       }
       return 0;
     }
+    case "upgrade": {
+      return await runUpgrade({ force: args.includes("--force") });
+    }
     case "help":
     case "--help":
     case "-h": {
@@ -5321,6 +5725,8 @@ Usage:
   agendex cleanup      Interactively remove cloud daemons
   agendex cleanup --stale  Auto-remove all stale daemons
   agendex status       Show current config state + daemon status
+  agendex upgrade      Upgrade the globally installed CLI to the latest version
+  agendex upgrade --force  Reinstall latest even if already up to date
   agendex help         Show this help message
   agendex --version    Print CLI version
   agendex -v           Print CLI version
@@ -5349,13 +5755,13 @@ function flushStream(stream) {
   if (stream.destroyed || !stream.writable) {
     return Promise.resolve();
   }
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve9, reject) => {
     stream.write("", (error) => {
       if (error) {
         reject(error);
         return;
       }
-      resolve8();
+      resolve9();
     });
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agendex-cli",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Agendex CLI for login, sync, and daemon workflows",
   "homepage": "https://github.com/Tyru5/Agendex#readme",
   "repository": {