ai-or-die 0.1.86 → 0.1.88

package/bin/ai-or-die.js

@@ -106,7 +106,12 @@ async function main() {
       port,
       auth: authToken,
       noAuth: noAuth,
-      https: options.https,
+      // Mesh terminates real TLS at the tailnet edge (the sidecar serves the
+      // <host>.ts.net cert) and reverse-proxies to a loopback backend, so in
+      // mesh mode the local server stays plain HTTP on 127.0.0.1 regardless of
+      // --https. (Mesh forces a loopback-only bind anyway, so --https's LAN
+      // secure-context role does not apply.) --https WITHOUT --mesh is unchanged.
+      https: options.mesh ? false : options.https,
       cert: options.cert,
       key: options.key,
       dev: options.dev,
@@ -158,7 +163,7 @@ async function main() {
     const app = new ClaudeCodeWebServer(serverOptions);
     await app.start();
 
-    const protocol = options.https ? 'https' : 'http';
+    const protocol = serverOptions.https ? 'https' : 'http';
     const baseUrl = `${protocol}://localhost:${port}`;
     // For localhost with auth, embed token in URL so user can just click it
     const url = authToken ? `${baseUrl}?token=${authToken}` : baseUrl;
@@ -168,8 +173,10 @@ async function main() {
       console.log(`   Auth token: \x1b[1m\x1b[33m${authToken}\x1b[0m`);
     }
 
-    // Warn if STT is enabled without HTTPS or tunnel
-    if ((serverOptions.stt || serverOptions.sttEndpoint) && !options.https && !options.tunnel) {
+    // Warn if STT is enabled without HTTPS or tunnel. Skip in mesh mode: it
+    // binds loopback-only (no LAN), the mic works on http://localhost locally,
+    // and remotely via the mesh edge's real TLS.
+    if ((serverOptions.stt || serverOptions.sttEndpoint) && !options.https && !options.tunnel && !options.mesh) {
       console.log('\n\x1b[33m⚠  STT enabled over plain HTTP \u2014 microphone only works on localhost.\x1b[0m');
       console.log('   For LAN access, restart with \x1b[1m--https\x1b[0m or \x1b[1m--tunnel\x1b[0m.');
     }
@@ -202,6 +209,9 @@ async function main() {
     // Mesh: permanent Tailscale reachability. Coexists with --tunnel (mesh for
     // owned devices, tunnel fallback for borrowed ones). Auth token stays ON.
     if (options.mesh) {
+      if (options.https) {
+        console.log('\n  \x1b[33mNote: --https is handled by the mesh edge (real .ts.net TLS); the local server stays HTTP on loopback.\x1b[0m');
+      }
       const { MeshManager } = require('../src/mesh-manager');
       const mesh = new MeshManager({
         port,

package/mesh/main.go

@@ -5,16 +5,28 @@
 // rest of the machine never joins. Enrollment is one-time via TS_AUTHKEY; the
 // node identity persists in --statedir so the key is never needed again.
 //
+// TLS: when the tailnet has HTTPS certificates enabled, the sidecar terminates
+// real `<host>.ts.net` TLS at the edge (so the advertised https:// URL is a
+// genuine browser secure context — remote mic/PWA work) and reverse-proxies to
+// the loopback backend. When certs are unavailable it degrades to plain http on
+// :80 and says so. The scheme is decided BEFORE the URL is advertised, never
+// after, because tsnet provisions the cert lazily inside the TLS handshake — a
+// post-advertise failure would otherwise hang the browser.
+//
 // stdout protocol (parsed by src/mesh-manager.js):
-//   MESH-URL https://<name>      node is up and serving
+//   MESH-URL https://<name>      node is up, serving real TLS at the edge
+//   MESH-URL http://<name>       node is up, but TLS certs unavailable (degraded)
+//   MESH-NOCERT                  hint: enable HTTPS Certificates in the tailnet
 //   MESH-NEEDLOGIN <url>         no/!valid key — operator must enroll
-//   MESH-ERR <msg>              fatal
+//   MESH-ERR <msg>               fatal
 package main
 
 import (
 	"context"
+	"crypto/tls"
 	"flag"
 	"fmt"
+	"net"
 	"net/http"
 	"net/http/httputil"
 	"net/url"
@@ -25,12 +37,33 @@ import (
 	"tailscale.com/tsnet"
 )
 
+// version is stamped at build time via -ldflags "-X main.version=<contentHash>".
+var version = "dev"
+
+const certWaitTimeout = 20 * time.Second
+
 func main() {
-	port := flag.String("port", "7777", "local ai-or-die port to expose")
+	port := flag.String("port", "7777", "local ai-or-die port to expose (loopback)")
+	backend := flag.String("backend", "", "full backend URL to proxy to (overrides --port); must be loopback")
 	host := flag.String("hostname", "aiordie", "tailnet hostname")
 	dir := flag.String("statedir", "./ts-state", "persistent node state dir")
+	showVersion := flag.Bool("version", false, "print the build version (content hash) and exit")
 	flag.Parse()
 
+	if *showVersion {
+		fmt.Println(version)
+		return
+	}
+
+	// Resolve + validate the backend target. It MUST be loopback: the sidecar is
+	// a tailnet-facing reverse proxy, and pointing it off-host would expose an
+	// arbitrary origin to the whole tailnet.
+	target, err := resolveBackend(*backend, *port)
+	if err != nil {
+		fmt.Printf("MESH-ERR %v\n", err)
+		os.Exit(1)
+	}
+
 	s := &tsnet.Server{Dir: *dir, Hostname: *host}
 	// Surface the login URL exactly once instead of tsnet's default stderr spam.
 	s.AuthKey = os.Getenv("TS_AUTHKEY")
@@ -39,27 +72,158 @@ func main() {
 	// Bring the node up; report the enroll URL if it needs login.
 	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
 	defer cancel()
-	if _, err := s.Up(ctx); err != nil {
+	st, err := s.Up(ctx)
+	if err != nil {
 		// Up blocks until authed; on timeout it's almost always missing/!key.
 		fmt.Printf("MESH-NEEDLOGIN https://login.tailscale.com/admin/settings/keys\n")
 		fmt.Printf("MESH-ERR %v\n", err)
 		os.Exit(1)
 	}
 
+	name := *host
+	if st != nil && st.Self != nil && st.Self.DNSName != "" {
+		name = strings.TrimSuffix(st.Self.DNSName, ".")
+	}
+
+	// One reverse proxy; the edge scheme it advertises to the backend is decided
+	// just below and captured by pointer so the X-Forwarded-Proto header is
+	// always accurate. The terminal client derives ws/wss from window.location,
+	// so wss works regardless; this header is hygiene for any absolute-URL or
+	// redirect the app generates (no mixed content).
+	edgeProto := "http"
+	rp := newEdgeProxy(target, name, &edgeProto)
+
+	// Decide the scheme BEFORE advertising. tsnet's ListenTLS returns a listener
+	// without provisioning the cert; the ACME work (and any failure) happens
+	// lazily inside the first TLS handshake. So we probe cert readiness up front
+	// and only advertise https:// when we are confident the handshake will work.
+	if tlsLn := tryListenTLS(ctx, s, name); tlsLn != nil {
+		edgeProto = "https"
+		// Best-effort :80 -> https redirect so a bare http:// hit is upgraded.
+		if httpLn, e := s.Listen("tcp", ":80"); e == nil {
+			go http.Serve(httpLn, redirectToHTTPS(name))
+		}
+		fmt.Printf("MESH-URL https://%s\n", name)
+		// http.Serve only returns on failure; exit non-zero so the manager
+		// (which restarts on a non-zero exit) brings the sidecar back.
+		err := http.Serve(tlsLn, rp)
+		fmt.Printf("MESH-ERR %v\n", err)
+		os.Exit(1)
+	}
+
+	// Degraded: no usable cert. Serve plain http and say so. http://<name>.ts.net
+	// is NOT a browser secure context, so remote mic/PWA will not work until the
+	// operator enables HTTPS Certificates in the tailnet admin console.
 	ln, err := s.Listen("tcp", ":80")
 	if err != nil {
 		fmt.Printf("MESH-ERR %v\n", err)
 		os.Exit(1)
 	}
-	target, _ := url.Parse("http://127.0.0.1:" + *port)
-	rp := httputil.NewSingleHostReverseProxy(target) // handles WS upgrade via hijack
+	fmt.Printf("MESH-NOCERT\n")
+	fmt.Printf("MESH-URL http://%s\n", name)
+	serveErr := http.Serve(ln, rp)
+	fmt.Printf("MESH-ERR %v\n", serveErr)
+	os.Exit(1)
+}
 
-	st, _ := s.Up(ctx)
-	name := *host
-	if st != nil && st.Self != nil && st.Self.DNSName != "" {
-		name = strings.TrimSuffix(st.Self.DNSName, ".")
+// resolveBackend builds the proxy target from --backend (preferred) or --port,
+// and rejects anything that is not an http(s) loopback origin.
+func resolveBackend(backend, port string) (*url.URL, error) {
+	raw := backend
+	if raw == "" {
+		raw = "http://127.0.0.1:" + port
 	}
-	fmt.Printf("MESH-URL https://%s\n", name)
+	u, err := url.Parse(raw)
+	if err != nil {
+		return nil, fmt.Errorf("invalid --backend %q: %v", raw, err)
+	}
+	if u.Scheme != "http" && u.Scheme != "https" {
+		return nil, fmt.Errorf("backend scheme must be http/https, got %q", u.Scheme)
+	}
+	if !isLoopbackHost(u.Hostname()) {
+		return nil, fmt.Errorf("backend host must be loopback (127.0.0.1/::1/localhost), got %q", u.Hostname())
+	}
+	// Pin "localhost" to a numeric loopback so the later proxy dial cannot be
+	// redirected off-host by a poisoned resolver / hosts file.
+	if u.Hostname() == "localhost" {
+		if p := u.Port(); p != "" {
+			u.Host = "127.0.0.1:" + p
+		} else {
+			u.Host = "127.0.0.1"
+		}
+	}
+	return u, nil
+}
 
-	_ = http.Serve(ln, rp)
+func isLoopbackHost(h string) bool {
+	if h == "localhost" {
+		return true
+	}
+	ip := net.ParseIP(h)
+	return ip != nil && ip.IsLoopback()
+}
+
+// tryListenTLS returns a TLS listener on :443 only when a cert for `name` looks
+// obtainable; otherwise nil. It first checks the tailnet's advertised cert
+// domains, then proactively warms the cert with a bounded timeout so a failure
+// surfaces here (returning nil) instead of mid-handshake later.
+func tryListenTLS(ctx context.Context, s *tsnet.Server, name string) net.Listener {
+	lc, err := s.LocalClient()
+	if err != nil {
+		return nil
+	}
+	status, err := lc.Status(ctx)
+	if err != nil || status == nil {
+		return nil
+	}
+	eligible := false
+	for _, d := range status.CertDomains {
+		if d == name {
+			eligible = true
+			break
+		}
+	}
+	if !eligible {
+		return nil
+	}
+	// Proactively obtain the cert with a bounded timeout. If the tailnet says the
+	// domain is eligible but issuance still fails (HTTPS not actually enabled,
+	// ACME hiccup), we learn it now and fall back to http rather than hanging the
+	// first browser request.
+	warmCtx, cancel := context.WithTimeout(ctx, certWaitTimeout)
+	defer cancel()
+	if _, _, err := lc.CertPair(warmCtx, name); err != nil {
+		return nil
+	}
+	ln, err := s.ListenTLS("tcp", ":443")
+	if err != nil {
+		return nil
+	}
+	return ln
+}
+
+func redirectToHTTPS(name string) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		u := "https://" + name + r.URL.RequestURI()
+		http.Redirect(w, r, u, http.StatusPermanentRedirect)
+	}
+}
+
+// newEdgeProxy builds the reverse proxy to the loopback backend. It stamps
+// X-Forwarded-Proto (read through *proto, set after the TLS decision) and
+// X-Forwarded-Host so the app never emits mixed-content links. For an https
+// loopback backend (a future self-signed local listener) it skips verification —
+// the host is already validated as loopback, so this is not a trust boundary.
+func newEdgeProxy(target *url.URL, name string, proto *string) *httputil.ReverseProxy {
+	rp := httputil.NewSingleHostReverseProxy(target)
+	orig := rp.Director
+	rp.Director = func(r *http.Request) {
+		orig(r)
+		r.Header.Set("X-Forwarded-Proto", *proto)
+		r.Header.Set("X-Forwarded-Host", name)
+	}
+	if target.Scheme == "https" {
+		rp.Transport = &http.Transport{TLSClientConfig: &tls.Config{InsecureSkipVerify: true}}
+	}
+	return rp
 }

package/mesh/main_test.go

@@ -0,0 +1,119 @@
+package main
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+)
+
+func TestResolveBackend(t *testing.T) {
+	cases := []struct {
+		name      string
+		backend   string
+		port      string
+		wantErr   bool
+		wantHost  string // expected resolved u.Host when no error
+	}{
+		{"default port → loopback", "", "7777", false, "127.0.0.1:7777"},
+		{"explicit loopback v4", "http://127.0.0.1:8080", "0", false, "127.0.0.1:8080"},
+		{"loopback v6", "http://[::1]:8080", "0", false, "[::1]:8080"},
+		{"ipv4-mapped loopback", "http://[::ffff:127.0.0.1]:8080", "0", false, "[::ffff:127.0.0.1]:8080"},
+		{"localhost normalized to 127.0.0.1", "http://localhost:9000", "0", false, "127.0.0.1:9000"},
+		{"https loopback allowed", "https://127.0.0.1:8443", "0", false, "127.0.0.1:8443"},
+		{"off-host private ip rejected", "http://10.0.0.5:80", "0", true, ""},
+		{"0.0.0.0 rejected", "http://0.0.0.0:80", "0", true, ""},
+		{"public ip rejected", "http://93.184.216.34:80", "0", true, ""},
+		{"arbitrary dns rejected", "http://evil.example.com:80", "0", true, ""},
+		{"non-loopback v6 rejected", "http://[2001:db8::1]:80", "0", true, ""},
+		{"bad scheme rejected", "ftp://127.0.0.1:80", "0", true, ""},
+		{"file scheme rejected", "file:///etc/passwd", "0", true, ""},
+		{"garbage rejected", "://nope", "0", true, ""},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			u, err := resolveBackend(c.backend, c.port)
+			if c.wantErr {
+				if err == nil {
+					t.Fatalf("expected error for backend=%q, got host=%q", c.backend, u.Host)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error for backend=%q: %v", c.backend, err)
+			}
+			if u.Host != c.wantHost {
+				t.Fatalf("backend=%q → host=%q, want %q", c.backend, u.Host, c.wantHost)
+			}
+		})
+	}
+}
+
+func TestIsLoopbackHost(t *testing.T) {
+	loop := []string{"localhost", "127.0.0.1", "127.0.0.2", "::1", "::ffff:127.0.0.1"}
+	notLoop := []string{"0.0.0.0", "10.0.0.1", "192.168.1.1", "93.184.216.34", "2001:db8::1", "example.com", ""}
+	for _, h := range loop {
+		if !isLoopbackHost(h) {
+			t.Errorf("isLoopbackHost(%q) = false, want true", h)
+		}
+	}
+	for _, h := range notLoop {
+		if isLoopbackHost(h) {
+			t.Errorf("isLoopbackHost(%q) = true, want false", h)
+		}
+	}
+}
+
+// End-to-end through the actual reverse proxy (no tailnet): a real loopback
+// backend must receive the X-Forwarded-Proto/Host the edge stamps, and the
+// pointer-captured proto must reflect the post-TLS decision.
+func TestEdgeProxyForwardsProtoAndHost(t *testing.T) {
+	var gotProto, gotHost, gotBody string
+	backend := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotProto = r.Header.Get("X-Forwarded-Proto")
+		gotHost = r.Header.Get("X-Forwarded-Host")
+		io.WriteString(w, "backend-ok")
+	}))
+	defer backend.Close()
+
+	target, _ := url.Parse(backend.URL) // 127.0.0.1 loopback
+	proto := "http"                      // default before the TLS decision
+	rp := newEdgeProxy(target, "node.tailnet.ts.net", &proto)
+	proto = "https" // edge decided real TLS AFTER constructing the proxy
+
+	front := httptest.NewServer(rp)
+	defer front.Close()
+
+	res, err := http.Get(front.URL + "/app")
+	if err != nil {
+		t.Fatalf("proxy request failed: %v", err)
+	}
+	defer res.Body.Close()
+	b, _ := io.ReadAll(res.Body)
+	gotBody = string(b)
+
+	if gotProto != "https" {
+		t.Errorf("backend saw X-Forwarded-Proto=%q, want https (pointer-captured decision)", gotProto)
+	}
+	if gotHost != "node.tailnet.ts.net" {
+		t.Errorf("backend saw X-Forwarded-Host=%q, want node.tailnet.ts.net", gotHost)
+	}
+	if gotBody != "backend-ok" {
+		t.Errorf("proxy body=%q, want backend-ok", gotBody)
+	}
+}
+
+func TestRedirectToHTTPS(t *testing.T) {
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest("GET", "http://anything/path?q=1", nil)
+	redirectToHTTPS("node.tailnet.ts.net")(rec, req)
+	if rec.Code != http.StatusPermanentRedirect {
+		t.Fatalf("status=%d, want 308", rec.Code)
+	}
+	loc := rec.Header().Get("Location")
+	if !strings.HasPrefix(loc, "https://node.tailnet.ts.net/path") || !strings.Contains(loc, "q=1") {
+		t.Fatalf("Location=%q, want https://node.tailnet.ts.net/path?q=1", loc)
+	}
+}

package/mesh-sidecar.lock.json

@@ -0,0 +1,12 @@
+{
+  "version": "1.0.0",
+  "contentHash": "fb010e2cd6a930ef7eeac0de0adaf903cdb7252815650c38eac2d72f15da6e3d",
+  "assets": {
+    "aiordie-mesh-windows-amd64.exe": "7a30a635b726e5cae694e3f48b37b329d470e8cf493ac5f025b99ea4a0fbded0",
+    "aiordie-mesh-windows-arm64.exe": "6d056c561538a40991a975e410b61b7ba4e076c456ee280744ae9ade65202dda",
+    "aiordie-mesh-linux-amd64": "2e5fd52842b67ec56647efb59ce8944bb211055b7630a19206a67b2c80b328fd",
+    "aiordie-mesh-linux-arm64": "7508a98a2762feb3405df54150a34c53028b5588b44eac504835c56a5df82822",
+    "aiordie-mesh-darwin-amd64": "d095c85d01036f3a9a529179c9ef5ca67231150bd49fc5adf1c4fb4e0d0da11b",
+    "aiordie-mesh-darwin-arm64": "8d115b8233697995dc0d7bab8f45f881bba2d37896c86cd70ea626965b1e4cb0"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-or-die",
-  "version": "0.1.86",
+  "version": "0.1.88",
   "description": "Universal AI coding terminal — Claude, Copilot, Gemini & more in your browser",
   "main": "src/server.js",
   "bin": {
@@ -22,6 +22,8 @@
     "test:longevity": "npm run test:longevity:server && npm run test:longevity:browser",
     "build:bundle": "node scripts/build-sea.js bundle",
     "build:sea": "node scripts/build-sea.js",
+    "mesh:lock": "node scripts/mesh-lock.js",
+    "mesh:lock:check": "node scripts/mesh-lock.js --check",
     "release:pr": "bash scripts/release-pr.sh"
   },
   "keywords": [

package/src/mesh-manager.js

@@ -34,12 +34,18 @@ class MeshManager {
       ? path.join(localApp, 'ai-or-die')
       : path.join(os.homedir(), '.ai-or-die');
     this.stateDir = options.stateDir || path.join(base, 'ts-state');
-    const exe = process.platform === 'win32' ? 'aiordie-mesh.exe' : 'aiordie-mesh';
-    this.sidecar = options.sidecar || path.join(base, 'bin', exe);
+    // The sidecar binary is content-addressed: its path embeds the lock's
+    // contentHash so a new build installs alongside the old one (no overwrite of
+    // a running .exe). Derived from the installer's lock + path helpers.
+    this._installer = options._installer || require('./utils/sidecar-installer');
+    this.sidecar = options.sidecar || this._sidecarPathFromLock(base);
     this.hostname = (options.hostname || `aiordie-${os.hostname()}`).toLowerCase().replace(/[^a-z0-9-]/g, '');
 
     this.proc = null;
     this.dnsName = null;
+    this.scheme = null;          // 'https' (edge TLS) or 'http' (degraded)
+    this.backend = options.backend || `http://127.0.0.1:${this.port}`;  // mesh serves plaintext loopback
+    this._lastError = null;
     this.stopping = false;
     this.retryCount = 0;
     this._totalRestarts = 0;
@@ -54,30 +60,40 @@ class MeshManager {
     console.log('\n  Connecting mesh (Tailscale userspace)...');
     this.stopping = false;
     if (!fs.existsSync(this.sidecar)) {
-      if (!(await this._ensureSidecar())) { this._printMissing(); return; }
+      if (!(await this._ensureSidecar())) { this._printMissing(this._lastError); return; }
     }
     if (!this._authKey && !this._enrolled()) { this._printNotEnrolled(); return; }
     try { fs.mkdirSync(this.stateDir, { recursive: true }); } catch (_) {}
     await this._spawn();
   }
 
+  /** Content-addressed sidecar path from the committed lock; safe fallback. */
+  _sidecarPathFromLock(base) {
+    try {
+      const lock = this._installer.loadLock();
+      return this._installer.sidecarPath(lock.contentHash);
+    } catch (_) {
+      const exe = process.platform === 'win32' ? 'aiordie-mesh.exe' : 'aiordie-mesh';
+      return path.join(base, 'bin', exe);
+    }
+  }
+
   /** Download + verify the sidecar from the matching release. Best-effort. */
   async _ensureSidecar() {
     try {
-      const { ensureSidecar } = require('./utils/sidecar-installer');
-      let version = '0.0.0';
-      try { version = require('../package.json').version; } catch (_) {}
       console.log('  [mesh] fetching sidecar binary...');
-      await ensureSidecar(version, this.sidecar);
+      await this._installer.ensureSidecar(this.sidecar);
+      this._lastError = null;
       return fs.existsSync(this.sidecar);
     } catch (e) {
+      this._lastError = e;
       if (this.dev) console.error('  [mesh] sidecar fetch failed:', e.message);
       return false;
     }
   }
 
   getStatus() {
-    return { running: this.proc !== null && !this.stopping && !!this.dnsName, publicUrl: this.dnsName ? `https://${this.dnsName}` : null };
+    return { running: this.proc !== null && !this.stopping && !!this.dnsName, publicUrl: this.dnsName ? `${this.scheme || 'https'}://${this.dnsName}` : null };
   }
 
   async stop() {
@@ -100,7 +116,7 @@ class MeshManager {
 
   _spawn() {
     return new Promise((resolve) => {
-      const args = ['--port', String(this.port), '--hostname', this.hostname, '--statedir', this.stateDir];
+      const args = ['--port', String(this.port), '--backend', this.backend, '--hostname', this.hostname, '--statedir', this.stateDir];
       // Pass the key to the sidecar via TS_AUTHKEY (enroll only); it's already
       // stripped from this process + base child env, so it reaches only this child.
       const env = this._authKey ? { ...this._childEnv, TS_AUTHKEY: this._authKey } : this._childEnv;
@@ -110,12 +126,14 @@ class MeshManager {
       this.proc.stdout.on('data', (d) => {
         const out = d.toString();
         if (this.dev) process.stdout.write(`  [mesh] ${out}`);
-        const url = out.match(/MESH-URL (https:\/\/\S+)/);
+        if (/MESH-NOCERT/.test(out)) this._printNoCert();
+        const url = out.match(/MESH-URL (https?):\/\/(\S+)/);
         if (url && !this.dnsName) {
-          this.dnsName = url[1].replace(/^https:\/\//, '');
+          this.scheme = url[1];
+          this.dnsName = url[2];
           this._authKey = null;
           this._startStabilityTimer();
-          this.onUrl(`https://${this.dnsName}`);
+          this.onUrl(`${this.scheme}://${this.dnsName}`);
           if (!done) { done = true; clearTimeout(timer); resolve(); }
         }
         if (/MESH-NEEDLOGIN/.test(out)) { this._printNotEnrolled(); if (!done) { done = true; clearTimeout(timer); resolve(); } }
@@ -129,11 +147,27 @@ class MeshManager {
     });
   }
 
-  _printMissing() {
-    console.log('\n  \x1b[33mMesh: sidecar not installed.\x1b[0m  Fetched on next release build; see docs/specs/mesh.md.');
+  _printMissing(err) {
+    const code = err && err.code;
+    const map = {
+      'unsupported-platform': `Mesh: no sidecar build for this platform (${err && err.message}).`,
+      'lock-unfinalized': 'Mesh: sidecar checksum missing from this build — upgrade ai-or-die.',
+      'assets-missing': 'Mesh: sidecar binaries for this build are not published yet — try again shortly.',
+      'network': `Mesh: could not download the sidecar — ${err && err.message}.`,
+      'checksum-mismatch': 'Mesh: sidecar checksum mismatch — refusing to run an unverified binary.',
+      'locked-binary': `Mesh: ${err && err.message} — stop any running ai-or-die mesh and retry.`,
+    };
+    const line = (code && map[code]) || 'Mesh: sidecar not installed.';
+    console.log(`\n  \x1b[33m${line}\x1b[0m  See docs/specs/mesh.md.`);
     console.log('  Continuing on localhost/devtunnel.\n');
   }
 
+  _printNoCert() {
+    console.log('\n  \x1b[33mMesh: tailnet HTTPS certificates are not enabled — serving plain http.\x1b[0m');
+    console.log('    Remote microphone (voice) and PWA install need a secure context (https).');
+    console.log('    Enable it once: \x1b[1mhttps://login.tailscale.com/admin/dns\x1b[0m → HTTPS Certificates.');
+  }
+
   _printNotEnrolled() {
     const ex = process.platform === 'win32' ? '$env:AIORDIE_TS_AUTHKEY="<key>"; ai-or-die --mesh' : 'AIORDIE_TS_AUTHKEY=<key> ai-or-die --mesh';
     console.log('\n  \x1b[1m\x1b[33mMesh: NOT ENROLLED\x1b[0m — enroll once:');