zevairouter 1.0.270 → 1.1.0

package/cli/app/.worktrees/v1-1-adaptive/cli/app/src/lib/terminal/ptyBridge.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+Minimal PTY bridge for ZevaiRouter web terminal.
+
+stdin  -> PTY master (keystrokes)
+stdout <- PTY master (shell output), raw binary
+stderr  = control / errors (utf-8 text lines)
+
+Optional control on a side channel is not needed: resize arrives as
+OSC-like escape on stdin:  \\x1b]9999;<cols>;<rows>\\x07
+"""
+from __future__ import annotations
+
+import errno
+import fcntl
+import os
+import select
+import signal
+import struct
+import sys
+import termios
+
+
+def set_winsize(fd: int, rows: int, cols: int) -> None:
+    try:
+        packed = struct.pack("HHHH", max(5, rows), max(20, cols), 0, 0)
+        fcntl.ioctl(fd, termios.TIOCSWINSZ, packed)
+    except Exception:
+        pass
+
+
+def main() -> int:
+    cols = int(sys.argv[1]) if len(sys.argv) > 1 else 120
+    rows = int(sys.argv[2]) if len(sys.argv) > 2 else 40
+    shell = os.environ.get("SHELL") or ("/bin/bash" if os.path.exists("/bin/bash") else "/bin/sh")
+    cwd = os.path.expanduser("~")
+
+    pid, master = pty_fork = _fork_pty()
+    if pid == 0:
+        # child
+        try:
+            os.chdir(cwd)
+        except Exception:
+            pass
+        os.environ.setdefault("TERM", "xterm-256color")
+        os.environ.setdefault("COLORTERM", "truecolor")
+        os.environ.setdefault("FORCE_COLOR", "1")
+        try:
+            os.execv(shell, [shell, "-il"])
+        except Exception:
+            os.execv("/bin/sh", ["/bin/sh", "-i"])
+        return 1
+
+    set_winsize(master, rows, cols)
+
+    # Non-blocking master + stdin
+    for fd in (master, sys.stdin.fileno()):
+        fl = fcntl.fcntl(fd, fcntl.F_GETFL)
+        fcntl.fcntl(fd, fcntl.F_SETFL, fl | os.O_NONBLOCK)
+
+    # Binary stdout
+    stdout = sys.stdout.buffer
+    stdin = sys.stdin.buffer
+
+    resize_buf = b""
+
+    def handle_resize_escape(chunk: bytes) -> bytes:
+        """Strip and apply embedded resize escapes, return remaining bytes."""
+        nonlocal resize_buf
+        data = resize_buf + chunk
+        out = bytearray()
+        i = 0
+        while i < len(data):
+            # ESC ] 9999 ; cols ; rows BEL
+            if data[i] == 0x1B and data[i : i + 6] == b"\x1b]9999;":
+                end = data.find(b"\x07", i + 6)
+                if end < 0:
+                    resize_buf = data[i:]
+                    return bytes(out)
+                payload = data[i + 6 : end].decode("ascii", "ignore")
+                try:
+                    c_s, r_s = payload.split(";", 1)
+                    set_winsize(master, int(r_s), int(c_s))
+                except Exception:
+                    pass
+                i = end + 1
+                resize_buf = b""
+                continue
+            out.append(data[i])
+            i += 1
+        resize_buf = b""
+        return bytes(out)
+
+    alive = True
+
+    def on_chld(signum, frame):  # noqa: ARG001
+        nonlocal alive
+        alive = False
+
+    signal.signal(signal.SIGCHLD, on_chld)
+
+    try:
+        while alive:
+            try:
+                r, _, _ = select.select([master, sys.stdin.fileno()], [], [], 0.25)
+            except InterruptedError:
+                continue
+
+            if master in r:
+                try:
+                    data = os.read(master, 8192)
+                except OSError as e:
+                    if e.errno in (errno.EIO, errno.EAGAIN, errno.EWOULDBLOCK):
+                        data = b""
+                    else:
+                        break
+                if not data:
+                    # EIO often means child exited
+                    if not alive:
+                        break
+                else:
+                    stdout.write(data)
+                    stdout.flush()
+
+            if sys.stdin.fileno() in r:
+                try:
+                    data = stdin.read(8192)
+                except Exception:
+                    data = b""
+                if data is None:
+                    data = b""
+                if data == b"" and not alive:
+                    break
+                if data:
+                    cleaned = handle_resize_escape(data)
+                    if cleaned:
+                        try:
+                            os.write(master, cleaned)
+                        except OSError:
+                            break
+    finally:
+        try:
+            os.close(master)
+        except Exception:
+            pass
+        try:
+            os.waitpid(pid, 0)
+        except Exception:
+            pass
+    return 0
+
+
+def _fork_pty():
+    import pty
+
+    return pty.fork()
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except KeyboardInterrupt:
+        raise SystemExit(0)

package/cli/app/.worktrees/v1-1-adaptive/src/lib/terminal/ptyBridge.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+Minimal PTY bridge for ZevaiRouter web terminal.
+
+stdin  -> PTY master (keystrokes)
+stdout <- PTY master (shell output), raw binary
+stderr  = control / errors (utf-8 text lines)
+
+Optional control on a side channel is not needed: resize arrives as
+OSC-like escape on stdin:  \\x1b]9999;<cols>;<rows>\\x07
+"""
+from __future__ import annotations
+
+import errno
+import fcntl
+import os
+import select
+import signal
+import struct
+import sys
+import termios
+
+
+def set_winsize(fd: int, rows: int, cols: int) -> None:
+    try:
+        packed = struct.pack("HHHH", max(5, rows), max(20, cols), 0, 0)
+        fcntl.ioctl(fd, termios.TIOCSWINSZ, packed)
+    except Exception:
+        pass
+
+
+def main() -> int:
+    cols = int(sys.argv[1]) if len(sys.argv) > 1 else 120
+    rows = int(sys.argv[2]) if len(sys.argv) > 2 else 40
+    shell = os.environ.get("SHELL") or ("/bin/bash" if os.path.exists("/bin/bash") else "/bin/sh")
+    cwd = os.path.expanduser("~")
+
+    pid, master = pty_fork = _fork_pty()
+    if pid == 0:
+        # child
+        try:
+            os.chdir(cwd)
+        except Exception:
+            pass
+        os.environ.setdefault("TERM", "xterm-256color")
+        os.environ.setdefault("COLORTERM", "truecolor")
+        os.environ.setdefault("FORCE_COLOR", "1")
+        try:
+            os.execv(shell, [shell, "-il"])
+        except Exception:
+            os.execv("/bin/sh", ["/bin/sh", "-i"])
+        return 1
+
+    set_winsize(master, rows, cols)
+
+    # Non-blocking master + stdin
+    for fd in (master, sys.stdin.fileno()):
+        fl = fcntl.fcntl(fd, fcntl.F_GETFL)
+        fcntl.fcntl(fd, fcntl.F_SETFL, fl | os.O_NONBLOCK)
+
+    # Binary stdout
+    stdout = sys.stdout.buffer
+    stdin = sys.stdin.buffer
+
+    resize_buf = b""
+
+    def handle_resize_escape(chunk: bytes) -> bytes:
+        """Strip and apply embedded resize escapes, return remaining bytes."""
+        nonlocal resize_buf
+        data = resize_buf + chunk
+        out = bytearray()
+        i = 0
+        while i < len(data):
+            # ESC ] 9999 ; cols ; rows BEL
+            if data[i] == 0x1B and data[i : i + 6] == b"\x1b]9999;":
+                end = data.find(b"\x07", i + 6)
+                if end < 0:
+                    resize_buf = data[i:]
+                    return bytes(out)
+                payload = data[i + 6 : end].decode("ascii", "ignore")
+                try:
+                    c_s, r_s = payload.split(";", 1)
+                    set_winsize(master, int(r_s), int(c_s))
+                except Exception:
+                    pass
+                i = end + 1
+                resize_buf = b""
+                continue
+            out.append(data[i])
+            i += 1
+        resize_buf = b""
+        return bytes(out)
+
+    alive = True
+
+    def on_chld(signum, frame):  # noqa: ARG001
+        nonlocal alive
+        alive = False
+
+    signal.signal(signal.SIGCHLD, on_chld)
+
+    try:
+        while alive:
+            try:
+                r, _, _ = select.select([master, sys.stdin.fileno()], [], [], 0.25)
+            except InterruptedError:
+                continue
+
+            if master in r:
+                try:
+                    data = os.read(master, 8192)
+                except OSError as e:
+                    if e.errno in (errno.EIO, errno.EAGAIN, errno.EWOULDBLOCK):
+                        data = b""
+                    else:
+                        break
+                if not data:
+                    # EIO often means child exited
+                    if not alive:
+                        break
+                else:
+                    stdout.write(data)
+                    stdout.flush()
+
+            if sys.stdin.fileno() in r:
+                try:
+                    data = stdin.read(8192)
+                except Exception:
+                    data = b""
+                if data is None:
+                    data = b""
+                if data == b"" and not alive:
+                    break
+                if data:
+                    cleaned = handle_resize_escape(data)
+                    if cleaned:
+                        try:
+                            os.write(master, cleaned)
+                        except OSError:
+                            break
+    finally:
+        try:
+            os.close(master)
+        except Exception:
+            pass
+        try:
+            os.waitpid(pid, 0)
+        except Exception:
+            pass
+    return 0
+
+
+def _fork_pty():
+    import pty
+
+    return pty.fork()
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except KeyboardInterrupt:
+        raise SystemExit(0)

package/cli/app/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Unreleased
 
+# v1.1.0 (2026-08-22)
+
+## Compatibility
+- **The v1.1 provider registry now validates canonical descriptors before exposing compatibility views.** Provider identity, aliases, auth modes, formats, endpoints, model IDs, quota sources, refresh/deadline/integrity profiles, media capabilities, and dashboard metadata are checked centrally; Antigravity, Kiro, Codex, Cursor, and GitHub retain their existing public aliases and model coverage.
+- **Cross-format requests preserve the v1.1 fields their target APIs understand.** OpenAI Chat service tiers survive Responses conversion, Responses-only client metadata is stripped before Chat forwarding, and Claude adaptive thinking keeps its adaptive mode plus effort without fabricating a legacy token budget.
+- **Codex model discovery now uses the installed ZevaiRouter version and a refresh-safe authenticated retry.** Catalog requests identify ZevaiRouter, include the active account when available, persist a rotated credential before one bounded retry, expand review models, and fall back to the static catalog with sanitized diagnostics on malformed or unavailable live data.
+- **Cursor gains live model discovery and a capability-gated AgentService transport.** Plain non-streaming text turns may use the current HTTP/2 AgentService protocol, while streams, tools, images, prefill, explicit output limits, proxies, and any unsupported shape retain the proven legacy path; malformed or committed responses cannot be replayed unsafely.
+
+## Security
+- **Outbound URLs now pass one DNS-pinned trust policy.** Public fetches reject private, reserved, mixed-resolution, credential-bearing, and redirected targets; authenticated LAN providers require explicit host/CIDR and port trust, while unchanged legacy private nodes remain usable without authorizing new origins.
+- **API-key restrictions now match admission and discovery.** OpenAI and Gemini model lists, model metadata, Gemini generation paths, chat admission, and connection selection consume the same immutable model/connection policy snapshot without leaking disallowed catalog entries.
+
+## Reliability
+- **Quota progress now comes from one generation-safe server coordinator.** Concurrent dashboard subscribers share one bounded refresh, receive cached snapshots plus ordered account updates/errors/completion, preserve stale successes, reject late writes from older generations, and reconnect without launching per-account browser request storms.
+- **Dashboard data consumers now share a small stale-while-revalidate resource cache.** Provider, model, alias, CLI, combo, endpoint, and usage views deduplicate concurrent requests, abort only after the final subscriber leaves, protect newer generations from late responses, retry failures, and invalidate exact mutation keys.
+- **The Usage routing topology now renders sanitized live lifecycle events.** A bounded replayable SSE ring drives admitted, attempting, streaming, failover, terminal, degraded, and probe states; bursts batch into animation frames, completed paths expire, and reduced-motion users receive equivalent static status instead of synthetic traffic.
+- **Disabled optional services now stay absent from startup.** Core quota and token loops wait for database readiness, while Tunnel, Tailscale, MITM, Headroom, and auto-ping load only from enabled branches after an unref'd three-second delay; settings changes reconfigure only affected service state, and shutdown is idempotent. PXPIPE remains request-lazy and loads its transform only when explicitly enabled.
+- **Provider token refreshes now run through isolated provider lanes.** Kiro refreshes serialize with a three-second minimum start interval, other providers retain bounded parallelism, queued caller aborts are removed without cancelling shared upstream work, and a slow provider cannot block unrelated refreshes.
+- **Kiro streams now validate AWS EventStream integrity before trusting frames.** Message bounds, typed headers, prelude/message CRCs, exception frames, truncation, and required terminal metadata are checked incrementally; corrupt scopes enter a bounded verified-spool mode with one safe retry and five-probe recovery.
+- **Every streamed request now has one truthful terminal and one lifecycle result.** Premature EOF, transport resets, timeouts, translator failures, and provider protocol errors emit a client-format failure terminal instead of fabricating `finish_reason: "stop"` or closing silently; success, usage, account consequences, and request logs finalize at most once.
+- **Adaptive candidate admission is deterministic without weakening route constraints.** Immutable secret-free snapshots apply capability, API-key, connection-pin, quota, transport, and scoped-circuit exclusions before a weighted health/priority/quota/latency/stability score; stable legacy order and connection ID resolve ties.
+- **Provider, egress, and protocol-integrity failures now open independent bounded circuits.** Cross-account/provider evidence is required for shared scopes, half-open probes admit one request, two successful probes recover the route, failed probes back off up to five minutes, and client aborts or policy rejection never count as provider evidence.
+- **Every upstream executor call now belongs to one monotonic attempt lease under a shared three-attempt request budget.** Same-account retry, refreshed-credential replay, and account failover consume the same budget; semantic commit forbids replay, while usage, health, circuit, probe, timeout, abort, and terminal races finalize at most once.
+- **Stream deadlines now adapt by phase instead of using one fixed stall window.** Generic routes use bounded `15s/60s/60s/300s` connect/first-event/progress-idle/absolute budgets and Antigravity thinking uses `15s/240s/120s/600s`; after twenty successful observations, first-event and idle budgets learn from p95/p99 while validated environment overrides remain authoritative.
+- **Adaptive routing ships shadow-first with secret-safe telemetry.** Shadow mode compares the deterministic winner while executing the legacy account, active selection requires both the global flag and a persisted provider activation, explicit pins remain hard constraints, and a bounded lifecycle-event ring plus Prometheus counters expose decisions without credentials, prompts, responses, emails, cookies, or raw upstream errors. Active routing remains disabled by default pending local and canary acceptance.
+
+## Improvements
+- **Warm Precision stays visually intact while dashboard work mounts and decodes lazily.** Closed provider, connection, model-select, edit, and Kiro dialogs no longer keep forms, hooks, or catalogue fetches alive; non-critical provider imagery uses native lazy loading/async decoding, while modal focus, responsive sizing, and the approved routing-map language remain unchanged. This unreleased candidate still requires local owner acceptance before any version bump, push, publish, or VPS rollout.
+- **Provider connection actions now use one consistent entry point.** Every connection-capable provider exposes one `Add Connection` action, while `Open Automation` remains adjacent for automation hubs. Multi-auth providers open a compact method chooser; CodeBuddy groups OAuth, API Key, and Quota Cookie there, while single-auth providers still open their form directly. Kiro retains its specialized picker. Empty and populated provider states now share the same action component, and narrow mobile rows stack cleanly.
+- **Mobile dashboard scrolling now has a production touch regression.** The verifier exercises long Provider and Usage pages, compact dynamic viewport height, and chooser-to-OAuth handoff cleanup. Shell or modal behavior is changed only where the browser reproduction identifies a failing boundary.
+- **Mobile navigation now scrolls to every dashboard destination.** The drawer is bounded to the dynamic viewport and its navigation owns overflow, so touch users can reach System and Settings on short screens. The desktop dashboard canvas also uses the approved Neutral Warm treatment: a faint coral atmosphere with neutral grid lines instead of an orange cast.
+
+# v1.0.271 (2026-08-22)
+
+## Fixes
+- **Authenticated Kiro API keys without a CodeWhisperer profile no longer appear disconnected.** Headless Kiro keys can answer `ListAvailableProfiles` with HTTP 200 and `profiles: []`, then successfully run chat and quota requests without a `profileArn`; the provider Check and saved-connection Test paths incorrectly treated the missing optional profile as an invalid credential. Both paths now use successful completion of the authenticated profile-list probe as the validity signal while 401/403, network failures, and upstream errors remain failures. The Test path is covered through the real connection-testing flow rather than source-text assertions.
+
 # v1.0.270 (2026-08-21)
 
 ## Fixes

package/cli/app/cli/hooks/safeGlobalInstall.js

@@ -195,6 +195,15 @@ function getBinNames() {
     : [BIN_NAME];
 }
 
+function pathEntryExists(target, fsApi = fs) {
+  try {
+    fsApi.lstatSync(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function createInstallRollback(globalRoot, globalBin) {
   const packageDir = path.join(globalRoot, APP_NAME);
   if (!fs.existsSync(path.join(packageDir, "package.json"))) return null;
@@ -211,7 +220,7 @@ function createInstallRollback(globalRoot, globalBin) {
     fs.mkdirSync(binBackup, { recursive: true });
     for (const name of getBinNames()) {
       const source = path.join(globalBin, name);
-      if (!fs.existsSync(source)) continue;
+      if (!pathEntryExists(source)) continue;
       fs.cpSync(source, path.join(binBackup, name), {
         preserveTimestamps: true,
         verbatimSymlinks: true,
@@ -236,11 +245,16 @@ function restoreInstallRollback(rollback, globalRoot, globalBin) {
   forceRemoveBinLinks(globalBin);
   for (const name of getBinNames()) {
     const source = path.join(rollback.binBackup, name);
-    if (!fs.existsSync(source)) continue;
-    fs.cpSync(source, path.join(globalBin, name), {
-      preserveTimestamps: true,
-      verbatimSymlinks: true,
-    });
+    if (!pathEntryExists(source)) continue;
+    const destination = path.join(globalBin, name);
+    if (fs.lstatSync(source).isSymbolicLink()) {
+      fs.symlinkSync(fs.readlinkSync(source), destination);
+    } else {
+      fs.cpSync(source, destination, {
+        preserveTimestamps: true,
+        verbatimSymlinks: true,
+      });
+    }
   }
 }
 
@@ -249,23 +263,74 @@ function cleanupInstallRollback(rollback) {
   try { fs.rmSync(rollback.backupRoot, { recursive: true, force: true }); } catch {}
 }
 
-function readInstalledVersion(globalRoot) {
+function readInstalledPackage(globalRoot, fsApi = fs) {
   try {
     const pkgJson = path.join(globalRoot, APP_NAME, "package.json");
-    return JSON.parse(fs.readFileSync(pkgJson, "utf8")).version || null;
+    const installed = JSON.parse(fsApi.readFileSync(pkgJson, "utf8"));
+    return {
+      name: installed?.name || null,
+      version: installed?.version || null,
+    };
   } catch {
     return null;
   }
 }
 
-function packageDirExists(globalRoot) {
+function readInstalledVersion(globalRoot, fsApi = fs) {
+  return readInstalledPackage(globalRoot, fsApi)?.version || null;
+}
+
+function packageDirExists(globalRoot, fsApi = fs) {
   try {
-    return fs.existsSync(path.join(globalRoot, APP_NAME, "package.json"));
+    return fsApi.existsSync(path.join(globalRoot, APP_NAME, "package.json"));
   } catch {
     return false;
   }
 }
 
+function resolveInstallSource(opts = {}, fsApi = fs) {
+  const version = String(opts.version || "latest").replace(/^v(?=\d)/, "");
+  const exactVersion = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version);
+  if (!opts.localArtifact) {
+    const packageSpec = opts.packageSpec || `${APP_NAME}@${version}`;
+    const validVersion = version === "latest" || exactVersion;
+    if (!validVersion || packageSpec !== `${APP_NAME}@${version}`) {
+      return {
+        ok: false,
+        error: "Version must be 'latest' or an exact semantic version (for example 1.2.3).",
+      };
+    }
+    return { ok: true, kind: "registry", packageSpec, expectedVersion: exactVersion ? version : null };
+  }
+
+  if (opts.allowLocalArtifact !== true || !exactVersion) {
+    return {
+      ok: false,
+      error: "Local artifacts require explicit opt-in and an exact expected version.",
+    };
+  }
+
+  try {
+    const requested = path.resolve(String(opts.localArtifact));
+    const stat = fsApi.lstatSync(requested);
+    if (!stat.isFile() || stat.isSymbolicLink() || path.extname(requested) !== ".tgz") {
+      throw new Error("Local artifact must be a regular .tgz file, not a directory or symlink.");
+    }
+    const canonical = fsApi.realpathSync(requested);
+    if (canonical !== requested) {
+      throw new Error("Local artifact path must already be canonical and contain no symlink components.");
+    }
+    return {
+      ok: true,
+      kind: "local-artifact",
+      packageSpec: canonical,
+      expectedVersion: version,
+    };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
 /**
  * Upgrade/install without nuking the existing package first.
  *
@@ -280,25 +345,29 @@ function packageDirExists(globalRoot) {
  */
 function safeInstallGlobal(opts = {}) {
   const platform = detectPlatform();
-  const version = String(opts.version || "latest").replace(/^v(?=\d)/, "");
-  const packageSpec = opts.packageSpec || `${APP_NAME}@${version}`;
-  const validVersion = /^(?:latest|\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)$/.test(version);
-  const validPackageSpec = packageSpec === `${APP_NAME}@${version}`;
-  if (!validVersion || !validPackageSpec) {
+  const dependencies = opts.dependencies || {};
+  const fsApi = dependencies.fs || fs;
+  const runNpmImpl = dependencies.runNpm || runNpm;
+  const resolveNpmImpl = dependencies.resolveNpmForThisNode || resolveNpmForThisNode;
+  const getGlobalRootImpl = dependencies.getGlobalRoot || getGlobalRoot;
+  const getGlobalBinImpl = dependencies.getGlobalBin || getGlobalBin;
+  const spawnSyncImpl = dependencies.spawnSync || spawnSync;
+  const source = resolveInstallSource(opts, fsApi);
+  if (!source.ok) {
     return {
       ok: false,
       nodePath: process.execPath,
       npmPath: "",
       globalRoot: "",
       platform,
-      error: "Version must be 'latest' or an exact semantic version (for example 1.2.3).",
+      error: source.error,
     };
   }
-  const npmBin = resolveNpmForThisNode();
-  const globalRoot = getGlobalRoot(npmBin);
-  const globalBin = getGlobalBin(npmBin);
-  const hadPackage = packageDirExists(globalRoot);
-  const previousVersion = hadPackage ? readInstalledVersion(globalRoot) : null;
+  const npmBin = resolveNpmImpl();
+  const globalRoot = getGlobalRootImpl(npmBin);
+  const globalBin = getGlobalBinImpl(npmBin);
+  const hadPackage = packageDirExists(globalRoot, fsApi);
+  const previousVersion = hadPackage ? readInstalledVersion(globalRoot, fsApi) : null;
   let rollback = null;
 
   if (hadPackage && !opts.externalRollback) {
@@ -323,7 +392,7 @@ function safeInstallGlobal(opts = {}) {
   log(`npm:  ${npmBin}`);
   log(`global root: ${globalRoot}`);
   log(`global bin:  ${globalBin}`);
-  log(`installing:  ${packageSpec}${previousVersion ? ` (was ${previousVersion})` : ""}`);
+  log(`installing:  ${source.packageSpec}${previousVersion ? ` (was ${previousVersion})` : ""}`);
 
   // Only hard-clean when explicitly requested AND package already broken/missing.
   // Default path: overwrite in place so OOM never leaves the system without zevai.
@@ -336,14 +405,15 @@ function safeInstallGlobal(opts = {}) {
   }
 
   // Prefer registry.npmjs.org when env asks — Tencent mirrors lag and 404 new versions.
-  const installArgs = ["install", "-g", packageSpec, "--prefer-online"];
+  const installArgs = ["install", "-g", source.packageSpec];
+  if (source.kind === "registry") installArgs.push("--prefer-online");
   if (process.env.npm_config_registry) {
     /* respect user registry */
   } else if (process.env.ZEVAI_NPM_REGISTRY) {
     installArgs.push("--registry", process.env.ZEVAI_NPM_REGISTRY);
   }
 
-  let install = runNpm(npmBin, installArgs, { timeout: 600_000, stream: true });
+  let install = runNpmImpl(npmBin, installArgs, { timeout: 600_000, stream: true });
 
   // Retry once on ENOTEMPTY / rename — only THEN remove old dir
   let errText = `${install.stderr}\n${install.stdout}\n${install.error || ""}`;
@@ -352,7 +422,7 @@ function safeInstallGlobal(opts = {}) {
     try {
       forceRemoveGlobalPackage(globalRoot);
       forceRemoveBinLinks(globalBin);
-      install = runNpm(npmBin, installArgs, { timeout: 600_000, stream: true });
+      install = runNpmImpl(npmBin, installArgs, { timeout: 600_000, stream: true });
       errText = `${install.stderr}\n${install.stdout}\n${install.error || ""}`;
     } catch (error) {
       install = { ok: false, status: null, stderr: error.message, stdout: "", error };
@@ -364,7 +434,7 @@ function safeInstallGlobal(opts = {}) {
   // without uninstalling again if remnants remain.
   if (!install.ok && /Killed|ENOMEM|JavaScript heap out of memory|signal SIGKILL/i.test(errText)) {
     warn("Install killed (likely OOM). Retrying once — ensure 1–2GB swap on 2GB VPS.");
-    install = runNpm(npmBin, installArgs, { timeout: 600_000, stream: true });
+    install = runNpmImpl(npmBin, installArgs, { timeout: 600_000, stream: true });
     errText = `${install.stderr}\n${install.stdout}\n${install.error || ""}`;
   }
 
@@ -379,8 +449,8 @@ function safeInstallGlobal(opts = {}) {
       }
     }
     cleanupInstallRollback(rollback);
-    const stillThere = packageDirExists(globalRoot);
-    const stillVer = stillThere ? readInstalledVersion(globalRoot) : null;
+    const stillThere = packageDirExists(globalRoot, fsApi);
+    const stillVer = stillThere ? readInstalledVersion(globalRoot, fsApi) : null;
     return {
       ok: false,
       nodePath: process.execPath,
@@ -398,15 +468,16 @@ function safeInstallGlobal(opts = {}) {
     };
   }
 
-  const installedVersion = readInstalledVersion(globalRoot);
+  const installedPackage = readInstalledPackage(globalRoot, fsApi);
+  const installedVersion = installedPackage?.version || null;
 
   const zevaiPath = process.platform === "win32"
     ? path.join(globalBin, `${BIN_NAME}.cmd`)
     : path.join(globalBin, BIN_NAME);
 
-  const expectedVersion = version !== "latest" ? String(version).replace(/^v/, "") : null;
-  const versionMismatch = expectedVersion && installedVersion !== expectedVersion;
-  if (!installedVersion || !fs.existsSync(zevaiPath) || versionMismatch) {
+  const packageNameMismatch = source.kind === "local-artifact" && installedPackage?.name !== APP_NAME;
+  const versionMismatch = source.expectedVersion && installedVersion !== source.expectedVersion;
+  if (!installedVersion || !fsApi.existsSync(zevaiPath) || versionMismatch || packageNameMismatch) {
     let rollbackError = "";
     if (rollback) {
       try {
@@ -423,8 +494,10 @@ function safeInstallGlobal(opts = {}) {
       globalRoot,
       platform,
       version: rollback ? previousVersion || undefined : undefined,
-      error: versionMismatch
-        ? `npm installed ${installedVersion || "an unknown version"}, expected ${expectedVersion}.${rollbackError}`
+      error: packageNameMismatch
+        ? `npm installed package name ${installedPackage?.name || "unknown"}, expected ${APP_NAME}.${rollbackError}`
+        : versionMismatch
+        ? `npm installed ${installedVersion || "an unknown version"}, expected ${source.expectedVersion}.${rollbackError}`
         : `npm exited successfully but the installed package or zevai binary is incomplete.${rollbackError}`,
     };
   }
@@ -433,13 +506,13 @@ function safeInstallGlobal(opts = {}) {
 
   // Dual-node warning
   try {
-    const pathZevai = spawnSync(
+    const pathZevai = spawnSyncImpl(
       process.platform === "win32" ? "where" : "which",
       [BIN_NAME],
       { encoding: "utf8", shell: process.platform === "win32" },
     );
     const first = (pathZevai.stdout || "").trim().split(/\r?\n/)[0];
-    if (first && fs.existsSync(zevaiPath) && path.resolve(first) !== path.resolve(zevaiPath)) {
+    if (first && fsApi.existsSync(zevaiPath) && path.resolve(first) !== path.resolve(zevaiPath)) {
       warn(`PATH resolves '${BIN_NAME}' to ${first}`);
       warn(`This install put binary at     ${zevaiPath}`);
       warn("Use the Node that owns this install, or put that bin dir first in PATH.");
@@ -451,8 +524,9 @@ function safeInstallGlobal(opts = {}) {
   log(`OK ${APP_NAME}@${installedVersion || "?"} → ${zevaiPath}`);
   return {
     ok: true,
+    source: source.kind,
     version: installedVersion,
-    zevaiPath: fs.existsSync(zevaiPath) ? zevaiPath : null,
+    zevaiPath: fsApi.existsSync(zevaiPath) ? zevaiPath : null,
     nodePath: process.execPath,
     npmPath: npmBin,
     globalRoot,
@@ -543,6 +617,7 @@ module.exports = {
   printDoctor,
   detectPlatform,
   resolveNpmForThisNode,
+  resolveInstallSource,
   restoreInstallRollback,
   getGlobalRoot,
   APP_NAME,