@kiran_nandi_123/conxa 1.0.4 → 1.0.6

package/README.md

@@ -3,13 +3,30 @@
 CLI for installing and running Conxa automation plugins on top of the
 shared `conxa` MCP runtime.
 
-## Install plugins
-
-```
-npx -y conxa install <plugin_id>
-```
-
-Plugin refs accepted:
+## Install plugins
+
+PowerShell on Windows:
+
+```powershell
+npx.cmd -y "@kiran_nandi_123/conxa" install "cannonboldoff-hue/render"
+```
+
+Generic shell:
+
+```
+npx -y "@kiran_nandi_123/conxa" install <plugin_id>
+```
+
+Avoid running downloaded scripts inline with `irm` + `scriptblock`. If you need
+the PowerShell installer, download and inspect it first:
+
+```powershell
+irm "https://cdn.jsdelivr.net/npm/@kiran_nandi_123/conxa/scripts/install.ps1" -OutFile ".\install-conxa.ps1"
+Get-Content ".\install-conxa.ps1"
+powershell -ExecutionPolicy Bypass -File ".\install-conxa.ps1" "cannonboldoff-hue/render"
+```
+
+Plugin refs accepted:
 
 - `acme/hr-onboarding` — GitHub `owner/repo` (cloned via git)
 - `acme/hr-onboarding@v1.0.0` — pinned version (git tag)

package/lib/browser.js

@@ -6,19 +6,36 @@ const { getPluginConfig, getPluginDir, getAuthJson } = require("./config");
 
 // ─── Browser cache (per-slug, 5-min idle timeout) ────────────────────────────
 
-const _cache = new Map(); // slug → { browser, context, idleTimer }
+const _cache    = new Map();  // slug → { browser, context, idleTimer }
+const _holds    = new Map();  // slug → hold count
+const _inflight = new Map();  // slug → Promise<{browser,context}> (dedup concurrent launches)
 const BROWSER_IDLE_MS = 5 * 60 * 1000;
+const BROWSER_MAX     = 5;
 
 function _scheduleCleanup(slug) {
   const entry = _cache.get(slug);
   if (!entry) return;
   clearTimeout(entry.idleTimer);
   entry.idleTimer = setTimeout(async () => {
+    if ((_holds.get(slug) || 0) > 0) {
+      _scheduleCleanup(slug); // still held — defer
+      return;
+    }
     console.error(`[browser-cache] Idle timeout for ${slug} — closing browser`);
     const b = entry.browser;
     _cache.delete(slug);
     if (b) await b.close().catch(() => {});
   }, BROWSER_IDLE_MS);
+  entry.idleTimer.unref?.();
+}
+
+function holdBrowser(slug) {
+  _holds.set(slug, (_holds.get(slug) || 0) + 1);
+}
+
+function releaseBrowserHold(slug) {
+  const n = (_holds.get(slug) || 0) - 1;
+  if (n <= 0) _holds.delete(slug); else _holds.set(slug, n);
 }
 
 async function getCachedBrowser(slug) {
@@ -33,11 +50,35 @@ async function getCachedBrowser(slug) {
       _cache.delete(slug);
     }
   }
-  const { browser, context } = await getAuthContext(slug, false);
-  _cache.set(slug, { browser, context, idleTimer: null });
-  _scheduleCleanup(slug);
-  console.error(`[browser-cache] Launched new browser for ${slug}`);
-  return { browser, context, cached: false };
+  // Dedup concurrent launch requests for the same slug
+  if (_inflight.has(slug)) {
+    console.error(`[browser-cache] Waiting for in-flight browser launch for ${slug}`);
+    return _inflight.get(slug);
+  }
+  const launch = (async () => {
+    try {
+      const { browser, context } = await getAuthContext(slug, false);
+      // Evict LRU entry if at capacity (skip held browsers)
+      if (_cache.size >= BROWSER_MAX) {
+        for (const [evictSlug, evictEntry] of _cache.entries()) {
+          if ((_holds.get(evictSlug) || 0) > 0) continue;
+          clearTimeout(evictEntry.idleTimer);
+          _cache.delete(evictSlug);
+          if (evictEntry.browser) evictEntry.browser.close().catch(() => {});
+          console.error(`[browser-cache] Evicted ${evictSlug} (cache limit ${BROWSER_MAX})`);
+          break;
+        }
+      }
+      _cache.set(slug, { browser, context, idleTimer: null });
+      _scheduleCleanup(slug);
+      console.error(`[browser-cache] Launched new browser for ${slug}`);
+      return { browser, context, cached: false };
+    } finally {
+      _inflight.delete(slug);
+    }
+  })();
+  _inflight.set(slug, launch);
+  return launch;
 }
 
 // ─── Session management ───────────────────────────────────────────────────────
@@ -76,6 +117,9 @@ async function getAuthContext(slug, headless) {
     console.error(`[auth:${slug}] No auth.json — starting manual login`);
   }
 
+  const isCI = process.env.CI || process.env.DISPLAY === "" || (!process.env.DISPLAY && process.platform === "linux");
+  if (isCI) throw new Error(`[auth:${slug}] Cannot open login browser in headless/CI environment. Pre-generate auth.json and place it at ${authJson}`);
+
   console.error(`[auth:${slug}] Opening login browser — waiting for user to authenticate...`);
   const loginBrowser = await chromium.launch({ headless: false });
   const loginCtx     = await loginBrowser.newContext();
@@ -92,8 +136,8 @@ async function getAuthContext(slug, headless) {
   }
 
   const state = await loginCtx.storageState();
-  fs.mkdirSync(path.dirname(authJson), { recursive: true });
-  fs.writeFileSync(authJson, JSON.stringify(state, null, 2));
+  fs.mkdirSync(path.dirname(authJson), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(authJson, JSON.stringify(state, null, 2), { encoding: "utf8", mode: 0o600 });
   console.error(`[auth:${slug}] Session saved to auth.json — closing login browser`);
   await loginBrowser.close();
 
@@ -126,4 +170,4 @@ async function gracefulShutdown() {
   process.exit(0);
 }
 
-module.exports = { getCachedBrowser, isAuthenticated, getAuthContext, gracefulShutdown };
+module.exports = { getCachedBrowser, holdBrowser, releaseBrowserHold, isAuthenticated, getAuthContext, gracefulShutdown };

package/lib/cli.js

@@ -34,12 +34,53 @@ const SERVER_JS       = path.join(RUNTIME_DIR, "server.js");
 
 function readRegistry() {
   if (!fs.existsSync(REGISTRY_PATH)) return {};
-  try { return JSON.parse(fs.readFileSync(REGISTRY_PATH, "utf8")); } catch (_) { return {}; }
+  try { return JSON.parse(fs.readFileSync(REGISTRY_PATH, "utf8")); }
+  catch (e) {
+    const bak = REGISTRY_PATH + ".bak";
+    try { fs.renameSync(REGISTRY_PATH, bak); } catch (_) {}
+    process.stderr.write(`[conxa] Warning: registry.json was corrupt (${e.message}) — backed up to registry.json.bak\n`);
+    return {};
+  }
+}
+
+function _atomicWrite(filePath, content) {
+  const tmp = filePath + `.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, content, "utf8");
+  fs.renameSync(tmp, filePath);
 }
 
 function writeRegistry(reg) {
   fs.mkdirSync(CONXA_HOME, { recursive: true });
-  fs.writeFileSync(REGISTRY_PATH, JSON.stringify(reg, null, 2));
+  _atomicWrite(REGISTRY_PATH, JSON.stringify(reg, null, 2));
+}
+
+// ─── Concurrency lock ─────────────────────────────────────────────────────────
+
+const _LOCK_FILE  = path.join(os.homedir(), ".conxa", "install.lock");
+const _LOCK_STALE = 30 * 1000; // steal lock after 30 s
+
+function _acquireLock() {
+  fs.mkdirSync(CONXA_HOME, { recursive: true });
+  try {
+    const fd = fs.openSync(_LOCK_FILE, "wx");
+    fs.writeSync(fd, String(process.pid));
+    fs.closeSync(fd);
+  } catch (e) {
+    if (e.code !== "EEXIST") throw e;
+    try {
+      const stat = fs.statSync(_LOCK_FILE);
+      if (Date.now() - stat.mtimeMs < _LOCK_STALE)
+        throw new Error("Another conxa install/uninstall is already running.");
+      fs.unlinkSync(_LOCK_FILE);
+      _acquireLock();
+    } catch (e2) {
+      if (e2.message.startsWith("Another")) throw e2;
+    }
+  }
+}
+
+function _releaseLock() {
+  try { fs.unlinkSync(_LOCK_FILE); } catch (_) {}
 }
 
 // ─── Claude Code integration ─────────────────────────────────────────────────
@@ -48,11 +89,11 @@ function _registerGlobalMcp() {
   let claudeJson = {};
   try { claudeJson = JSON.parse(fs.readFileSync(CLAUDE_JSON, "utf8")); } catch (_) {}
   const existing = claudeJson.mcpServers && claudeJson.mcpServers.conxa;
-  if (existing && existing.args && existing.args[0] === SERVER_JS) return;
+  if (existing && existing.type === "stdio" && existing.command === "node" && existing.args && existing.args[0] === SERVER_JS) return;
   if (!claudeJson.mcpServers) claudeJson.mcpServers = {};
   claudeJson.mcpServers.conxa = { type: "stdio", command: "node", args: [SERVER_JS] };
   try {
-    fs.writeFileSync(CLAUDE_JSON, JSON.stringify(claudeJson, null, 2) + "\n", "utf8");
+    _atomicWrite(CLAUDE_JSON, JSON.stringify(claudeJson, null, 2) + "\n");
     process.stderr.write(`[conxa] Registered conxa MCP server in ${CLAUDE_JSON}\n`);
   } catch (e) {
     process.stderr.write(`[conxa] Warning: could not update .claude.json: ${e.message}\n`);
@@ -80,7 +121,7 @@ function updateGlobalClaudeMd(reg) {
   const entries = Object.values(reg);
   const pluginLines = entries.length === 0
     ? "- (no plugins installed)"
-    : entries.map(e => `- ${e.slug}  →  ~/.conxa/plugins/${e.slug}/CLAUDE.md`).join("\n");
+    : entries.map(e => `- ${e.slug}  →  ${path.join(CONXA_HOME, "plugins", e.slug, "CLAUDE.md")}`).join("\n");
 
   const content = [
     "# Conxa Runtime",
@@ -142,6 +183,7 @@ function regenerateIndex(reg) {
 function copyDirSync(src, dst) {
   fs.mkdirSync(dst, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) continue;
     const s = path.join(src, entry.name);
     const d = path.join(dst, entry.name);
     if (entry.isDirectory()) copyDirSync(s, d);
@@ -151,39 +193,60 @@ function copyDirSync(src, dst) {
 
 // ─── init ─────────────────────────────────────────────────────────────────────
 
+function _cliVersion() {
+  try { return require("../package.json").version; } catch (_) { return null; }
+}
+
 function init() {
+  const cliVersion = _cliVersion();
   if (fs.existsSync(VERSION_JSON)) {
     const v = JSON.parse(fs.readFileSync(VERSION_JSON, "utf8"));
-    process.stderr.write(`[conxa] Runtime already bootstrapped at ${RUNTIME_DIR} (v${v.version})\n`);
-    return;
+    if (!cliVersion || v.version === cliVersion) {
+      process.stderr.write(`[conxa] Runtime already at v${v.version}\n`);
+      return;
+    }
+    process.stderr.write(`[conxa] Updating runtime v${v.version} → v${cliVersion}...\n`);
+  } else {
+    process.stderr.write(`[conxa] Bootstrapping runtime at ${RUNTIME_DIR} ...\n`);
   }
-  process.stderr.write(`[conxa] Bootstrapping runtime at ${RUNTIME_DIR} ...\n`);
-
-  // All runtime files live alongside cli.js in both layouts: the in-repo
-  // template tree (app/storage/plugin_templates/runtime/) and the published
-  // npm package (packages/conxa-cli/lib/). Copy the whole directory so new
-  // files (resolver/, search.js, etc.) ship automatically without having to
-  // maintain a hardcoded allow-list.
-  fs.mkdirSync(RUNTIME_DIR, { recursive: true });
+
+  // Safe-swap: copy to RUNTIME_DIR.new/, run npm install there, then rename
+  // so a failed install never leaves a half-updated runtime.
+  const RUNTIME_NEW = RUNTIME_DIR + ".new";
+  const RUNTIME_OLD = RUNTIME_DIR + ".old";
+  if (fs.existsSync(RUNTIME_NEW)) fs.rmSync(RUNTIME_NEW, { recursive: true, force: true });
+  fs.mkdirSync(RUNTIME_NEW, { recursive: true });
+
   for (const entry of fs.readdirSync(__dirname, { withFileTypes: true })) {
-    if (entry.name === "node_modules" || entry.name === ".bootstrapped") continue;
+    if (entry.name === "node_modules" || entry.name === ".bootstrapped" || entry.isSymbolicLink()) continue;
     const src = path.join(__dirname, entry.name);
-    const dst = path.join(RUNTIME_DIR, entry.name);
+    const dst = path.join(RUNTIME_NEW, entry.name);
     if (entry.isDirectory()) copyDirSync(src, dst);
     else fs.copyFileSync(src, dst);
   }
 
   process.stderr.write("[conxa] Running npm install...\n");
-  execSync("npm install --prefer-offline --silent", { cwd: RUNTIME_DIR, stdio: ["ignore", "pipe", "inherit"] });
+  try {
+    execSync("npm install --prefer-offline --silent", { cwd: RUNTIME_NEW, stdio: ["ignore", "pipe", "inherit"] });
+  } catch (e) {
+    // Retry once without --prefer-offline in case cache is stale
+    process.stderr.write("[conxa] npm install failed, retrying without cache...\n");
+    execSync("npm install --silent", { cwd: RUNTIME_NEW, stdio: ["ignore", "pipe", "inherit"] });
+  }
 
   process.stderr.write("[conxa] Installing Playwright Chromium...\n");
-  execSync("npx playwright install chromium", { cwd: RUNTIME_DIR, stdio: ["ignore", "pipe", "inherit"] });
+  execSync("npx playwright install chromium", { cwd: RUNTIME_NEW, stdio: ["ignore", "pipe", "inherit"] });
+
+  // Atomic swap: old → .old, new → active
+  if (fs.existsSync(RUNTIME_DIR)) {
+    if (fs.existsSync(RUNTIME_OLD)) fs.rmSync(RUNTIME_OLD, { recursive: true, force: true });
+    fs.renameSync(RUNTIME_DIR, RUNTIME_OLD);
+  }
+  fs.renameSync(RUNTIME_NEW, RUNTIME_DIR);
+  if (fs.existsSync(RUNTIME_OLD)) fs.rmSync(RUNTIME_OLD, { recursive: true, force: true });
 
-  const pkg = fs.existsSync(path.join(RUNTIME_DIR, "package.json"))
-    ? JSON.parse(fs.readFileSync(path.join(RUNTIME_DIR, "package.json"), "utf8"))
-    : {};
   fs.writeFileSync(VERSION_JSON, JSON.stringify({
-    version: pkg.version || "1.0.0",
+    version: cliVersion || "1.0.0",
     installed_at: new Date().toISOString(),
     node_version: process.version,
   }, null, 2));
@@ -201,11 +264,12 @@ function init() {
   fs.writeFileSync(path.join(CONXA_HOME, ".bootstrapped"), "1", "utf8");
 
   process.stderr.write("[conxa] Bootstrap complete.\n");
+  if (cliVersion) process.stderr.write(`[conxa] Runtime is now v${cliVersion}. Restart Claude Code Desktop to apply.\n`);
 }
 
 // ─── install ──────────────────────────────────────────────────────────────────
 
-function _installFromLocalDir(pluginDir) {
+function _installFromLocalDir(pluginDir, sourceRef = null) {
   if (!pluginDir) throw new Error("install: plugin directory path required");
   const absDir = path.resolve(pluginDir);
   if (!fs.existsSync(absDir)) throw new Error(`Plugin directory not found: ${absDir}`);
@@ -218,10 +282,31 @@ function _installFromLocalDir(pluginDir) {
   if (!cfg.target_url)    throw new Error("plugin.json missing: target_url");
   if (!cfg.protected_url) throw new Error("plugin.json missing: protected_url");
 
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(cfg.slug))
+    throw new Error(`plugin.json slug "${cfg.slug}" contains invalid characters`);
+  for (const s of (cfg.skills || [])) {
+    const p = s.path || `skills/${s.slug}`;
+    if (p.includes("..") || path.isAbsolute(p))
+      throw new Error(`Skill path "${p}" is not allowed`);
+  }
+
   const slug    = cfg.slug;
   const destDir = path.join(PLUGINS_DIR, slug);
 
   process.stderr.write(`[conxa] Installing plugin '${slug}' from ${absDir}...\n`);
+  if (fs.existsSync(destDir)) {
+    // Preserve auth/ across reinstall — save and restore
+    const authDir = path.join(destDir, "auth");
+    const authSave = fs.existsSync(authDir) ? fs.readdirSync(authDir)
+      .filter(f => f !== "credentials.example.json")
+      .reduce((m, f) => { m[f] = fs.readFileSync(path.join(authDir, f)); return m; }, {}) : {};
+    fs.rmSync(destDir, { recursive: true, force: true });
+    if (Object.keys(authSave).length) {
+      fs.mkdirSync(path.join(destDir, "auth"), { recursive: true, mode: 0o700 });
+      for (const [name, buf] of Object.entries(authSave))
+        fs.writeFileSync(path.join(destDir, "auth", name), buf, { mode: 0o600 });
+    }
+  }
   fs.mkdirSync(destDir, { recursive: true });
 
   // Copy plugin manifest
@@ -255,6 +340,7 @@ function _installFromLocalDir(pluginDir) {
     protected_url: cfg.protected_url,
     skills:        skillsList,
     installed_at:  new Date().toISOString(),
+    ...(sourceRef ? { source_ref: sourceRef } : {}),
   };
   const reg = readRegistry();
   reg[slug] = entry;
@@ -279,9 +365,11 @@ function _ensureInitialized() {
 // before delegating to _installFromLocalDir.
 async function install(ref) {
   if (!ref) throw new Error("install: <ref> required (local dir, owner/repo, or plugin_id)");
+  _acquireLock();
+  try {
   _ensureInitialized();
   if (fs.existsSync(ref) && fs.statSync(ref).isDirectory()) {
-    return _installFromLocalDir(ref);
+    return _installFromLocalDir(ref, null);
   }
   // Look in cache first (already downloaded). cache.stagedDir() takes a
   // plugin_id+version pair; we accept either "id" or "id@version".
@@ -290,16 +378,17 @@ async function install(ref) {
   const ver = at > 0 ? ref.slice(at + 1) : null;
   const cache = require("./resolver/cache");
   const staged = cache.stagedDir(id, ver);
-  if (staged) return _installFromLocalDir(staged);
+  if (staged) return _installFromLocalDir(staged, ref);
   // git resolver handles owner/repo and full https URLs. It stages into cache/
   // and returns the staged directory path.
   const git = require("./resolver/git");
   const resolved = await git.resolve(ref);
-  if (resolved && resolved.staged_dir) return _installFromLocalDir(resolved.staged_dir);
+  if (resolved && resolved.staged_dir) return _installFromLocalDir(resolved.staged_dir, ref);
   // Registry resolver is contract-only today; falls through when no hosted
   // registry is configured. When implemented it would download a tarball into
   // cache/ and return the staged path.
   throw new Error(`install: could not resolve '${ref}'`);
+  } finally { _releaseLock(); }
 }
 
 // ─── search ───────────────────────────────────────────────────────────────────
@@ -344,21 +433,24 @@ function registryLogout(url) {
 
 function uninstall(slug) {
   if (!slug) throw new Error("uninstall: slug required");
-  const destDir = path.join(PLUGINS_DIR, slug);
-  if (fs.existsSync(destDir)) {
-    fs.rmSync(destDir, { recursive: true, force: true });
-    process.stderr.write(`[conxa] Removed plugin directory: ${destDir}\n`);
-  }
-  const reg = readRegistry();
-  if (reg[slug]) {
-    delete reg[slug];
-    writeRegistry(reg);
-    updateGlobalClaudeMd(reg);
-    regenerateIndex(reg);
-    process.stderr.write(`[conxa] Removed '${slug}' from registry\n`);
-  } else {
-    process.stderr.write(`[conxa] Plugin '${slug}' was not in registry\n`);
-  }
+  _acquireLock();
+  try {
+    const destDir = path.join(PLUGINS_DIR, slug);
+    if (fs.existsSync(destDir)) {
+      fs.rmSync(destDir, { recursive: true, force: true });
+      process.stderr.write(`[conxa] Removed plugin directory: ${destDir}\n`);
+    }
+    const reg = readRegistry();
+    if (reg[slug]) {
+      delete reg[slug];
+      writeRegistry(reg);
+      updateGlobalClaudeMd(reg);
+      regenerateIndex(reg);
+      process.stderr.write(`[conxa] Removed '${slug}' from registry\n`);
+    } else {
+      process.stderr.write(`[conxa] Plugin '${slug}' was not in registry\n`);
+    }
+  } finally { _releaseLock(); }
 }
 
 // ─── list ─────────────────────────────────────────────────────────────────────
@@ -381,7 +473,11 @@ async function runCli(argv) {
   const [cmd, ...rest] = argv;
   try {
     switch (cmd) {
-      case "init":      init();                  break;
+      case "init":
+      case "update":
+        if (cmd === "update" && fs.existsSync(VERSION_JSON)) fs.unlinkSync(VERSION_JSON);
+        init();
+        break;
       case "install":   await install(rest[0]);  break;
       case "uninstall": uninstall(rest[0]);      break;
       case "list":      list();                  break;
@@ -392,7 +488,7 @@ async function runCli(argv) {
         else throw new Error("registry: login <url> <token> | logout <url>");
         break;
       default:
-        process.stderr.write("Usage: conxa <init|install <ref>|uninstall <slug>|list|search <q>|registry login|registry logout>\n");
+        process.stderr.write("Usage: conxa <init|update|install <ref>|uninstall <slug>|list|search <q>|registry login|registry logout>\n");
         process.exit(1);
     }
   } catch (e) {

package/lib/config.js

@@ -21,18 +21,31 @@ function getAuthJson(slug) {
 
 function getPluginConfig(slug) {
   const cfgPath = path.join(getPluginDir(slug), "plugin.json");
-  return JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+  try { return JSON.parse(fs.readFileSync(cfgPath, "utf8")); }
+  catch (e) { throw new Error(`Plugin "${slug}" has a malformed plugin.json: ${e.message}`); }
 }
 
 function getRegistry() {
   if (!fs.existsSync(REGISTRY_PATH)) return {};
-  try { return JSON.parse(fs.readFileSync(REGISTRY_PATH, "utf8")); } catch (_) { return {}; }
+  try { return JSON.parse(fs.readFileSync(REGISTRY_PATH, "utf8")); }
+  catch (e) {
+    const bak = REGISTRY_PATH + ".bak";
+    try { fs.renameSync(REGISTRY_PATH, bak); } catch (_) {}
+    process.stderr.write(`[conxa] Warning: registry.json was corrupt (${e.message}) — backed up to registry.json.bak\n`);
+    return {};
+  }
 }
 
 function getRegistryAuth() {
-  if (!fs.existsSync(REGISTRY_AUTH_PATH)) return { registries: [] };
-  try { return JSON.parse(fs.readFileSync(REGISTRY_AUTH_PATH, "utf8")); }
-  catch (_) { return { registries: [] }; }
+  const fromEnv = process.env.CONXA_REGISTRY_TOKEN;
+  let stored = { registries: [] };
+  if (fs.existsSync(REGISTRY_AUTH_PATH)) {
+    try { stored = JSON.parse(fs.readFileSync(REGISTRY_AUTH_PATH, "utf8")); }
+    catch (_) { stored = { registries: [] }; }
+  }
+  if (fromEnv && !stored.registries.some(r => r.token === fromEnv))
+    stored.registries = [{ name: "env", url: "*", token: fromEnv }, ...stored.registries];
+  return stored;
 }
 
 function writeRegistryAuth(payload) {

package/lib/resolver/git.js

@@ -21,7 +21,10 @@ function _parseRef(ref) {
   const text = String(ref || "").trim();
   if (!text) return null;
   let m = _GH_OWNER_REPO.exec(text);
-  if (m) return { url: `https://github.com/${m[1]}/${m[2]}.git`, version: m[3] || null, id: `${m[1]}/${m[2]}` };
+  if (m) {
+    const repo = m[2].replace(/\.git$/, "");
+    return { url: `https://github.com/${m[1]}/${repo}.git`, version: m[3] || null, id: `${m[1]}/${repo}` };
+  }
   m = _GIT_URL.exec(text);
   if (m) {
     const url    = `${m[1]}.git`;
@@ -31,16 +34,31 @@ function _parseRef(ref) {
   return null;
 }
 
+function _ensureGit() {
+  try { execFileSync("git", ["--version"], { stdio: "ignore" }); }
+  catch (e) {
+    if (e.code === "ENOENT") throw new Error("git is not installed — install it to use owner/repo plugin refs");
+    throw e;
+  }
+}
+
 function _clone(url, version, destDir) {
   const args = ["clone", "--depth", "1"];
   if (version) args.push("--branch", version);
   args.push(url, destDir);
-  execFileSync("git", args, { stdio: ["ignore", "pipe", "inherit"] });
+  try {
+    execFileSync("git", args, { stdio: ["ignore", "pipe", "inherit"], timeout: 60000 });
+  } catch (e) {
+    // Clean up partial clone so the next attempt starts fresh
+    try { require("fs").rmSync(destDir, { recursive: true, force: true }); } catch (_) {}
+    throw e;
+  }
 }
 
 async function resolve(pluginRef) {
   const parsed = _parseRef(pluginRef);
   if (!parsed) return null;
+  _ensureGit();
   const version = parsed.version || "main";
   const staged = cache.stagedDir(parsed.id, version);
   if (staged) return { staged_dir: staged, plugin_id: parsed.id, version, source: "git" };
@@ -50,6 +68,7 @@ async function resolve(pluginRef) {
   } catch (e) {
     // Retry without branch if version refspec is wrong (lets us still clone HEAD)
     if (parsed.version) {
+      console.error(`[git] Branch "${parsed.version}" not found — falling back to default branch`);
       try {
         const fallback = cache.ensureStagedDir(parsed.id, "main");
         _clone(parsed.url, null, fallback);

package/lib/run.js

@@ -5,14 +5,17 @@ const { CONXA_HOME } = require("./config");
 
 // ─── Retry budget (L0) ────────────────────────────────────────────────────────
 
-const _retryBudget     = new Map();
+const _retryBudget     = new Map(); // key → { count, ts }
 const RETRY_BUDGET_MAX = 5;
+const RETRY_BUDGET_TTL = 10 * 60 * 1000; // reset after 10 min idle
 
 function checkRetryBudget(slug, stepIndex) {
-  const key      = `${slug}:${stepIndex}`;
-  const attempts = (_retryBudget.get(key) || 0) + 1;
-  _retryBudget.set(key, attempts);
-  if (attempts > RETRY_BUDGET_MAX) {
+  const key  = `${slug}:${stepIndex}`;
+  const now  = Date.now();
+  const prev = _retryBudget.get(key);
+  const count = (prev && now - prev.ts < RETRY_BUDGET_TTL) ? prev.count + 1 : 1;
+  _retryBudget.set(key, { count, ts: now });
+  if (count > RETRY_BUDGET_MAX) {
     appendRecoveryEvent({ event: "retry_budget_exhausted", slug, step_index: stepIndex });
     console.error(`[recovery] L0 budget exhausted for ${key}`);
     return false;
@@ -32,8 +35,10 @@ const RECOVERY_LOG_MAX = 10 * 1024 * 1024;
 
 function appendRecoveryEvent(event) {
   try {
-    if (fs.existsSync(RECOVERY_LOG) && fs.statSync(RECOVERY_LOG).size > RECOVERY_LOG_MAX)
+    if (fs.existsSync(RECOVERY_LOG) && fs.statSync(RECOVERY_LOG).size > RECOVERY_LOG_MAX) {
+      if (fs.existsSync(RECOVERY_LOG + ".1")) fs.renameSync(RECOVERY_LOG + ".1", RECOVERY_LOG + ".2");
       fs.renameSync(RECOVERY_LOG, RECOVERY_LOG + ".1");
+    }
     fs.appendFileSync(RECOVERY_LOG, JSON.stringify({ ts: new Date().toISOString(), ...event }) + "\n");
   } catch (_) {}
 }
@@ -224,9 +229,8 @@ async function runPlan(page, steps, inputs, startFrom, slug) {
   for (let i = startFrom; i < steps.length; i++) {
     const step = steps[i];
 
-    // Settle: wait for DOM + network before each step
+    // Settle: wait for DOM before each step
     await page.waitForLoadState("domcontentloaded", { timeout: 5000 }).catch(() => {});
-    await page.waitForLoadState("networkidle",      { timeout: 3000 }).catch(() => {});
 
     // Pre-step screenshot (interactive steps only)
     const isInteractive = INTERACTIVE.has(step.type);

package/lib/server.js

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 "use strict";
+
+// Require Node >=20
+const _nodeMajor = parseInt(process.version.slice(1), 10);
+if (_nodeMajor < 20) {
+  process.stderr.write(`[conxa] Node.js ${process.version} is too old — requires >=20. Update Node and run: npx -y @kiran_nandi_123/conxa init\n`);
+  process.exit(1);
+}
+
 const { Server }              = require("@modelcontextprotocol/sdk/server/index.js");
 const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
 const { CallToolRequestSchema, ListToolsRequestSchema } = require("@modelcontextprotocol/sdk/types.js");
@@ -12,20 +20,124 @@ const _PID_FILE = path.join(os.homedir(), ".conxa", "runtime", "server.pid");
 try { fs.writeFileSync(_PID_FILE, String(process.pid)); } catch (_) {}
 const _cleanPid = () => { try { fs.unlinkSync(_PID_FILE); } catch (_) {} };
 process.on("exit", _cleanPid);
-process.on("SIGINT",  () => process.exit(0));
-process.on("SIGTERM", () => process.exit(0));
 
 const { getPluginConfig, getPluginDir, getAuthJson, getRegistry } = require("./config");
-const { getCachedBrowser, isAuthenticated, getAuthContext, gracefulShutdown } = require("./browser");
+const { getCachedBrowser, holdBrowser, releaseBrowserHold, isAuthenticated, getAuthContext, gracefulShutdown } = require("./browser");
 const {
   appendRecoveryEvent, interpolate, enrichStepsWithRecovery,
   waitForUrlState, runPlan, runSkill, checkRetryBudget, clearRetryBudget,
 } = require("./run");
 
+// ─── Version helpers ──────────────────────────────────────────────────────────
+
+const CONXA_HOME   = path.join(os.homedir(), ".conxa");
+const VERSION_JSON = path.join(CONXA_HOME, "runtime", "version.json");
+const UPDATE_CHECK = path.join(CONXA_HOME, "last_update_check.json");
+const NPM_PACKAGE  = "@kiran_nandi_123/conxa";
+const ONE_DAY_MS   = 24 * 60 * 60 * 1000;
+
+function _semverGte(installed, required) {
+  // Strip leading 'v', split on '.', ignore pre-release suffix (pre-release < release)
+  const parse = v => String(v || "0").replace(/^v/i, "").split(".").map((p, i) =>
+    i < 3 ? (parseInt(p, 10) || 0) : 0
+  );
+  const hasPre = v => /[-+]/.test(String(v || "").replace(/^v/i, ""));
+  const a = parse(installed), b = parse(required);
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  // Equal version numbers: pre-release is less than release
+  return !hasPre(installed) || hasPre(required);
+}
+
+function _installedVersion() {
+  try { return JSON.parse(fs.readFileSync(VERSION_JSON, "utf8")).version; } catch (_) { return null; }
+}
+
+function _shouldCheckToday() {
+  try {
+    const { last_check } = JSON.parse(fs.readFileSync(UPDATE_CHECK, "utf8"));
+    return (Date.now() - last_check) > ONE_DAY_MS;
+  } catch (_) { return true; }
+}
+
+let _needsRestart = false;
+
+function _startupUpdateCheck() {
+  if (!_shouldCheckToday()) return;
+  const https = require("https");
+  const req = https.get(`https://registry.npmjs.org/${NPM_PACKAGE}/latest`, { timeout: 5000 }, (res) => {
+    let data = "";
+    res.on("data", chunk => { data += chunk; });
+    res.on("end", () => {
+      try {
+        fs.writeFileSync(UPDATE_CHECK, JSON.stringify({ last_check: Date.now() }));
+        const latest = JSON.parse(data).version;
+        const installed = _installedVersion();
+        if (!latest || !installed || installed === latest) return;
+        console.error(`[conxa] Auto-updating runtime v${installed} → v${latest}...`);
+        const { spawn } = require("child_process");
+        const proc = spawn(
+          process.execPath, ["-e", `require("child_process").execFileSync(process.execPath,[require.resolve("${NPM_PACKAGE}/lib/cli.js"),"init"],{stdio:"inherit"})`],
+          { detached: true, stdio: "ignore" }
+        );
+        proc.unref();
+        _needsRestart = true;
+        console.error(`[conxa] Update running in background. Restart Claude Code Desktop to apply v${latest}.`);
+      } catch (_) {}
+    });
+  });
+  req.on("error", () => {});
+  req.on("timeout", () => req.destroy());
+}
+
+_startupUpdateCheck();
+
+async function _pluginUpdateCheck() {
+  if (!_shouldCheckToday()) return;
+  const registry = getRegistry();
+  const https = require("https");
+  for (const [slug, entry] of Object.entries(registry)) {
+    const ref = entry.source_ref;
+    if (!ref || !/^[^/]+\/[^/]+$/.test(ref.split("@")[0])) continue;
+    if (ref.includes("@")) continue; // version-pinned — don't auto-update
+    const ownerRepo = ref.split("@")[0];
+    const [owner, repo] = ownerRepo.split("/");
+    await new Promise((resolve) => {
+      const url = `https://raw.githubusercontent.com/${owner}/${repo}/main/plugin.json`;
+      const req = https.get(url, { timeout: 5000 }, (res) => {
+        let data = "";
+        res.on("data", chunk => { data += chunk; });
+        res.on("end", () => {
+          try {
+            const latest = JSON.parse(data).version;
+            if (!latest || latest === entry.version) return resolve();
+            console.error(`[conxa] Plugin update available: ${slug} v${entry.version} → v${latest}. Run: conxa install ${ownerRepo}`);
+            resolve();
+          } catch (_) { resolve(); }
+        });
+      });
+      req.on("error", () => resolve());
+      req.on("timeout", () => { req.destroy(); resolve(); });
+    });
+  }
+}
+
+_pluginUpdateCheck().catch(() => {});
+
 // ─── Registry helpers ─────────────────────────────────────────────────────────
 
-// Returns { slug → { pluginSlug, skill, skillDir } } for fast lookup
+let _skillIndexCache = null;
+let _skillIndexMtime = 0;
+
+// Returns { slug → { pluginSlug, skill, skillDir } } — cached until registry.json changes
 function buildSkillIndex() {
+  const { REGISTRY_PATH } = require("./config");
+  try {
+    const mtime = fs.existsSync(REGISTRY_PATH) ? fs.statSync(REGISTRY_PATH).mtimeMs : 0;
+    if (_skillIndexCache && mtime === _skillIndexMtime) return _skillIndexCache;
+    _skillIndexMtime = mtime;
+  } catch (_) {}
   const registry = getRegistry();
   const index = {};
   for (const [pluginSlug, entry] of Object.entries(registry)) {
@@ -35,9 +147,17 @@ function buildSkillIndex() {
       index[key] = { pluginSlug, skill, skillDir: path.join(pluginDir, skill.path || `skills/${skill.slug}`) };
     }
   }
+  _skillIndexCache = index;
   return index;
 }
 
+function invalidateSkillIndex() { _skillIndexCache = null; }
+
+function _restartNotice() {
+  if (!_needsRestart) return null;
+  return "⚠️ Conxa runtime update is installing in the background. Restart Claude Code Desktop to apply it, then retry.";
+}
+
 function resolveSkill(pluginSlug, skillSlug, index) {
   // Exact match with plugin prefix
   if (pluginSlug) {
@@ -49,12 +169,14 @@ function resolveSkill(pluginSlug, skillSlug, index) {
         return v;
     }
   }
-  // Slug-only: match across all plugins
-  for (const v of Object.values(index)) {
-    if (v.skill.slug === skillSlug || v.skill.slug.replace(/-/g, "_") === skillSlug.replace(/-/g, "_"))
-      return v;
-  }
-  return null;
+  // Slug-only: match across all plugins — warn if ambiguous
+  const norm = s => s.replace(/-/g, "_");
+  const matches = Object.values(index).filter(v =>
+    v.skill.slug === skillSlug || norm(v.skill.slug) === norm(skillSlug)
+  );
+  if (matches.length > 1)
+    console.error(`[conxa] Warning: skill "${skillSlug}" matches multiple plugins (${matches.map(v => v.pluginSlug).join(", ")}) — using first match. Specify plugin: to disambiguate.`);
+  return matches[0] || null;
 }
 
 // ─── MCP server ───────────────────────────────────────────────────────────────
@@ -169,10 +291,27 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   return { tools };
 });
 
+
+function _checkPluginRuntimeVersion(pluginSlug) {
+  try {
+    const pluginDir = getPluginDir(pluginSlug);
+    const manifest = JSON.parse(fs.readFileSync(path.join(pluginDir, "plugin.json"), "utf8"));
+    const minVer = manifest.runtime_min_version;
+    if (!minVer) return null;
+    const installed = _installedVersion();
+    if (!installed || _semverGte(installed, minVer)) return null;
+    return `Plugin "${pluginSlug}" requires conxa runtime >=${minVer} (installed: ${installed}). Run: npx -y ${NPM_PACKAGE} install ${pluginSlug}`;
+  } catch (_) { return null; }
+}
+
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
   const skillIndex = buildSkillIndex();
 
+  // Surface restart notice on first call after a background update completes
+  const restartMsg = _restartNotice();
+  if (restartMsg) return { content: [{ type: "text", text: restartMsg }] };
+
   // ── list_skills ───────────────────────────────────────────────────────────
   if (name === "list_skills") {
     const filterPlugin = args && args.plugin ? String(args.plugin) : null;
@@ -243,7 +382,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
       const installRef = version && !ref.includes("@") ? `${ref}@${version}` : ref;
       const entry = await cli.install(installRef);
-      return { content: [{ type: "text", text: `Installed ${entry.slug} v${entry.version}. Skills: ${(entry.skills || []).map(s => s.slug).join(", ")}` }] };
+      invalidateSkillIndex();
+      return { content: [{ type: "text", text: `Installed ${entry.slug} v${entry.version}. Skills: ${(entry.skills || []).map(s => s.slug).join(", ")}. Call list_skills to see available skills.` }] };
     } catch (e) {
       return { content: [{ type: "text", text: `install_plugin failed: ${e.message}` }] };
     }
@@ -256,6 +396,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const cli = require("./cli");
     try {
       cli.uninstall(slug);
+      invalidateSkillIndex();
       return { content: [{ type: "text", text: `Uninstalled ${slug}` }] };
     } catch (e) {
       return { content: [{ type: "text", text: `uninstall_plugin failed: ${e.message}` }] };
@@ -312,6 +453,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const found     = resolveSkill(pluginArg, slug, skillIndex);
       if (!found) return { content: [{ type: "text", text: `Skill not found: ${slug}. Call list_skills.` }] };
       const { skillDir, pluginSlug } = found;
+      const versionErr = _checkPluginRuntimeVersion(pluginSlug);
+      if (versionErr) return { content: [{ type: "text", text: versionErr }] };
       const rawExec = fs.existsSync(path.join(skillDir, "execution.json"))
         ? JSON.parse(fs.readFileSync(path.join(skillDir, "execution.json"), "utf8")) : null;
       const rawRec  = fs.existsSync(path.join(skillDir, "recovery.json"))
@@ -329,6 +472,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
     // Determine which plugin to use for auth (first skill's plugin)
     const primaryPlugin = resolved[0].pluginSlug;
+    const uniquePlugins = [...new Set(resolved.map(r => r.pluginSlug))];
+    if (uniquePlugins.length > 1)
+      console.error(`[execute_plan] Warning: plan spans ${uniquePlugins.length} plugins (${uniquePlugins.join(", ")}) — only ${primaryPlugin} auth context will be used`);
 
     // ── Layer 0: Retry budget gate ────────────────────────────────────────
     if (resumeFrom > 0) {
@@ -344,6 +490,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     } catch (authErr) {
       return { content: [{ type: "text", text: String(authErr) }] };
     }
+    holdBrowser(primaryPlugin);
 
     const runtimeLog = { consoleErrors: [], pageErrors: [], failedRequests: [] };
     const page = await _context.newPage();
@@ -399,8 +546,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       // ── Success ───────────────────────────────────────────────────────────
       const authJson = getAuthJson(primaryPlugin);
       const state = await _context.storageState();
-      fs.mkdirSync(path.dirname(authJson), { recursive: true });
-      fs.writeFileSync(authJson, JSON.stringify(state, null, 2));
+      fs.mkdirSync(path.dirname(authJson), { recursive: true, mode: 0o700 });
+      fs.writeFileSync(authJson, JSON.stringify(state, null, 2), { encoding: "utf8", mode: 0o600 });
       const shot = await page.screenshot({ type: "png" }).catch(() => null);
       const url  = page.url();
       await page.close().catch(() => {});
@@ -411,6 +558,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       console.error(`[execute_plan] Done. URL: ${url}`);
       const content = [{ type: "text", text: `Done. URL: ${url}` }];
       if (shot) content.push({ type: "image", data: shot.toString("base64"), mimeType: "image/png" });
+      releaseBrowserHold(primaryPlugin);
       return { content };
 
     } catch (err) {
@@ -500,6 +648,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (runtimeLog.failedRequests.length > 0) l5.push(`Failed requests:\n${JSON.stringify(runtimeLog.failedRequests,null, 2)}`);
       content.push({ type: "text", text: l5.join("\n") });
 
+      releaseBrowserHold(primaryPlugin);
       return { content };
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kiran_nandi_123/conxa",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Conxa CLI — install and manage shared-runtime automation plugins",
   "license": "MIT",
   "bin": {

package/scripts/install.ps1

@@ -6,4 +6,14 @@ if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
     $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
 }
 
-npx -y "@kiran_nandi_123/conxa" install $PluginId
+$NpxCommand = Get-Command npx.cmd -ErrorAction SilentlyContinue
+if (-not $NpxCommand) {
+    $NpxCommand = Get-Command npx -ErrorAction SilentlyContinue
+}
+
+if (-not $NpxCommand) {
+    throw "[conxa] npx not found. Install Node.js LTS, then retry."
+}
+
+$NpxPath = if ($NpxCommand.Source) { $NpxCommand.Source } else { $NpxCommand.Path }
+& $NpxPath -y "@kiran_nandi_123/conxa" install $PluginId