gemini-computer-use 0.2.4 → 0.4.1

package/core/agent.py

@@ -13,11 +13,17 @@ Configuration (read once at import/startup)::
     MESH_CONFIG_FILE  KEY=VALUE file used for any of the three above that is not
                       set in the environment (default:
                       ~/.config/antigravity-mesh/agent.env).  This keeps the token
-                      out of launchers such as the Windows Startup script.
+                      out of launchers such as the Windows Startup script.  Any
+                      other MESH_* key in that file is exported as well.
+    MESH_SHELL        Windows command shell: "cmd" or "git-bash" (default:
+                      PowerShell, falling back to cmd.exe when PowerShell is absent)
     MESH_WORKSPACE    base directory for relative paths (default: cwd)
     MESH_READ_ONLY    "1"/"true" -> mutating tools refuse to run
     MESH_WRITE_ROOTS  pathsep-separated list of roots allowed for writes
 
+    MESH_UPDATE_*      self-update: see core/updater.py. A running node checks for a
+                       newer GitHub release in the background and installs it
+ 
 Resilience contract:
 
 * every link failure (DNS, TLS, reset, half-open socket after sleep) is retried
@@ -31,16 +37,30 @@ Resilience contract:
 """
 
 import asyncio
+import atexit
+import faulthandler
 import json
 import logging
 import os
 import random
+import signal
+import socket
+import subprocess
 import sys
+import threading
 import time
+from typing import Optional
 
-import websockets
+try:
+    import websockets
+except ImportError as _websockets_error:      # a launcher pinned a Python without the dep
+    websockets = None                         # type: ignore[assignment]
+    _WEBSOCKETS_IMPORT_ERROR = _websockets_error
+else:
+    _WEBSOCKETS_IMPORT_ERROR = None
 
-from core import mcp_tools
+from core import domain, mcp_tools, updater
+from core import version as version_module
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
 logger = logging.getLogger("agy-agent")
@@ -48,6 +68,16 @@ logger = logging.getLogger("agy-agent")
 CONFIG_DIR = os.path.join(os.path.expanduser("~"), ".config", "antigravity-mesh")
 DEFAULT_CONFIG_FILE = os.path.join(CONFIG_DIR, "agent.env")
 
+#: Diagnostics that answer "why is this node offline?" without the tunnel. The
+#: watchdog (ops/windows/agent-watchdog.ps1) and ops/doctor.ps1 read these files,
+#: and the incident that motivated them - a launcher pinned to the Microsoft
+#: Store Python alias that left a single torn line in agent.log and kept the node
+#: offline for a day - is exactly what they prevent.
+HEARTBEAT_FILE = os.path.join(CONFIG_DIR, "agent.heartbeat")
+FAULT_FILE = os.path.join(CONFIG_DIR, "agent.fault.log")
+STOP_MARKER_FILE = os.path.join(CONFIG_DIR, "agent.stopped")
+HEARTBEAT_INTERVAL = 15.0
+
 #: Backoff cap for ordinary link failures.
 MAX_BACKOFF = 15.0
 #: Wait after the gateway rejects the token: retrying fast cannot help, but the
@@ -56,19 +86,79 @@ UNAUTHORIZED_BACKOFF = 60.0
 
 
 def read_env_file(path: str) -> dict:
-    """Parse a KEY=VALUE file; tolerates a UTF-8 BOM (Windows PowerShell 5 writes one)."""
-    values = {}
+    """Parse a KEY=VALUE file; tolerates a UTF-8 BOM (Windows PowerShell 5 writes one).
+
+    The implementation lives in :mod:`core.domain`, which reads ``domain.env`` with
+    the same rules; it is re-exported here so existing importers of
+    ``core.agent.read_env_file`` keep working and the project keeps exactly one
+    parser.
+    """
+    return domain.read_env_file(path)
+
+
+#: Hostnames that identify no machine. Android answers "localhost" to
+#: ``gethostname(2)`` for every device, and Termux has no hostname of its own, so
+#: a node that trusted it would collide with every other phone: the gateway keeps
+#: exactly one tunnel per name and the newer one evicts the older.
+_USELESS_HOSTNAMES = frozenset({"", "localhost", "localhost.localdomain", "android"})
+
+
+def android_device_name() -> str:
+    """The phone's model as a node name (``Pixel 7 Pro`` -> ``pixel7pro``).
+
+    ``getprop`` ships with Android itself, needs no root and is on PATH inside
+    Termux. A device that does not answer yields "" and the caller falls back to
+    the generic name - this helper never raises.
+    """
+    for prop in ("ro.product.model", "ro.product.device"):
+        try:
+            completed = subprocess.run(["getprop", prop], capture_output=True, timeout=5)
+        except Exception:
+            continue
+        value = (completed.stdout or b"").decode("utf-8", "replace")
+        safe = "".join(c for c in value.strip().lower() if c.isalnum() or c in "-_")
+        if safe:
+            return safe
+    return ""
+
+
+def default_node_name() -> str:
+    """Node name used when ``MESH_USER`` is not configured: the machine's name.
+
+    This used to be a personal nickname, so every node that did not set
+    ``MESH_USER`` claimed that *same* name on the shared gateway - and the gateway
+    keeps exactly one tunnel per name, evicting the previous one. Two unrelated
+    users would therefore knock each other offline in an endless loop, which is
+    precisely the flapping the instance lock exists to prevent (and that lock is
+    per machine, so it cannot help across machines). The installers already
+    register the sanitised hostname, so the agent now agrees with them.
+
+    On a phone the hostname is worse than useless - it is the same "localhost" for
+    every device - so Termux uses the device model instead, exactly as the
+    installer registers it.
+    """
     try:
-        with open(path, "r", encoding="utf-8-sig") as handle:
-            for line in handle:
-                line = line.strip()
-                if not line or line.startswith("#") or "=" not in line:
-                    continue
-                key, _, value = line.partition("=")
-                values[key.strip()] = value.strip().strip('"').strip("'")
-    except OSError:
-        pass
-    return values
+        hostname = socket.gethostname()
+    except Exception:
+        hostname = ""
+    safe = "".join(c for c in hostname.strip().lower() if c.isalnum() or c in "-_")
+    if safe in _USELESS_HOSTNAMES and domain.is_termux():
+        safe = android_device_name()
+    return safe or "node"
+
+
+def configuration_error() -> Optional[str]:
+    """Human-readable reason this node cannot connect, or None when it is usable.
+
+    An empty token is not a transient link failure: the gateway rejects the node
+    on every attempt, so retrying forever only fills agent.log and leaves a
+    broken autostart behind. The caller reports this and stops.
+    """
+    if not TOKEN:
+        return ("MESH_TOKEN is empty (environment and %s). The gateway rejects a node "
+                "without a token, so the tunnel cannot work - re-run the installer."
+                % (os.environ.get("MESH_CONFIG_FILE") or DEFAULT_CONFIG_FILE))
+    return None
 
 
 def _load_settings() -> dict:
@@ -77,9 +167,22 @@ def _load_settings() -> dict:
     def pick(key: str, default: str) -> str:
         return os.environ.get(key) or file_values.get(key) or default
 
+    # Every other MESH_* key the operator put in the same file is exported too, so
+    # one agent.env (or one Windows Startup launcher) configures the whole node:
+    # MESH_SHELL for the Windows command shell, MESH_WORKSPACE, MESH_READ_ONLY,
+    # MESH_WRITE_ROOTS, MESH_JOBS_DIR, MESH_MAX_OUTPUT_CHARS. The real environment
+    # always wins over the file.
+    for key, value in file_values.items():
+        if key.startswith("MESH_") and not os.environ.get(key):
+            os.environ[key] = value
+
     return {
-        "gateway": pick("MESH_GATEWAY", "smart-server.online"),
-        "user": pick("MESH_USER", "levra7"),
+        # The host the node dials. core.domain owns the order: the configured
+        # public domain (MESH_PUBLIC_URL, or domain.env) wins, and the legacy
+        # MESH_GATEWAY - which the loop above has just exported from agent.env - is
+        # only consulted while nothing else names a domain.
+        "gateway": domain.gateway_host(),
+        "user": pick("MESH_USER", default_node_name()),
         "token": pick("MESH_TOKEN", ""),
     }
 
@@ -105,6 +208,26 @@ def configure_from_env() -> None:
         write_roots=write_roots,
         jobs_dir=jobs_dir,
         max_output_chars=max_chars,
+        # Public shares: the node name in a share link must be the name this
+        # tunnel registers with the gateway (the gateway routes
+        # /<node>/<slug>/... back to that tunnel), so it is passed explicitly
+        # rather than left to web_share's MESH_USER fallback - which would say
+        # "anonymous" whenever the operator relied on the hostname default.
+        # ``public_url`` is not passed here: core/domain.py owns the domain.
+        web_dir=os.environ.get("MESH_WEB_DIR") or None,
+        mesh_user=USER,
+        max_share_bytes=os.environ.get("MESH_WEB_MAX_BYTES"),
+        max_shares=os.environ.get("MESH_WEB_MAX_SHARES"),
+        web_listing=os.environ.get("MESH_WEB_LISTING"),
+        # Device branch (core/device.py, core/termux.py). "auto" is the default and
+        # keeps the tools advertised on every platform - the phone-only ones then
+        # answer with a reason instead of vanishing, because the gateway's static
+        # tool surface must match this node's exactly.
+        device=os.environ.get("MESH_DEVICE") or "auto",
+        device_actions=os.environ.get("MESH_DEVICE_ACTIONS") or None,
+        capture_dir=os.environ.get("MESH_DEVICE_CAPTURE_DIR") or None,
+        device_pim=_env_flag("MESH_DEVICE_PIM"),
+        device_quick=_env_flag("MESH_DEVICE_QUICK"),
     )
 
 
@@ -113,6 +236,302 @@ def configure_from_env() -> None:
 configure_from_env()
 
 
+# ---------------------------------------------------------------------------
+# Runtime diagnostics: banner, fault log, heartbeat, clean-stop marker
+#
+# A node that never connects leaves the client with an opaque frontend error, so
+# every start records what it is: which interpreter, which websockets, from which
+# directory. The heartbeat makes "the agent runs but is not connected" visible to
+# the watchdog, and the absence of a clean-stop marker tells it that the process
+# was killed instead of shutting down.
+# ---------------------------------------------------------------------------
+
+_RUNTIME_FACTS = None
+_FAULT_HANDLE = None
+
+#: Live state reported through the heartbeat. Written by the event loop and read
+#: by the heartbeat thread; plain dict operations are atomic enough under the GIL
+#: and a lost update only costs one cycle of freshness.
+_HEARTBEAT_STATE = {
+    "connected": False,
+    "connects": 0,
+    "last_tool": "",
+    "last_tool_at": 0.0,
+    "last_error": "",
+    "started_at": 0.0,
+}
+
+
+def runtime_facts() -> dict:
+    """Interpreter, dependency and location facts of this agent process."""
+    global _RUNTIME_FACTS
+    if _RUNTIME_FACTS is None:
+        version = getattr(websockets, "__version__", "MISSING") if websockets else "MISSING"
+        _RUNTIME_FACTS = {
+            "python": "%d.%d.%d" % sys.version_info[:3],
+            "interpreter": sys.executable or "",
+            "websockets": version,
+            "node_version": version_module.__version__,
+        }
+    facts = dict(_RUNTIME_FACTS)
+    # Read fresh: tests (and a re-configured process) may change these.
+    facts["gateway"] = GATEWAY_HOST
+    facts["user"] = USER
+    return facts
+
+
+def log_runtime_banner() -> dict:
+    """Log one line naming the interpreter a launcher actually started.
+
+    The Windows incident produced no such line: the launcher ran the Microsoft
+    Store alias, which printed ``Python `` and exited, so nothing in the log said
+    which interpreter was expected.
+    """
+    facts = runtime_facts()
+    logger.info("Runtime: node=%s interpreter=%s python=%s websockets=%s cwd=%s pid=%s",
+                facts.get("node_version") or version_module.__version__,
+                facts["interpreter"] or "<unknown>", facts["python"],
+                facts["websockets"], os.getcwd(), os.getpid())
+    if _WEBSOCKETS_IMPORT_ERROR is not None:
+        logger.error("The 'websockets' package is not importable by this interpreter (%s): %s. "
+                     "The tunnel cannot start; run: %s -m pip install websockets",
+                     facts["interpreter"] or "<unknown>", _WEBSOCKETS_IMPORT_ERROR,
+                     facts["interpreter"] or "python")
+    if "\\WindowsApps\\" in facts["interpreter"] or "/WindowsApps/" in facts["interpreter"]:
+        logger.error("This agent runs through the Microsoft Store 'python.exe' alias (%s). That alias "
+                     "stops working after a Store repair or an update; the installer must pin a real "
+                     "interpreter instead.", facts["interpreter"])
+    return facts
+
+
+def write_heartbeat(path: Optional[str] = None, **extra) -> dict:
+    """Atomically refresh the heartbeat file read by the watchdog and the doctor."""
+    target = path or HEARTBEAT_FILE
+    payload = {"ts": time.time(), "pid": os.getpid()}
+    payload.update(runtime_facts())
+    payload.update(_HEARTBEAT_STATE)
+    payload.update(extra)
+    try:
+        directory = os.path.dirname(target)
+        if directory:
+            os.makedirs(directory, exist_ok=True)
+        temporary = target + ".tmp"
+        with open(temporary, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, ensure_ascii=False, sort_keys=True)
+            handle.write("\n")
+        os.replace(temporary, target)
+    except Exception as exc:                   # diagnostics never break the tunnel
+        logger.debug("Could not write the heartbeat %s: %s", target, exc)
+    return payload
+
+
+def read_heartbeat(path: Optional[str] = None) -> dict:
+    """The last heartbeat, or an empty dict when there is none or it is unreadable."""
+    target = path or HEARTBEAT_FILE
+    try:
+        with open(target, "r", encoding="utf-8") as handle:
+            data = json.load(handle)
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def heartbeat_age(path: Optional[str] = None) -> float:
+    """Seconds since the last heartbeat; ``inf`` when there is none."""
+    try:
+        return max(0.0, time.time() - float(read_heartbeat(path).get("ts")))
+    except Exception:
+        return float("inf")
+
+
+def mark_connected(connected: bool, reason: str = "") -> None:
+    """Record the tunnel state for the heartbeat."""
+    _HEARTBEAT_STATE["connected"] = bool(connected)
+    if connected:
+        _HEARTBEAT_STATE["connects"] = int(_HEARTBEAT_STATE.get("connects", 0)) + 1
+        _HEARTBEAT_STATE["last_error"] = ""
+    elif reason:
+        _HEARTBEAT_STATE["last_error"] = str(reason)[:300]
+
+
+def start_heartbeat(path: Optional[str] = None, interval: float = HEARTBEAT_INTERVAL):
+    """Start the daemon heartbeat thread (it must never keep the process alive)."""
+    _HEARTBEAT_STATE["started_at"] = time.time()
+    write_heartbeat(path)
+
+    def _beat():
+        while True:
+            time.sleep(interval)
+            write_heartbeat(path)
+
+    thread = threading.Thread(target=_beat, name="mesh-heartbeat", daemon=True)
+    thread.start()
+    return thread
+
+
+def enable_fault_log(path: Optional[str] = None) -> Optional[str]:
+    """Send fatal-error tracebacks (native crash, deadlock) to their own file.
+
+    Without this the only trace of an abnormal end is a torn line in agent.log.
+    """
+    global _FAULT_HANDLE
+    target = path or FAULT_FILE
+    try:
+        directory = os.path.dirname(target)
+        if directory:
+            os.makedirs(directory, exist_ok=True)
+        _FAULT_HANDLE = open(target, "a", encoding="utf-8")
+        faulthandler.enable(file=_FAULT_HANDLE, all_threads=True)
+    except Exception as exc:
+        logger.debug("Could not enable the fault log %s: %s", target, exc)
+        return None
+    return target
+
+
+def write_stop_marker(reason: str = "stop") -> None:
+    """Record a clean stop: a missing marker means the process was killed."""
+    try:
+        directory = os.path.dirname(STOP_MARKER_FILE)
+        if directory:
+            os.makedirs(directory, exist_ok=True)
+        with open(STOP_MARKER_FILE, "w", encoding="utf-8") as handle:
+            handle.write("%s pid=%s reason=%s\n"
+                         % (time.strftime("%Y-%m-%dT%H:%M:%S"), os.getpid(), reason))
+    except Exception:
+        pass
+
+
+def install_exit_markers() -> None:
+    """Write the clean-stop marker on a normal exit or on a received signal."""
+    atexit.register(write_stop_marker, "atexit")
+
+    def _on_signal(signum, _frame):
+        write_stop_marker("signal=%s" % signum)
+        raise SystemExit(0)
+
+    for name in ("SIGINT", "SIGTERM", "SIGBREAK"):
+        number = getattr(signal, name, None)
+        if number is None:
+            continue
+        try:
+            signal.signal(number, _on_signal)
+        except Exception:
+            continue
+
+
+# ---------------------------------------------------------------------------
+# Self-update
+#
+# The updater itself lives in core/updater.py and is deliberately unaware of this
+# module: it can check, download, verify and swap a payload with no agent around
+# (ops/update.ps1 and the CLI drive it that way). What only the agent can do is
+# stop cleanly so the swapped code is what runs next - that is the hook below.
+# ---------------------------------------------------------------------------
+
+#: The updater's last answer, carried in every heartbeat so ops/doctor.ps1 can
+#: show "a newer release exists" (or "the last check failed") without a network.
+_UPDATE_STATE: dict = {}
+_RESTART_EVENT = threading.Event()
+
+
+def note_update_state(result: dict) -> None:
+    """Record one updater answer in the heartbeat."""
+    if not isinstance(result, dict):
+        return
+    check = result.get("check") if isinstance(result.get("check"), dict) else result
+    payload = {
+        "current": check.get("current") or version_module.__version__,
+        "latest": check.get("latest") or "",
+        "available": bool(check.get("update_available")),
+        "checked_at": check.get("checked_at") or "",
+        "reason": str(check.get("reason") or "")[:200],
+    }
+    applied = result.get("apply")
+    if isinstance(applied, dict) and applied.get("applied"):
+        payload["applied"] = applied.get("to") or ""
+    _UPDATE_STATE.clear()
+    _UPDATE_STATE.update(payload)
+    _HEARTBEAT_STATE["update"] = dict(_UPDATE_STATE)
+    write_heartbeat()
+
+
+def request_restart(delay: float = 5.0) -> bool:
+    """Stop this agent (once) so the restart helper can start the updated copy.
+
+    The delay is what lets an in-flight tool result reach the caller: a
+    ``mesh_update`` call answers "applied and restarting" and only then does the
+    process leave, which is also what releases the tunnel and the instance lock
+    the new agent needs.
+    """
+    if _RESTART_EVENT.is_set():
+        return False
+    _RESTART_EVENT.set()
+    name = "SIGBREAK" if os.name == "nt" else "SIGTERM"
+    number = getattr(signal, name, None)
+    if number is None:
+        number = getattr(signal, "SIGTERM", None)
+
+    def _fire():
+        time.sleep(max(0.0, delay))
+        logger.warning("Stopping this agent so the updated version can start (signal %s).", name)
+        try:
+            signal.raise_signal(number)
+        except Exception:
+            # A platform without raise_signal still has to end up updated; the
+            # restart helper is already waiting for this pid either way.
+            os._exit(0)
+
+    threading.Thread(target=_fire, name="mesh-restart", daemon=True).start()
+    return True
+
+
+def start_update_thread():
+    """Check for a newer release in the background and install it.
+
+    The first check is delayed (``MESH_UPDATE_INITIAL_DELAY``, 90 s by default)
+    so a node that was just started - including one that was just updated - gets
+    its tunnel up and serves a few calls before anything restarts.
+    """
+    config = updater.config_from_env()
+    if not config["enabled"]:
+        logger.info("Self-update is disabled (MESH_UPDATE_CHECK=0).")
+        return None
+    # Registered even when automatic updating is off: an operator (or the model
+    # through mesh_update) can still ask for an update, and the node then has to
+    # stop itself for the new version to run.
+    updater.set_restart_hook(request_restart)
+    try:
+        initial = float(os.environ.get("MESH_UPDATE_INITIAL_DELAY", "") or 90.0)
+    except ValueError:
+        initial = 90.0
+
+    def _loop():
+        time.sleep(max(0.0, initial))
+        while True:
+            try:
+                result = updater.background_tick(config=config)
+                note_update_state(result)
+                check = result.get("check") or {}
+                applied = result.get("apply") or {}
+                if applied.get("applied"):
+                    logger.warning("Self-update: %s -> %s applied from %s; restarting.",
+                                   applied.get("from"), applied.get("to"), applied.get("asset"))
+                elif check.get("update_available"):
+                    logger.info("Self-update: release %s is available (%s).",
+                                check.get("latest"), check.get("reason"))
+                elif check.get("ok"):
+                    logger.debug("Self-update: up to date (%s).", check.get("current"))
+                else:
+                    logger.warning("Self-update check failed: %s", check.get("reason"))
+            except Exception as exc:      # the updater must never take the node down
+                logger.warning("Self-update iteration failed: %s", exc)
+            time.sleep(max(60, int(config["interval"])))
+
+    thread = threading.Thread(target=_loop, name="mesh-updater", daemon=True)
+    thread.start()
+    return thread
+
+
 # ---------------------------------------------------------------------------
 # Single instance per node name
 # ---------------------------------------------------------------------------
@@ -171,7 +590,14 @@ def wait_for_instance_lock(user: str) -> InstanceLock:
 async def handle_tool_call(name: str, args: dict) -> dict:
     """Forward one tool call to the shared implementation in a worker thread."""
     logger.info("Executing %s", name)
-    return await asyncio.to_thread(mcp_tools.call_tool, name, args or {})
+    _HEARTBEAT_STATE["last_tool"] = name or ""
+    _HEARTBEAT_STATE["last_tool_at"] = time.time()
+    try:
+        return await asyncio.to_thread(mcp_tools.call_tool, name, args or {})
+    finally:
+        # A heartbeat right after every call makes "the agent is alive and served
+        # this tool" visible to the watchdog without reading the tunnel state.
+        write_heartbeat()
 
 
 async def _serve_call(ws, req_id, params: dict) -> None:
@@ -182,6 +608,7 @@ async def _serve_call(ws, req_id, params: dict) -> None:
     except Exception as tool_exc:
         # A tool must never take the tunnel down with it.
         logger.warning(f"Tool {tool_name} failed: {tool_exc}")
+        _HEARTBEAT_STATE["last_error"] = "%s: %s" % (type(tool_exc).__name__, tool_exc)
         res = {"error": f"{type(tool_exc).__name__}: {tool_exc}"}
     try:
         await ws.send(json.dumps({"id": req_id, "result": res}, ensure_ascii=False))
@@ -189,6 +616,8 @@ async def _serve_call(ws, req_id, params: dict) -> None:
         # The link dropped while the tool ran; the gateway already failed the
         # call, and the reconnect loop restores the tunnel.
         logger.warning(f"Could not deliver result of {tool_name}: {send_exc}")
+        _HEARTBEAT_STATE["last_error"] = "send failed: %s" % send_exc
+        write_heartbeat()
 
 
 def _is_unauthorized(exc: BaseException) -> bool:
@@ -212,6 +641,25 @@ def _is_unauthorized(exc: BaseException) -> bool:
     return status in (401, 403)
 
 
+def _looks_like_dns_failure(exc: BaseException) -> bool:
+    """True when the connection failed because the gateway name did not resolve.
+
+    A wrong or dead gateway domain produced an endless stream of generic
+    "Connection lost" lines, which reads like a network outage. Naming the cause
+    once is the difference between a five-minute fix and a long hunt.
+    """
+    if isinstance(exc, socket.gaierror):
+        return True
+    text = str(exc).lower()
+    return any(marker in text for marker in (
+        "name or service not known",       # Linux getaddrinfo
+        "nodename nor servname",           # BSD / macOS
+        "getaddrinfo failed",              # Windows
+        "temporary failure in name resolution",
+        "no address associated with hostname",
+    ))
+
+
 def tunnel_uri() -> str:
     """Canonical tunnel URL: one shared domain, node selected by ?user=."""
     base = GATEWAY_HOST.rstrip("/")
@@ -242,6 +690,8 @@ async def run_agent():
                                             max_size=None) as ws:
                 logger.info(f"Connected to Mesh Gateway as '{USER}'!")
                 backoff = 1.0                      # healthy again
+                mark_connected(True)
+                write_heartbeat()
                 async for raw_msg in ws:
                     try:
                         data = json.loads(raw_msg)
@@ -259,10 +709,19 @@ async def run_agent():
         except asyncio.CancelledError:
             raise
         except Exception as e:
+            # The heartbeat is how a watchdog - and an operator reading the files
+            # later - can tell "running but disconnected" from "not running".
+            mark_connected(False, "%s: %s" % (type(e).__name__, e))
+            write_heartbeat()
             if _is_unauthorized(e):
                 delay = UNAUTHORIZED_BACKOFF
                 logger.error("Gateway rejected node '%s' (4001 Unauthorized): the token is wrong or the "
                              "node was removed. Re-run the installer. Retrying in %.0fs.", USER, delay)
+            elif _looks_like_dns_failure(e):
+                delay = min(backoff, MAX_BACKOFF) + random.uniform(0, 0.5)
+                logger.error("Gateway '%s' does not resolve (%s). Check the gateway name (MESH_GATEWAY) "
+                             "and this machine's DNS. Retrying in %.0fs.", GATEWAY_HOST, e, delay)
+                backoff = min(backoff * 2, MAX_BACKOFF)
             else:
                 delay = min(backoff, MAX_BACKOFF) + random.uniform(0, 0.5)
                 logger.warning(f"Connection lost: {e}. Reconnecting in {delay:.1f}s...")
@@ -271,11 +730,37 @@ async def run_agent():
 
 
 def main() -> None:
+    # Fail fast on a configuration that can never work, instead of retrying the
+    # gateway every 60 seconds forever from a Windows Startup launcher.
+    problem = configuration_error()
+    if problem:
+        logger.error("%s Refusing to start.", problem)
+        sys.exit(2)
+    install_exit_markers()
+    enable_fault_log()
+    log_runtime_banner()
+    # An update that was interrupted mid-swap (a kill, a power cut) is settled
+    # here, before the tunnel starts: either finished or rolled back.
+    recovery = updater.recover_pending()
+    if recovery:
+        logger.warning("Self-update recovery: %s", recovery)
+    start_heartbeat()
+    if _WEBSOCKETS_IMPORT_ERROR is not None:
+        # The banner above already named the interpreter and the missing module.
+        logger.error("Refusing to start: this interpreter cannot import 'websockets'.")
+        sys.exit(3)
     _lock = wait_for_instance_lock(USER)  # held for the life of the process
+    write_heartbeat()
+    logger.info("Instance lock acquired: this is the only agent for node '%s'.", USER)
+    # Only the agent that owns the node updates it: a second instance waiting for
+    # the lock must not swap files under the process that is actually running.
+    start_update_thread()
     try:
         asyncio.run(run_agent())
     except KeyboardInterrupt:
         sys.exit(0)
+    finally:
+        write_heartbeat(stopping=True)
 
 
 if __name__ == "__main__":

package/core/agent_harness.py

@@ -7,8 +7,15 @@ from core.triggers import create_mesh_watchdog_trigger, create_config_trigger
 from core.policies import get_mesh_policies, ALLOWED_WORKSPACES
 from core.subagents import get_mesh_subagents, get_root_capabilities_config
 
-DEFAULT_SAVE_DIR = "/root/agy-gdrive-runner/.state/sessions"
-DEFAULT_APP_DATA_DIR = "/root/agy-gdrive-runner/.state/artifacts"
+# Derived from the coordinator workspace so the harness works wherever that root
+# is: the documented /root/agy-gdrive-runner on Linux, %USERPROFILE%\agy-gdrive-runner
+# on Windows. A hardcoded POSIX literal was rejected there by the SDK
+# ("app_data_dir must be an absolute path") because os.path.isabs('/root/...') is
+# False on Windows. os.path.abspath keeps it absolute even if the operator pointed
+# MESH_COORDINATOR_WORKSPACE at a relative path.
+_COORDINATOR_ROOT = os.path.abspath(ALLOWED_WORKSPACES[0])
+DEFAULT_SAVE_DIR = os.path.join(_COORDINATOR_ROOT, ".state", "sessions")
+DEFAULT_APP_DATA_DIR = os.path.join(_COORDINATOR_ROOT, ".state", "artifacts")
 
 ROOT_SYSTEM_INSTRUCTIONS = (
     "You are the Root Orchestrator for the Antigravity Remote Execution Mesh. "