gemini-computer-use 0.2.3 → 0.4.1

package/gateway.py

@@ -1,4 +1,6 @@
 import asyncio
+import base64
+from collections import deque
 from contextlib import asynccontextmanager
 import datetime
 import hmac
@@ -26,11 +28,81 @@ logger = logging.getLogger("gateway")
 
 REGISTRY_PATH = "/etc/antigravity-mesh/registry.json"
 active_tunnels = {}  # user -> {"ws": WebSocket, "pending": {req_id: Future}}
-active_sse_subscribers = {}  # user -> set of asyncio.Queue
-active_sse_sessions = {}  # session_id -> asyncio.Queue
+# user -> list of asyncio.Queue, OLDEST stream first. This was a set, which has
+# no order: the per-user cap below has to evict the OLDEST stream, and every
+# other reader (broadcast, /health, the watchdog) only iterates or measures the
+# container, so the type change stays invisible outside this module.
+active_sse_subscribers = {}
+active_sse_sessions = {}  # per-connection stream_key -> asyncio.Queue
+# client-visible session id -> queues opened under it. active_sse_sessions is
+# keyed per CONNECTION on purpose (one DELETE must not close a stream another
+# connection is still reading), so this second index is what lets a
+# re-initialize close exactly the streams of the session it replaces.
+active_sse_session_queues = {}
 active_sessions = {}  # session_id -> user, issued once per initialize
 latest_session_by_user = {}  # user -> most recently issued session id
 
+# A client that lost its session id opens a new stream every turn and never
+# closes the old one (observed: 9 abandoned streams for one user while no tunnel
+# was connected). Nothing above this many streams for one user is kept: the
+# oldest is closed, because the newest is the one the client just opened.
+# MESH_MAX_SSE_PER_USER raises the cap for a deployment whose clients legitimately
+# keep several streams open; the default stays deliberately small.
+try:
+    MAX_SSE_PER_USER = max(1, int(os.environ.get("MESH_MAX_SSE_PER_USER") or "2"))
+except (TypeError, ValueError):
+    MAX_SSE_PER_USER = 2
+
+# Tunnel lifecycle history for /health. "node_online: false" alone does not say
+# WHEN the node was last seen, which is the first question after an unexpected
+# reboot; the ring buffer is bounded so a long-lived gateway cannot grow.
+last_tunnel_seen = None  # ISO-8601 timestamp of the last successful connection
+TUNNEL_EVENTS_MAX = 10
+tunnel_events = deque(maxlen=TUNNEL_EVENTS_MAX)  # newest last
+
+
+def record_tunnel_event(event: str, user: str, reason: str = "") -> None:
+    """Record one tunnel connect/disconnect and stamp the last connect time."""
+    global last_tunnel_seen
+    ts = datetime.datetime.now(datetime.timezone.utc).isoformat()
+    if event == "connect":
+        last_tunnel_seen = ts
+    tunnel_events.append({"ts": ts, "event": event, "user": user, "reason": reason})
+
+
+def forget_sse_queue(user: str, queue) -> None:
+    """Unregister a queue from the per-user list and from the session index.
+
+    Shared by the stream's own cleanup and the DELETE teardown so both keep the
+    two containers in step; a stream that is still registered after it stopped
+    being readable is exactly the leak ``/health`` is meant to expose.
+    """
+    subscribers = active_sse_subscribers.get(user)
+    if subscribers is not None and queue in subscribers:
+        subscribers.remove(queue)
+    for session_id, queues in list(active_sse_session_queues.items()):
+        if queue in queues:
+            queues.remove(queue)
+            if not queues:
+                active_sse_session_queues.pop(session_id, None)
+
+
+def close_sse_streams_for_session(session_id: str) -> int:
+    """Close every SSE stream opened under a session id that is now superseded.
+
+    ``None`` is the sentinel the stream loop treats as "close this stream", the
+    same one the DELETE teardown and the per-user cap use; the stream's own
+    ``finally`` does the unregistering, so nothing is removed here. Returns how
+    many streams were asked to close.
+    """
+    queues = active_sse_session_queues.pop(session_id, [])
+    for queue in queues:
+        try:
+            queue.put_nowait(None)
+        except Exception:
+            pass
+    return len(queues)
+
 # Negotiated protocol version per user. The value must be identical in the
 # initialize result AND in the mcp-protocol-version header of every response: a
 # client that asked for 2025-11-25 and reads 2024-11-05 back in the header can
@@ -69,12 +141,32 @@ BROADCAST_HTTP_RESPONSES = os.environ.get(
 #   SSE      https://<shared-domain>/sse?user=<node>&token=<token>
 #   HTTP     https://<shared-domain>/mcp?user=<node>&token=<token>
 #   Tunnel   wss://<shared-domain>/ws/tunnel?user=<node>&token=<token>
-# Override the shared domain with MESH_PUBLIC_URL (or AGY_PUBLIC_BASE_URL).
-PUBLIC_BASE_URL = (
-    os.environ.get("MESH_PUBLIC_URL")
-    or os.environ.get("AGY_PUBLIC_BASE_URL")
-    or "https://smart-server.online"
-).strip().rstrip("/")
+# Override the shared domain with MESH_PUBLIC_URL (or its AGY_PUBLIC_BASE_URL
+# alias), or with the domain file - core/domain.py owns that order and holds the
+# single default, so the domain is configured in exactly one place.
+try:
+    from core import domain as _domain
+except Exception:  # pragma: no cover - gateway.py installed without core/ beside it
+    _domain = None
+
+if _domain is not None:
+    PUBLIC_BASE_URL = _domain.public_base_url()
+else:
+    # gateway.py is sometimes installed on its own (for example
+    # /opt/antigravity-mesh/gateway.py with no core/ next to it). Shipping
+    # core/domain.py alongside it is part of the deployment; this branch only keeps
+    # the service starting when that was forgotten, and it refuses to invent a
+    # domain of its own - the project default lives in core/domain.py alone.
+    PUBLIC_BASE_URL = (
+        os.environ.get("MESH_PUBLIC_URL") or os.environ.get("AGY_PUBLIC_BASE_URL") or ""
+    ).strip().rstrip("/")
+    if not PUBLIC_BASE_URL:
+        logger.error(
+            "core/domain.py is not importable and neither MESH_PUBLIC_URL nor "
+            "AGY_PUBLIC_BASE_URL is set: the public domain is unknown, so URLs handed "
+            "to clients will be relative. Install core/domain.py next to gateway.py, or "
+            "set the domain in the domain file / environment."
+        )
 PUBLIC_HOST = urlparse(PUBLIC_BASE_URL).netloc or PUBLIC_BASE_URL
 
 # Legacy per-device subdomain resolution. Kept only so URLs handed out before the
@@ -281,7 +373,12 @@ async def call_remote_tool(user: str, name: str, args: dict) -> dict:
         # The agent reconnects within ~2s of a dropped link (VPN flap, network
         # change, service restart), so give it a moment instead of reporting the
         # node as offline immediately. A missing agent is then a rare answer.
-        for _ in range(16):                      # up to ~8 seconds
+        #
+        # A host reboot is NOT a flap, though: the agent stays away for minutes,
+        # while the client's own frontend gives a tool call roughly 30 s. Waiting
+        # 8 s only made the eventual failure arrive later. 4 x 0.5 s covers a real
+        # reconnect and keeps the whole tools/call path within ~5 s.
+        for _ in range(4):                       # up to ~2 seconds
             await asyncio.sleep(0.5)
             tunnel = active_tunnels.get(user)
             if tunnel and tunnel.get("ws"):
@@ -290,9 +387,9 @@ async def call_remote_tool(user: str, name: str, args: dict) -> dict:
         return {
             "exit_code": 1,
             "stdout": "",
-            "stderr": (f"[Mesh Gateway] Node '{user}' did not come back within 8 seconds - the agent "
-                       f"on the host is not connected. Start/restart the mesh agent there, then retry; "
-                       f"this is a transport problem, not a missing file or permission.")
+            "stderr": (f"[Mesh Gateway] Node '{user}' has no active tunnel: the mesh agent on the "
+                       f"host is not connected to the gateway. Start/restart the mesh agent there, "
+                       f"then retry; this is a transport problem, not a missing file or permission.")
         }
     req_id = str(uuid.uuid4())
     fut = asyncio.get_running_loop().create_future()
@@ -317,7 +414,7 @@ async def call_remote_tool(user: str, name: str, args: dict) -> dict:
         # Wait for the agent to come back and replay the call once instead of
         # failing the client's request.
         logger.warning(f"Tunnel call to '{user}' failed ({e}); waiting for reconnect and retrying once")
-        for _ in range(20):                      # up to ~10 seconds
+        for _ in range(4):                       # up to ~2 seconds
             await asyncio.sleep(0.5)
             fresh = active_tunnels.get(user)
             if fresh and fresh.get("ws") and fresh.get("ws") is not tunnel.get("ws"):
@@ -372,8 +469,16 @@ async def health(request: Request):
         "active_tunnels_count": len(active_tunnels),
         # Diagnostics: an abandoned SSE stream keeps a queue alive, and a client
         # with a connection cap would then be unable to open a new one.
+        # `open_sse_streams` is the total, `streams_per_user` the same count
+        # broken down per node - both unchanged in meaning, now fed by the
+        # insertion-ordered per-user container.
         "open_sse_streams": sum(len(q) for q in active_sse_subscribers.values()),
         "streams_per_user": {u: len(q) for u, q in active_sse_subscribers.items()},
+        # Tunnel lifecycle. `node_online: false` does not say when the node was
+        # last seen, which is what tells a reboot apart from a network flap;
+        # `tunnel_events` keeps the last 10 connect/disconnect events and why.
+        "last_tunnel_seen": last_tunnel_seen,
+        "tunnel_events": list(tunnel_events),
     }, headers={"Access-Control-Allow-Origin": "*"})
 
 async def api_register(request: Request):
@@ -428,7 +533,10 @@ async def api_register(request: Request):
                     "sse_url": public_url("/sse", u, token),
                     "tunnel_url": f"wss://{PUBLIC_HOST}/ws/tunnel?user={u}&token={token}",
                     "reused": True,
-                    "instructions": f"Antigravity Mesh node '{user}'. Direct access to the real remote host over a reverse tunnel. "
+                    # `u` is the loop variable above; `user` does not exist in this
+                    # branch, so every re-registration of an already-known MAC
+                    # raised NameError and the gateway answered HTTP 500.
+                    "instructions": f"Antigravity Mesh node '{u}'. Direct access to the real remote host over a reverse tunnel. "
                 f"Do not guess paths or outputs: use list_dir/glob_find/grep_search/read_file/bash_exec/"
                 f"system_vitals. Use run_job for slow commands; page output with max_chars+cursor."
                 })
@@ -573,36 +681,82 @@ async def sse_endpoint(request: Request):
     # the stream over it - the stream it was reading tool results from.
     announce_endpoint = announce_endpoint_for_path(request.url.path)
     queue = asyncio.Queue()
-    if user not in active_sse_subscribers:
-        active_sse_subscribers[user] = set()
-    active_sse_subscribers[user].add(queue)
+    queues = active_sse_subscribers.setdefault(user, [])
+    queues.append(queue)
+    # Cap the streams one user may hold. Nothing in the protocol closes a stream
+    # a client forgot, so a client whose session id was lost (or that reconnects
+    # on every turn) accumulates queues until its own connection limit is reached
+    # and it can no longer open one at all. Evicting the OLDEST is safe: the
+    # newest is the stream the client just opened and is actually reading.
+    evicted = 0
+    while len(queues) > MAX_SSE_PER_USER:
+        oldest = queues.pop(0)
+        evicted += 1
+        try:
+            oldest.put_nowait(None)      # sentinel: the stream loop closes on None
+        except Exception:
+            pass
+        # Also drop it from the session index now, so /health and a later
+        # re-initialize never see a stream that was already closed.
+        forget_sse_queue(user, oldest)
     # stored under the per-connection key, not the shared client-visible id
     active_sse_sessions[stream_key] = queue
+    # ...and indexed by the client-visible session id, so a re-initialize can
+    # close exactly the streams of the session it replaces.
+    active_sse_session_queues.setdefault(session_id, []).append(queue)
     logger.info(
         f"SSE stream opened for '{user}' (stream_key={stream_key}, "
         f"session={session_id[:12]}…, path={request.url.path}, "
-        f"open_now={len(active_sse_subscribers[user])})"
+        f"open_now={len(queues)}"
+        + (f", evicted={evicted} over the cap of {MAX_SSE_PER_USER}" if evicted else "")
+        + ")"
     )
 
     async def event_generator():
+        # Keepalive deadline: intermediaries (nginx, Google's frontend) close an
+        # idle stream, and a closed stream is what makes a client believe the
+        # server went away. One frame - a comment counts - goes out at least every
+        # 15 s. Framing is untouched: `event: endpoint` once, then one
+        # `event: message` per queued frame.
+        keepalive_interval = 15.0
+        last_write = time.monotonic()
         try:
             if announce_endpoint:
                 yield f"event: endpoint\ndata: /messages?user={user}&token={token}\n\n"
             while True:
                 try:
-                    msg = await asyncio.wait_for(queue.get(), timeout=15.0)
-                    if msg is None:
+                    remaining = keepalive_interval - (time.monotonic() - last_write)
+                    msg = await asyncio.wait_for(queue.get(), timeout=max(0.25, remaining))
+                except asyncio.TimeoutError:
+                    try:
+                        yield ": keepalive\n\n"
+                    except Exception as exc:
+                        # The write raised: nobody is reading this stream any
+                        # more, so drop it instead of keeping the queue alive.
+                        logger.warning(f"SSE keepalive write failed for '{user}' "
+                                       f"(stream_key={stream_key}): {exc}")
                         break
+                    last_write = time.monotonic()
+                    continue
+                except Exception as exc:
+                    logger.warning(f"SSE queue unreadable for '{user}' "
+                                   f"(stream_key={stream_key}): {exc}")
+                    break
+                if msg is None:
+                    break
+                try:
                     yield f"event: message\ndata: {msg}\n\n"
-                except asyncio.TimeoutError:
-                    yield ": keepalive\n\n"
+                except Exception as exc:
+                    logger.warning(f"SSE write failed for '{user}' "
+                                   f"(stream_key={stream_key}): {exc}")
+                    break
+                last_write = time.monotonic()
         except asyncio.CancelledError:
             logger.info(f"SSE stream cancelled for '{user}' (stream_key={stream_key})")
             raise
         finally:
             active_sse_sessions.pop(stream_key, None)
-            if user in active_sse_subscribers and queue in active_sse_subscribers[user]:
-                active_sse_subscribers[user].remove(queue)
+            forget_sse_queue(user, queue)
             logger.info(f"SSE stream closed for '{user}' (stream_key={stream_key}, "
                         f"open_now={len(active_sse_subscribers.get(user, ()))})")
 
@@ -700,6 +854,20 @@ async def messages_endpoint(request: Request):
         else:
             negotiated = "2024-11-05"
         active_protocol_versions[user] = negotiated
+        # Session hygiene: this initialize replaces whatever session this user
+        # held before, and the client will never use that id again. Leaving its
+        # streams open is how one user ended up with 9 live streams and no
+        # tunnel - the client lost the session id, re-initialized every turn, and
+        # every abandoned stream stayed registered (and counted in /health).
+        # The response-header contract is untouched: the NEW id is what this
+        # response returns.
+        previous_session_id = latest_session_by_user.get(user)
+        if previous_session_id:
+            closed = close_sse_streams_for_session(previous_session_id)
+            active_sessions.pop(previous_session_id, None)
+            if closed:
+                logger.info(f"initialize: closed {closed} superseded SSE stream(s) of session "
+                            f"{previous_session_id[:12]}… for user '{user}'")
         session_id = issue_session_id(user)
         issued_session_id = session_id
         logger.info(f"initialize: client requested protocolVersion={client_version!r} "
@@ -731,7 +899,11 @@ async def messages_endpoint(request: Request):
                 f"REACHABILITY: every tool result you receive in this conversation was produced ON the "
                 f"node, so the node IS online. After any successful tool result, never tell the user the "
                 f"host is unreachable or that the agent did not answer. If a call fails, report its exact "
-                f"error text instead of guessing that the host is down."
+                f"error text instead of guessing that the host is down.\n"
+                f"DEVICE: if system_info reports a 'device' block whose class is phone or tablet, prefer "
+                f"device_info / device_control for device-level work instead of hand-writing termux-* "
+                f"commands through bash_exec, and ask the user before any device_capture or "
+                f"device_messages call."
             )
             )
             )
@@ -750,8 +922,10 @@ async def messages_endpoint(request: Request):
     elif method == "ping":
         resp["result"] = {}
     elif method == "tools/list":
+        # annotate_tools attaches the confirmation policy (read-only / local
+        # write / publish / destructive) declared at the bottom of this file.
         resp["result"] = {
-            "tools": [
+            "tools": annotate_tools([
                 {
                     "name": "list_dir",
                     "description": (
@@ -787,8 +961,13 @@ async def messages_endpoint(request: Request):
                     "name": "bash_exec",
                     "description": (
                         f"Execute a shell command directly on {user}'s host machine. "
-                        "MANDATORY: Always use this tool to inspect git status, run builds, check processes, or execute tasks. "
-                        "NEVER guess command outputs."
+                        "The shell follows the host: bash on Linux/macOS, PowerShell or cmd.exe "
+                        "on Windows - call system_info first and match command_shell. "
+                        "Use it to inspect git status, run builds, check processes or run tasks, "
+                        "and NEVER guess command outputs. Commands that install or remove "
+                        "software, or that delete data, are refused here: this tool runs without "
+                        "a confirmation dialog, so those must go through system_change, where the "
+                        "user is asked to confirm first."
                     ),
                     "inputSchema": {
                         "type": "object",
@@ -801,12 +980,288 @@ async def messages_endpoint(request: Request):
                         "required": ["command"]
                     }
                 },
+                {
+                    "name": "system_change",
+                    "description": (
+                        "Install or remove software, or delete data, on the host - the only tool "
+                        "allowed to run those commands, and the one the user is asked to confirm "
+                        "before it runs. Same shell as bash_exec (check command_shell from "
+                        "system_info first). Use it for package managers (apt/dnf/pacman/apk/brew/"
+                        "pip/npm/winget/msiexec/...), uninstallers, rm / Remove-Item / del, disk "
+                        "wipes and anything else that installs, removes or destroys. Set "
+                        "background=true for long installs and poll with job_output. Ordinary "
+                        "inspection, builds and tests belong in bash_exec / run_job instead."
+                    ),
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "command": {"type": "string",
+                                        "description": "The install / remove / delete command"},
+                            "timeout_sec": {"type": "integer",
+                                            "description": "Foreground only: 1-120 seconds (default 25)"},
+                            "background": {"type": "boolean",
+                                           "description": "Run it as a background job and return a job_id"},
+                            "cwd": {"type": "string",
+                                    "description": "Working directory; background=true only"},
+                            "max_chars": {"type": "integer",
+                                          "description": "Maximum characters per response"},
+                            "cursor": {"type": "integer",
+                                       "description": "Character offset to continue from"}
+                        },
+                        "required": ["command"]
+                    }
+                },
                 {
                     "name": "mesh_status",
                     "description": ("Confirm this node is reachable. Call this FIRST if you believe the "
                                     "host is offline: it returns live evidence from the host."),
                     "inputSchema": {"type": "object", "properties": {}, "required": []}
                 },
+                {
+                    "name": "mesh_update",
+                    "description": ("Report, check for, or install a newer release of the node's own "
+                                    "code. action=status reads local state; action=check asks GitHub; "
+                                    "action=apply installs it and restarts the agent (the tunnel "
+                                    "drops for a few seconds). Default action is status."),
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "action": {"type": "string", "enum": ["status", "check", "apply"],
+                                       "description": "What to do (default: status)"},
+                            "force": {"type": "boolean",
+                                      "description": "Ignore the check interval and the failed-apply backoff"},
+                            "offline": {"type": "boolean",
+                                        "description": "check: cached answer only, no network"},
+                            "restart": {"type": "boolean",
+                                        "description": "apply: restart the node afterwards (default true)"}
+                        },
+                        "required": []
+                    }
+                },
+                # The node's own device (a phone/tablet under Termux, or the local
+                # laptop/desktop). core/mcp_tools.TOOLS is the SOURCE OF TRUTH for
+                # these four entries: their descriptions and schemas below are copied
+                # from it value for value (only the layout is the gateway's own - it
+                # deploys as one file and may not import node code). The node is what
+                # actually executes, and the client reads this copy, so any wording
+                # difference here would be a lie the model acts on. Keep them in step;
+                # tests/test_gateway_share_route.py pins the copy for these four.
+                {
+                    "name": "device_info",
+                    "description": (
+                        "One-call report for the device this node runs on: battery and charging, "
+                        "network interfaces with Wi-Fi and cellular signal strength, language, time and "
+                        "timezone, CPU, RAM, storage, cameras, microphones, sensors and what the platform "
+                        "can actually reach. On an Android/Termux node it reads the phone through the "
+                        "termux-api commands; on a laptop or desktop it reads the local system. Every "
+                        "section carries available/source, so 'not exposed here' is never reported as a "
+                        "zero - and on a non-phone the phone-only sections explain themselves instead of "
+                        "failing. Use device_control, device_capture or device_messages to act."
+                    ),
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "section": {
+                                "type": "string",
+                                "enum": ["summary", "all", "device", "battery", "network", "locale",
+                                         "time", "hardware", "storage", "cameras", "microphones",
+                                         "sensors", "capabilities"],
+                                "description": "Which blocks to return (default: all)."
+                            },
+                            "sensor": {
+                                "type": "string",
+                                "description": ("Name one sensor to take a single live sample from "
+                                                "(Android only; needs a name from the sensors block).")
+                            },
+                            "fresh": {
+                                "type": "boolean",
+                                "description": "Bypass the short-lived cache (default false)."
+                            },
+                            "quick": {
+                                "type": "boolean",
+                                "description": ("Skip the slow sections: network, cameras, microphones, "
+                                                "sensors (default false).")
+                            }
+                        },
+                        "additionalProperties": False
+                    }
+                },
+                {
+                    "name": "device_control",
+                    "description": (
+                        "Reversible actions on the node's own device: torch, vibrate, volume, screen "
+                        "brightness, text-to-speech, toast, notifications, clipboard, media playback, "
+                        "media scan, wake lock, download, opening or sharing a file, a text dialog and "
+                        "the wallpaper. Each action is a fixed termux-api command on Android and an "
+                        "explained no-op elsewhere; the result names the command and its argv so nothing "
+                        "is guessed. Nothing here is destructive, and all of it is refused when the node "
+                        "runs with MESH_READ_ONLY=1."
+                    ),
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "action": {
+                                "type": "string",
+                                "enum": ["torch", "vibrate", "volume", "volume_get", "brightness",
+                                         "tts_speak", "toast", "notify", "notify_list",
+                                         "notify_remove", "clipboard_get", "clipboard_set", "media",
+                                         "media_scan", "wakelock", "download", "open", "share",
+                                         "dialog", "wallpaper"],
+                                "description": "Action to perform."
+                            },
+                            "on": {
+                                "type": "boolean",
+                                "description": "torch: true lights it, false puts it out."
+                            },
+                            "value": {
+                                "type": "integer",
+                                "description": ("vibrate: milliseconds; volume: level 0-15; "
+                                                "brightness: 0-255.")
+                            },
+                            "stream": {
+                                "type": "string",
+                                "enum": ["music", "call", "alarm", "notification", "ring", "system"],
+                                "description": "volume: which audio stream (default music)."
+                            },
+                            "text": {
+                                "type": "string",
+                                "description": ("tts_speak/toast/notify/clipboard_set/dialog body; media: "
+                                                "play|pause|stop|info.")
+                            },
+                            "title": {
+                                "type": "string",
+                                "description": "notify/dialog: heading text."
+                            },
+                            "id": {
+                                "type": "string",
+                                "description": "notify_remove: the id the notification was posted with."
+                            },
+                            "url": {
+                                "type": "string",
+                                "description": "download/open/wallpaper: URL to use."
+                            },
+                            "path": {
+                                "type": "string",
+                                "description": "open/share/media/download/media_scan/wallpaper: file on the node."
+                            },
+                            "state": {
+                                "type": "string",
+                                "enum": ["acquire", "release", "status"],
+                                "description": "wakelock: what to do (default status)."
+                            },
+                            "timeout_sec": {
+                                "type": "integer",
+                                "description": "dialog: seconds to wait for the person (5-120, default 30)."
+                            }
+                        },
+                        "required": ["action"],
+                        "additionalProperties": False
+                    }
+                },
+                {
+                    "name": "device_capture",
+                    "description": (
+                        "Camera, microphone, location, fingerprint, USB and infrared actions. These "
+                        "observe the physical world or authenticate the person holding the phone, so the "
+                        "client always asks for confirmation first. A photo or a recording is written to "
+                        "the node's capture directory and is never uploaded anywhere by itself; "
+                        "fingerprint returns only the verdict, never biometric data; USB access requests "
+                        "permission and returns the descriptor but deliberately refuses to run a program "
+                        "for you; and on Android 11+ the Termux:API app has to be in the foreground for a "
+                        "recording. Refused when MESH_READ_ONLY=1."
+                    ),
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "action": {
+                                "type": "string",
+                                "enum": ["camera_list", "camera_photo", "mic_record_start",
+                                         "mic_record_stop", "mic_record_status", "location",
+                                         "fingerprint", "usb_list", "usb_access",
+                                         "infrared_frequencies", "infrared_transmit"],
+                                "description": "Capture action to perform."
+                            },
+                            "camera_id": {
+                                "type": "integer",
+                                "description": "camera_photo: id from camera_list (default 0)."
+                            },
+                            "path": {
+                                "type": "string",
+                                "description": ("camera_photo/mic_record_start: output file (default: the "
+                                                "node's capture directory); usb_access: device path from "
+                                                "usb_list.")
+                            },
+                            "seconds": {
+                                "type": "integer",
+                                "description": "mic_record_start: recording length limit in seconds."
+                            },
+                            "provider": {
+                                "type": "string",
+                                "enum": ["gps", "network", "passive"],
+                                "description": "location: which Android provider to use (default gps)."
+                            },
+                            "frequency": {
+                                "type": "integer",
+                                "description": "infrared_transmit: carrier frequency in Hz."
+                            },
+                            "pattern": {
+                                "type": "string",
+                                "description": ("infrared_transmit: durations in microseconds, e.g. "
+                                                "1000,2000,1000.")
+                            }
+                        },
+                        "required": ["action"],
+                        "additionalProperties": False
+                    }
+                },
+                {
+                    "name": "device_messages",
+                    "description": (
+                        "SMS, call log, contacts and placing a call. This is private data about the person "
+                        "who owns the phone, so the client asks for confirmation AND the node refuses "
+                        "until its operator enables it with MESH_DEVICE_PIM=1. The refusal names the flag "
+                        "and the Android permissions to grant, so the answer is an instruction rather than "
+                        "a dead end. Sending an SMS and placing a call are also refused under "
+                        "MESH_READ_ONLY=1."
+                    ),
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "action": {
+                                "type": "string",
+                                "enum": ["sms_list", "sms_send", "call_log", "contacts", "call"],
+                                "description": "Message or PIM action to perform."
+                            },
+                            "number": {
+                                "type": "string",
+                                "description": "sms_send/call: recipient number."
+                            },
+                            "text": {
+                                "type": "string",
+                                "description": "sms_send: message body."
+                            },
+                            "limit": {
+                                "type": "integer",
+                                "description": "How many records (1-50, default 10)."
+                            },
+                            "offset": {
+                                "type": "integer",
+                                "description": "Record offset, for paging."
+                            },
+                            "type": {
+                                "type": "string",
+                                "description": ("sms_list/call_log: filter, e.g. inbox/sent or "
+                                                "incoming/outgoing/missed.")
+                            },
+                            "query": {
+                                "type": "string",
+                                "description": "contacts: filter by name or number."
+                            }
+                        },
+                        "required": ["action"],
+                        "additionalProperties": False
+                    }
+                },
                 {
                     "name": "system_info",
                     "description": ("One-call host summary: OS, desktop, user, home, disks, memory, load, "
@@ -827,7 +1282,11 @@ async def messages_endpoint(request: Request):
                 {
                     "name": "write_file",
                     "description": (
-                        "Write a file atomically (creates parent dirs)."
+                        "Write a file atomically (creates parent dirs). Runs without a "
+                        "confirmation dialog, so a path inside the system - /etc, /usr, "
+                        "/boot, /var/lib, C:\\Windows, C:\\Program Files, ProgramData, the "
+                        "registry - is refused and has to go through system_write, which "
+                        "the user is asked to confirm."
                     ),
                     "inputSchema": {
                         "type": "object",
@@ -843,7 +1302,10 @@ async def messages_endpoint(request: Request):
                 {
                     "name": "edit_file",
                     "description": (
-                        "Replace an exact string in a file; old_string must be unique."
+                        "Replace an exact string in a file; old_string must be unique. Runs "
+                        "without a confirmation dialog, so a system path is refused here - "
+                        "read the file and write the whole new content with system_write "
+                        "instead, which the user confirms."
                     ),
                     "inputSchema": {
                         "type": "object",
@@ -857,6 +1319,27 @@ async def messages_endpoint(request: Request):
                         "required": ["path", "old_string", "new_string"]
                     }
                 },
+                {
+                    "name": "system_write",
+                    "description": (
+                        "Write a file inside a system path - /etc, /usr, /boot, /var/lib, "
+                        "C:\\Windows, C:\\Program Files, ProgramData, the registry - the only "
+                        "way to write there, and the one the user is asked to confirm before "
+                        "it runs. Takes the exact content, like write_file (no shell "
+                        "quoting). To change an existing system file, read_file it first and "
+                        "send the full new content here."
+                    ),
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "path": {"type": "string", "description": "System path to write"},
+                            "content": {"type": "string", "description": "Exact file content to write"},
+                            "create_dirs": {"type": "boolean", "description": "Create parent directories"},
+                            "mode": {"type": "string", "description": "File mode, e.g. 0644 (POSIX only)"}
+                        },
+                        "required": ["path", "content"]
+                    }
+                },
                 {
                     "name": "grep_search",
                     "description": (
@@ -893,7 +1376,9 @@ async def messages_endpoint(request: Request):
                 {
                     "name": "run_job",
                     "description": (
-                        "Start a long command in the background; returns job_id."
+                        "Start a long command in the background; returns job_id. Installs, "
+                        "removals and deletions are refused here (this tool has no confirmation "
+                        "step) - run those with system_change(background=true)."
                     ),
                     "inputSchema": {
                         "type": "object",
@@ -939,7 +1424,7 @@ async def messages_endpoint(request: Request):
                         "limit": {"type": "integer", "description": "How many jobs to return (1-50, default 20)"}
                     }, "required": []}
                 }
-            ]
+            ] + SHARE_TOOL_SPECS)
         }
     elif method == "tools/call":
         name = params.get("name")
@@ -956,10 +1441,33 @@ async def messages_endpoint(request: Request):
             else:
                 parts = ["[NODE REACHABLE] This answer was produced on the host itself - the mesh "
                          "agent and the tunnel are working. Do not claim the node is offline."]
-                for key in ("hostname", "agent_pid", "checked_at", "host_uptime_human", "workspace"):
+                for key in ("hostname", "agent_pid", "checked_at", "host_uptime_human",
+                            "workspace", "node_version"):
                     if res.get(key) is not None:
                         parts.append(f"{key}: {res.get(key)}")
                 content_text = "\n".join(parts)
+        elif name == "mesh_update":
+            res = await call_remote_tool(user, name, args)
+            err = remote_tool_error(res)
+            if err:
+                is_error = True
+                content_text = f"[Error] {err}"
+            else:
+                parts = []
+                if res.get("current"):
+                    parts.append(f"node version: {res['current']}")
+                if res.get("latest"):
+                    parts.append(f"newest release: {res['latest']}")
+                if res.get("update_available") is not None:
+                    parts.append("update available: %s"
+                                 % ("yes" if res.get("update_available") else "no"))
+                if res.get("applied"):
+                    parts.append("applied: %s -> %s"
+                                 % (res.get("current"), res.get("latest")))
+                    parts.append("node is restarting; the tunnel drops for a few seconds")
+                elif res.get("reason"):
+                    parts.append(f"detail: {res['reason']}")
+                content_text = "\n".join(parts) if parts else json.dumps(res, ensure_ascii=False, indent=2)
         elif name == "system_info":
             res = await call_remote_tool(user, name, args)
             err = remote_tool_error(res)
@@ -968,14 +1476,19 @@ async def messages_endpoint(request: Request):
                 content_text = f"[Error] {err}"
             else:
                 parts = []
+                # command_shell tells the model which shell bash_exec really uses
+                # (PowerShell or cmd.exe on Windows, bash on Linux), so it writes
+                # commands for the right one instead of assuming bash.
                 for key in ("hostname", "os", "kernel", "user", "home", "desktop",
-                            "session_type", "wallpaper", "wallpaper_exists"):
+                            "session_type", "command_shell", "scenario", "device_class",
+                            "wallpaper", "wallpaper_exists"):
                     value = res.get(key)
                     if value not in (None, ""):
                         parts.append("%s: %s" % (key, value))
                 for key in ("memory", "load", "disks", "top_processes"):
                     if res.get(key):
                         parts.append("\n[%s]\n%s" % (key, res.get(key)))
+                parts.extend(_device_report_lines(res))
                 content_text = "\n".join(parts) if parts else json.dumps(res, ensure_ascii=False, indent=2)
         elif name == "system_vitals":
             res = await call_remote_tool(user, name, args)
@@ -985,56 +1498,51 @@ async def messages_endpoint(request: Request):
             else:
                 content_text = json.dumps(res, ensure_ascii=False, indent=2)
         elif name in ("bash_exec", "list_dir", "read_file"):
-            # Gateway-level guard: call_remote_tool gives up after 28s, so never forward
-            # a bash timeout longer than 25s (node may default to 25 anyway).
+            refusal = ""
             if name == "bash_exec":
-                timeout_sec = args.get("timeout_sec")
-                if isinstance(timeout_sec, (int, float)) and timeout_sec > 25:
-                    args = dict(args)
-                    args["timeout_sec"] = 25
-            res = await call_remote_tool(user, name, args)
-            if "error" in res:
+                kind = classify_command(args.get("command"))
+                if kind:
+                    # Installs and deletions only run through system_change, which the
+                    # client confirms; this tool is advertised as read-only.
+                    refusal = command_confirmation_message(args.get("command", ""), kind, "bash_exec")
+                else:
+                    # Gateway-level guard: call_remote_tool gives up after 28s, so never
+                    # forward a bash timeout longer than 25s (the node defaults to 25).
+                    timeout_sec = args.get("timeout_sec")
+                    if isinstance(timeout_sec, (int, float)) and timeout_sec > 25:
+                        args = dict(args)
+                        args["timeout_sec"] = 25
+            if refusal:
+                is_error = True
+                content_text = refusal
+            else:
+                res = await call_remote_tool(user, name, args)
+                content_text, is_error = format_command_result(res, name)
+        elif name in ("write_file", "edit_file"):
+            if is_system_path(args.get("path")):
+                # The unconfirmed file tools never touch the system: that is what
+                # system_write exists for, and the client confirms it.
                 is_error = True
-                content_text = f"[Execution Error]: {res.get('error')}"
+                content_text = path_confirmation_message(args.get("path", ""), name)
+                res = None
             else:
-                exit_code = res.get("exit_code", 0)
-                # Never strip: a paginated chunk must survive byte-exact so the
-                # client can rebuild the output by following next_cursor.
-                stdout = res.get("stdout", "")
-                stderr = res.get("stderr", "")
-                if exit_code != 0:
+                res = await call_remote_tool(user, name, args)
+            if res is not None:
+                err = remote_tool_error(res)
+                if err:
                     is_error = True
-                    # A non-zero exit code is the command's own result, not a
-                    # transport failure: the command RAN on the host. Without this
-                    # wording a model reads isError=true as "the node is
-                    # unreachable" and stops looking for the real output.
-                    parts = [
-                        f"[Exit code: {exit_code}] The command ran on the host and the node "
-                        f"is reachable; {exit_code} is the command's own exit status."
-                    ]
-                    if stderr.strip():
-                        parts.append(stderr)
-                    if stdout.strip():
-                        parts.append(stdout)
-                    content_text = "\n".join(parts) if parts else f"[Exit code: {exit_code}]"
+                    content_text = f"[Error] {err}"
                 else:
-                    parts = []
-                    if stdout:
-                        parts.append(stdout)
-                    if stderr:
-                        parts.append(f"[STDERR]\n{stderr}")
-                    content_text = "\n\n".join(parts) if parts else "(Command executed successfully with no output)"
-                # Surface node-side pagination/spooling so the model knows there is more.
-                if isinstance(res, dict):
-                    if res.get("next_cursor") is not None:
-                        content_text += (
-                            f"\n\n[output continues on the node: call {name} again with "
-                            f"cursor={res.get('next_cursor')} (optionally a larger max_chars)]"
-                        )
-                    if res.get("saved_to"):
-                        content_text += f"\n\n[full output saved on the node at {res['saved_to']}]"
-        elif name in ("write_file", "edit_file"):
-            res = await call_remote_tool(user, name, args)
+                    path = res.get("path", args.get("path", ""))
+                    sha = res.get("sha256", "")
+                    if name == "write_file":
+                        content_text = f"OK: wrote {res.get('bytes', 0)} bytes to {path} (sha256={sha})"
+                    else:
+                        content_text = f"OK: edited {path} ({res.get('replacements', 0)} replacement(s), sha256={sha})"
+        elif name == "system_write":
+            # Confirmed twin of write_file for paths inside the system. The node only
+            # ever sees write_file, so this works with every deployed node version.
+            res = await call_remote_tool(user, "write_file", args)
             err = remote_tool_error(res)
             if err:
                 is_error = True
@@ -1042,10 +1550,10 @@ async def messages_endpoint(request: Request):
             else:
                 path = res.get("path", args.get("path", ""))
                 sha = res.get("sha256", "")
-                if name == "write_file":
-                    content_text = f"OK: wrote {res.get('bytes', 0)} bytes to {path} (sha256={sha})"
-                else:
-                    content_text = f"OK: edited {path} ({res.get('replacements', 0)} replacement(s), sha256={sha})"
+                content_text = (
+                    f"OK: wrote {res.get('bytes', 0)} bytes to {path} (sha256={sha}) "
+                    f"(confirmed system write)"
+                )
         elif name == "grep_search":
             res = await call_remote_tool(user, name, args)
             err = remote_tool_error(res)
@@ -1077,18 +1585,51 @@ async def messages_endpoint(request: Request):
                 if res.get("truncated"):
                     content_text += f"\n\n(truncated: showing first {len(files)} paths)"
         elif name == "run_job":
-            res = await call_remote_tool(user, name, args)
-            err = remote_tool_error(res)
-            if err:
+            kind = classify_command(args.get("command"))
+            if kind:
+                # Same rule as bash_exec: the unconfirmed tools never install or
+                # delete anything, not even in the background.
                 is_error = True
-                content_text = f"[Error] {err}"
+                content_text = command_confirmation_message(args.get("command", ""), kind, "run_job")
             else:
-                job_id = res.get("job_id", "")
-                content_text = (
-                    f"Started job {job_id} (pid {res.get('pid')})\n"
-                    f"command: {res.get('command', args.get('command', ''))}\n"
-                    f"Use job_output(job_id=\"{job_id}\") to poll progress; use job_kill(job_id=\"{job_id}\") to stop it."
-                )
+                res = await call_remote_tool(user, name, args)
+                err = remote_tool_error(res)
+                if err:
+                    is_error = True
+                    content_text = f"[Error] {err}"
+                else:
+                    content_text = format_job_started(res, args)
+        elif name == "system_change":
+            # The confirmed twin of bash_exec/run_job. The client asks the user
+            # before this call because the tool is advertised destructiveHint=true;
+            # the node itself only ever sees bash_exec or run_job, so this works with
+            # every node version, including payloads older than this gateway.
+            background = _wants_background(args)
+            forwarded = dict(args)
+            forwarded.pop("background", None)
+            if background:
+                forwarded.pop("timeout_sec", None)
+                forwarded.pop("max_chars", None)
+                forwarded.pop("cursor", None)
+                remote_name = "run_job"
+            else:
+                # bash_exec has no cwd of its own; the command runs in the node's
+                # workspace unless the caller asked for a background job.
+                forwarded.pop("cwd", None)
+                timeout_sec = forwarded.get("timeout_sec")
+                if isinstance(timeout_sec, (int, float)) and timeout_sec > 25:
+                    forwarded["timeout_sec"] = 25
+                remote_name = "bash_exec"
+            res = await call_remote_tool(user, remote_name, forwarded)
+            if remote_name == "run_job":
+                err = remote_tool_error(res)
+                if err:
+                    is_error = True
+                    content_text = f"[Error] {err}"
+                else:
+                    content_text = format_job_started(res, forwarded)
+            else:
+                content_text, is_error = format_command_result(res, remote_name)
         elif name == "job_output":
             # Gateway-level guard: call_remote_tool gives up after 28s, keep wait below it.
             wait_ms = args.get("wait_ms")
@@ -1145,6 +1686,57 @@ async def messages_endpoint(request: Request):
                             )
                         )
                     content_text = "\n".join(lines)
+        elif name in ("share_file", "serve_dir"):
+            res = await call_remote_tool(user, name, args)
+            err = remote_tool_error(res)
+            if err:
+                is_error = True
+                content_text = f"[Error] {err}"
+            else:
+                content_text = (
+                    "Published. Public link: {url}\n"
+                    "Anyone with this link can read it - the random part of the path is the credential. "
+                    "Revoke it with unshare(name=\"{name}\") when it is no longer needed.\n"
+                    "Local URL on the node: {local}"
+                ).format(url=res.get("url", ""), name=res.get("name", ""),
+                         local=res.get("local_url", ""))
+        elif name == "share_list":
+            res = await call_remote_tool(user, name, args)
+            err = remote_tool_error(res)
+            if err:
+                is_error = True
+                content_text = f"[Error] {err}"
+            else:
+                shares = res.get("shares") or []
+                if not shares:
+                    content_text = "No active shares."
+                else:
+                    lines = ["kind | name | url | running"]
+                    for item in shares:
+                        if isinstance(item, dict):
+                            lines.append("{kind} | {name} | {url} | {running}".format(
+                                kind=item.get("kind", ""), name=item.get("name", ""),
+                                url=item.get("url", ""), running=item.get("running")))
+                    content_text = "\n".join(lines)
+        elif name == "unshare":
+            res = await call_remote_tool(user, name, args)
+            err = remote_tool_error(res)
+            if err:
+                is_error = True
+                content_text = f"[Error] {err}"
+            else:
+                content_text = (
+                    "Revoked share '{name}' ({slug}). Server stopped={stopped}, files removed={removed}."
+                ).format(name=res.get("name", ""), slug=res.get("slug", ""),
+                         stopped=res.get("server_stopped"), removed=res.get("files_removed"))
+        elif name in DEVICE_TOOLS:
+            res = await call_remote_tool(user, name, args)
+            err = remote_tool_error(res)
+            if err:
+                is_error = True
+                content_text = f"[Error] {err}"
+            else:
+                content_text = _format_device_result(name, res)
         else:
             resp["error"] = {"code": -32601, "message": f"Unknown tool: {name}"}
             broadcast_sse(user, resp)
@@ -1301,14 +1893,19 @@ async def mcp_unified_endpoint(request: Request):
         # that another in-flight request is still reading.
         active_sessions.pop(session_id, None)
 
-        # Clean up session queue if active
+        # Clean up session queue if active. The lookup stays keyed per connection
+        # (see above): a DELETE closes the stream whose key it names, never
+        # another connection's. The queue is unregistered from the per-user list
+        # and the session index here as well, so /health stays truthful even if
+        # the stream generator never resumes to run its own cleanup.
         if session_id in active_sse_sessions:
             q = active_sse_sessions.pop(session_id, None)
-            if q:
+            if q is not None:
                 try:
                     q.put_nowait(None)
                 except Exception:
                     pass
+                forget_sse_queue(user, q)
 
         return Response(
             status_code=204,
@@ -1397,7 +1994,11 @@ async def ws_tunnel_endpoint(websocket: WebSocket):
     logger.info(f"Agent tunnel connected for user '{user}'")
     tunnel_data = {"ws": websocket, "pending": {}}
     active_tunnels[user] = tunnel_data
+    # The agent is connected: this is the timestamp /health reports as
+    # last_tunnel_seen, and the event that tells a reboot apart from a flap.
+    record_tunnel_event("connect", user, "agent connected")
 
+    disconnect_reason = "tunnel closed"
     try:
         while True:
             raw = await websocket.receive_text()
@@ -1411,10 +2012,765 @@ async def ws_tunnel_endpoint(websocket: WebSocket):
                 if not fut.done():
                     fut.set_result(msg)
     except WebSocketDisconnect:
+        disconnect_reason = "websocket disconnected"
         logger.info(f"Agent tunnel disconnected for user '{user}'")
+    except Exception as exc:
+        disconnect_reason = f"tunnel error: {type(exc).__name__}"
+        logger.warning(f"Agent tunnel error for user '{user}': {exc}")
+        raise
     finally:
         if active_tunnels.get(user, {}).get("ws") == websocket:
             active_tunnels.pop(user, None)
+            # Only the tunnel that is still the active one is reported here: if
+            # the watchdog already removed it as stale, or a newer connection
+            # replaced it, that path has its own event and this one is noise.
+            record_tunnel_event("disconnect", user, disconnect_reason)
+
+
+# ---------------------------------------------------------------------------
+# Public file shares: GET/HEAD <shared-domain>/<node>/<name>-<secret>/...
+# ---------------------------------------------------------------------------
+# The node runs a loopback-only static server (core/web_share.py) and this route
+# relays the request over the existing tunnel; no port is ever opened on the
+# node. Only read methods are proxied, the 16-hex suffix is the share secret and
+# a node that is not connected fails fast with 503 instead of blocking on the
+# tunnel retry loop. The slug shape is duplicated from core/web_share.py on
+# purpose: the gateway deploys as a single file and must not import node code.
+SHARE_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}-[0-9a-f]{16}$")
+SHARE_METHODS = ("GET", "HEAD")
+# The node is trusted, but a corrupted or buggy reply must not be able to inject
+# response headers. An allow-list (not a deny-list) also keeps a compromised node
+# from setting cookies on the shared domain or adding headers this route never
+# means to expose; control characters are stripped and values are forced through
+# latin-1, which is what Starlette encodes headers with.
+_RELAY_HEADERS = (
+    "content-type", "content-disposition", "last-modified", "etag",
+    "cache-control", "location", "accept-ranges", "content-length",
+)
+_HEADER_VALUE_RE = re.compile(r"[\x00-\x1f\x7f]")
+_CONTENT_LENGTH_RE = re.compile(r"^\d{1,12}$")
+
+
+def _relay_headers(raw) -> dict:
+    headers = {}
+    if not isinstance(raw, dict):
+        return headers
+    for key, value in raw.items():
+        name = str(key).strip().lower()
+        if name not in _RELAY_HEADERS:
+            continue
+        text = _HEADER_VALUE_RE.sub("", str(value))[:4096]
+        text = text.encode("latin-1", "replace").decode("latin-1")
+        if name == "location" and not text.startswith("/"):
+            continue  # a redirect must stay inside this domain's share namespace
+        headers[name] = text
+    return headers
+
+
+# ---------------------------------------------------------------------------
+# Confirmation policy: what goes through a tool the client confirms
+# ---------------------------------------------------------------------------
+# bash_exec, run_job, write_file and edit_file are advertised with
+# readOnlyHint=true (see the policy below), and Gemini Spark - like any client
+# that keys its approval dialog on that hint - runs them without asking. That
+# promise is kept for the classes the operator wants gated, each with a confirmed
+# twin the model is told to use instead:
+#
+#   install / delete   software is installed or removed, data is deleted
+#                      -> system_change
+#   sudo               the command escalates privileges (sudo/doas/pkexec/runas)
+#                      -> system_change
+#   system             a system path or the registry is modified
+#                      -> system_change (shell) or system_write (file content)
+#
+# The shell check is deliberately conservative: a verb has to sit at the start of a
+# command segment, after stripping sudo/env/timeout/`powershell -Command`
+# prefixes, so `echo "rm -rf /"`, `grep rm notes.txt` and `git log --grep install`
+# all still run. It is a UX gate, not a sandbox - MESH_READ_ONLY on the node is the
+# hard boundary.
+_SEGMENT_RE = re.compile(r"[;&|\n]+")
+_PREFIX_RE = re.compile(
+    r"^\s*(?:(?:sudo|doas|command|nohup|env|time|nice|"
+    r"timeout\s+\d+(?:\.\d+)?|"
+    r"(?:powershell|pwsh)(?:\.exe)?(?:\s+-[\w:]+)*|"
+    r"cmd(?:\.exe)?\s+/[cCkK]|"
+    r"&\s+|start\s+)\s+|\w+=\S+\s+)*"
+)
+INSTALL_COMMAND_PATTERNS = (
+    r"apt(?:-get)?\s+(?:install|remove|purge|autoremove|dist-upgrade|full-upgrade)\b",
+    r"aptitude\s+(?:install|remove|purge)\b",
+    r"dnf\s+(?:install|remove|erase|update|upgrade|autoremove|groupinstall)\b",
+    r"yum\s+(?:install|remove|erase|update|upgrade|groupinstall)\b",
+    r"zypper\s+(?:install|remove|rm|update|up|dup|patch)\b",
+    r"pacman\s+-[A-Za-z]*[SR][A-Za-z]*\b",
+    r"apk\s+(?:add|del|delete)\b",
+    r"brew\s+(?:install|uninstall|remove|upgrade|reinstall)\b",
+    r"(?:pip|pip3|pipx)\s+(?:install|uninstall)\b",
+    r"(?:python|python3|py)\s+-m\s+pip\s+(?:install|uninstall)\b",
+    r"(?:npm|pnpm|yarn)\s+(?:install|i|ci|add|uninstall|remove|rm|up|upgrade)\b",
+    r"winget\s+(?:install|uninstall|upgrade)\b",
+    r"(?:choco|scoop)\s+(?:install|uninstall|upgrade|remove)\b",
+    r"(?:snap|flatpak)\s+(?:install|remove|uninstall|refresh|update)\b",
+    r"(?:gem|cargo|dotnet)\s+(?:install|uninstall|tool\s+(?:install|uninstall)|"
+    r"add\s+package|remove\s+package)\b",
+    r"go\s+install\b",
+    r"msiexec(?:\.exe)?\s+/[ix]\b",
+    r"dpkg\s+-[A-Za-z]*[irP][A-Za-z]*\b",
+    r"rpm\s+-[A-Za-z]*[ieU][A-Za-z]*\b",
+    r"(?:install|uninstall)-(?:module|package|script|psresource|windowsfeature)\b",
+    r"(?:add|remove)-(?:appxpackage|windowsoptionalfeature|windowsfeature|"
+    r"provisionedappxpackage)\b",
+    r"\b(?:iex|invoke-expression)\b",
+)
+DELETE_COMMAND_PATTERNS = (
+    r"rm\s+(?:-\S+\s+)*\S",
+    r"(?:rmdir|rd|unlink|shred|srm)\s+\S",
+    r"(?:del|erase)\s+\S",
+    r"deltree\b",
+    r"remove-item\b",
+    r"ri\s+(?:-\S+\s+)*\S",
+    r"clear-content\b",
+    r"remove-itemproperty\b",
+    r"(?:format-volume|clear-disk|remove-partition)\b",
+    r"(?:mkfs(?:\.\w+)?|wipefs|blkdiscard|fdisk|parted)\b",
+    r"dd\s+",
+    r"truncate\s+-s\s*0\b",
+    r"git\s+clean\s+-\S*[fdx]",
+    r"git\s+rm\b",
+    r"docker\s+(?:rm|rmi)\b",
+    r"docker\s+(?:system|volume|image|container|builder)\s+prune\b",
+    r"kubectl\s+delete\b",
+    r"vssadmin\s+delete\b",
+    r"bcdedit\s+/delete\b",
+    r"(?:userdel|groupdel|deluser|delgroup)\b",
+)
+_INSTALL_RE = re.compile("|".join(INSTALL_COMMAND_PATTERNS), re.IGNORECASE)
+_DELETE_RE = re.compile("|".join(DELETE_COMMAND_PATTERNS), re.IGNORECASE)
+# `curl … | sh` is the installer idiom and never looks like a package manager.
+_PIPE_TO_SHELL_RE = re.compile(
+    r"\b(?:curl|wget)\b[^|]*\|\s*(?:sudo\s+)?(?:ba|z|k)?sh\b", re.IGNORECASE
+)
+# Privilege escalation: the operator asked to be asked whenever the agent reaches
+# for root, whatever the command does with it.
+_PRIVILEGE_RE = re.compile(
+    r"(?:^|[;&|\n])\s*(?:sudo|doas|gsudo|pkexec|runas)\b"
+    r"|\bsu\s+-\S"
+    r"|\bStart-Process\b[^\n]*?-Verb\s+RunAs",
+    re.IGNORECASE,
+)
+# Paths that belong to the system, not to the user's work: the operator asked to be
+# asked before these are modified. Reads (`cat /etc/os-release`, `ls /usr/bin`) are
+# not gated - only a mutation of them is.
+SYSTEM_PATH_RE = re.compile(
+    r"(?:"
+    r"/(?:etc|usr|bin|sbin|lib|lib64|boot|dev|proc|sys|opt|root)(?:/|\b)"
+    r"|/var/(?:lib|log|spool|cache|www)(?:/|\b)"
+    r"|[A-Za-z]:\\+(?:Windows|ProgramData)(?:\\|\b)"
+    r"|[A-Za-z]:\\+Program Files(?:\s*\(x86\))?(?:\\|\b)"
+    r"|%(?:SystemRoot|ProgramFiles|ProgramData|windir)%"
+    r"|HKEY_LOCAL_MACHINE|HKLM\\+"
+    r")",
+    re.IGNORECASE,
+)
+# What "modifies" means for the test above.
+SYSTEM_MUTATION_PATTERNS = (
+    r"rm|rmdir|unlink|shred|mv|cp|install|chmod|chown|chgrp|mkdir|rmdir|touch|ln|"
+    r"truncate|dd|mount|umount|tee|sed\s+-i|patch|dpkg|rpm|apt(?:-get)?|"
+    r"(?:systemctl|service)\s+(?:start|stop|restart|reload|enable|disable|mask|unmask|"
+    r"daemon-reload|set-property)|"
+    r"crontab|visudo|passwd|user(?:add|mod|del)|group(?:add|mod|del)|"
+    r"reg\s+(?:add|delete|import|copy|restore|save|load|unload)|"
+    r"sc\s+(?:config|create|delete|start|stop)|netsh|schtasks|icacls|takeown|attrib|"
+    r"new-item|set-content|add-content|out-file|remove-item|move-item|copy-item|"
+    r"rename-item|new-itemproperty|set-itemproperty|clear-content|set-acl|"
+    r"(?:start|stop|restart|new|set|remove)-service"
+)
+_SYSTEM_MUTATION_RE = re.compile(
+    r"(?<![\w.-])(?:%s)(?![\w.-])" % SYSTEM_MUTATION_PATTERNS, re.IGNORECASE
+)
+# A redirection that writes straight into a system path.
+_REDIRECT_TO_SYSTEM_RE = re.compile(
+    r">>?\s*[\"']?(?:"
+    r"/(?:etc|usr|bin|sbin|lib|lib64|boot|dev|proc|sys|opt|root)(?:/|\b)"
+    r"|/var/(?:lib|log|spool|cache|www)(?:/|\b)"
+    r"|[A-Za-z]:\\+(?:Windows|ProgramData)(?:\\|\b)"
+    r"|[A-Za-z]:\\+Program Files(?:\s*\(x86\))?(?:\\|\b)"
+    r")",
+    re.IGNORECASE,
+)
+_TRUE_VALUES = ("1", "true", "yes", "on")
+
+
+def _wants_background(args) -> bool:
+    """True when the caller asked for system_change in the background."""
+    if not isinstance(args, dict):
+        return False
+    value = args.get("background")
+    if isinstance(value, bool):
+        return value
+    return str(value or "").strip().lower() in _TRUE_VALUES
+
+
+def classify_command(command) -> str:
+    """Return "install", "delete", "sudo", "system" or "" for a shell command.
+
+    "" means the command may run in the unconfirmed tools; anything else has to go
+    through system_change, where the client asks the user first. The most specific
+    reason wins, so `sudo apt install x` reports the install, not the sudo.
+    """
+    if not isinstance(command, str) or not command.strip():
+        return ""
+    if _PIPE_TO_SHELL_RE.search(command):
+        return "install"
+    for segment in _SEGMENT_RE.split(command):
+        stripped = _PREFIX_RE.sub("", segment).strip().lstrip("\"'`").lstrip()
+        if not stripped:
+            continue
+        if _INSTALL_RE.match(stripped):
+            return "install"
+        if _DELETE_RE.match(stripped):
+            return "delete"
+    if _PRIVILEGE_RE.search(command):
+        return "sudo"
+    if SYSTEM_PATH_RE.search(command) and (
+            _SYSTEM_MUTATION_RE.search(command) or _REDIRECT_TO_SYSTEM_RE.search(command)):
+        return "system"
+    return ""
+
+
+def is_system_path(path) -> bool:
+    """True when *path* points into the system rather than the user's own files."""
+    if not isinstance(path, str) or not path.strip():
+        return False
+    return bool(SYSTEM_PATH_RE.search(path.strip()))
+
+
+def command_confirmation_message(command: str, kind: str, tool: str) -> str:
+    """The refusal a model gets instead of running a gated command unconfirmed."""
+    what = {
+        "install": "installs or removes software",
+        "delete": "deletes data",
+        "sudo": "runs with elevated privileges",
+        "system": "changes a system path",
+    }.get(kind, "is a system change")
+    return (
+        f"[Confirmation required] This command {what}, so it was not run.\n"
+        f"{tool} is advertised as read-only and therefore runs without a confirmation "
+        f"dialog; the operator's rule is to be asked before anything is installed, "
+        f"deleted, run as root, or written into a system path. Call system_change with "
+        f"the same command - that tool is advertised as destructive, so the user is "
+        f"asked to confirm it first.\n"
+        f"command: {command.strip() if isinstance(command, str) else command}\n"
+        f"Do not rephrase, split, encode or otherwise obfuscate the command to get around "
+        f"this; route it through system_change."
+    )
+
+
+def path_confirmation_message(path: str, tool: str) -> str:
+    """The refusal for write_file/edit_file aimed at a system path."""
+    return (
+        f"[Confirmation required] {path} is a system path, so it was not written.\n"
+        f"{tool} is advertised as read-only and runs without a confirmation dialog; the "
+        f"operator's rule is to be asked before anything outside their own files is "
+        f"changed. Use system_write(path=..., content=...) instead - it is advertised as "
+        f"destructive, so the user is asked to confirm the write first.\n"
+        f"path: {path}"
+    )
+
+
+def format_command_result(res, name: str):
+    """(text, is_error) for a bash_exec / system_change / list_dir / read_file reply."""
+    if "error" in res:
+        return (f"[Execution Error]: {res.get('error')}", True)
+    is_error = False
+    exit_code = res.get("exit_code", 0)
+    # Never strip: a paginated chunk must survive byte-exact so the
+    # client can rebuild the output by following next_cursor.
+    stdout = res.get("stdout", "")
+    stderr = res.get("stderr", "")
+    if exit_code != 0:
+        is_error = True
+        # A non-zero exit code is the command's own result, not a
+        # transport failure: the command RAN on the host. Without this
+        # wording a model reads isError=true as "the node is
+        # unreachable" and stops looking for the real output.
+        parts = [
+            f"[Exit code: {exit_code}] The command ran on the host and the node "
+            f"is reachable; {exit_code} is the command's own exit status."
+        ]
+        if stderr.strip():
+            parts.append(stderr)
+        if stdout.strip():
+            parts.append(stdout)
+        content_text = "\n".join(parts) if parts else f"[Exit code: {exit_code}]"
+    else:
+        parts = []
+        if stdout:
+            parts.append(stdout)
+        if stderr:
+            parts.append(f"[STDERR]\n{stderr}")
+        content_text = "\n\n".join(parts) if parts else "(Command executed successfully with no output)"
+    # Surface node-side pagination/spooling so the model knows there is more.
+    if isinstance(res, dict):
+        if res.get("next_cursor") is not None:
+            content_text += (
+                f"\n\n[output continues on the node: call {name} again with "
+                f"cursor={res.get('next_cursor')} (optionally a larger max_chars)]"
+            )
+        if res.get("saved_to"):
+            content_text += f"\n\n[full output saved on the node at {res['saved_to']}]"
+    return (content_text, is_error)
+
+
+def format_job_started(res, args) -> str:
+    """The reply for run_job and for system_change(background=true)."""
+    job_id = res.get("job_id", "")
+    return (
+        f"Started job {job_id} (pid {res.get('pid')})\n"
+        f"command: {res.get('command', (args or {}).get('command', ''))}\n"
+        f"Use job_output(job_id=\"{job_id}\") to poll progress; "
+        f"use job_kill(job_id=\"{job_id}\") to stop it."
+    )
+
+
+# ---------------------------------------------------------------------------
+# MCP tool annotations: when the client may run a tool without asking first
+# ---------------------------------------------------------------------------
+# Gemini Spark reads ``Tool.annotations`` from ``tools/list`` to decide whether it
+# must stop and ask the user "confirm this action?" before a call. The spec's
+# defaults are pessimistic (readOnlyHint false, destructiveHint true), so a tool
+# advertised with no annotations is treated as destructive and *every* call was
+# confirmed. Declaring the hints explicitly keeps the prompt for the calls the
+# operator wants confirmed - installing/deleting, sudo, system paths - and removes
+# it from everything else.
+#
+# This table is the gateway's own: the gateway deploys as one file and may not
+# import node code, so tests/test_gateway_share_route.py compares the advertised
+# hints with the node's TOOLS. The differences are deliberate and pinned there:
+# system_change and system_write exist only here (they are translated to
+# bash_exec/run_job/write_file before the node sees them), and every tool this
+# gateway silences is still advertised honestly by the node, whose own surface has
+# no classifier to keep the read-only claim true.
+_ANNOT_READ_ONLY = {
+    "readOnlyHint": True,
+    "destructiveHint": False,
+    "idempotentHint": True,
+    "openWorldHint": False,
+}
+#: Tools that change something but are deliberately left without a dialog: file
+#: writes the operator asked not to confirm, and the unconfirmed shell pair whose
+#: gated classes are refused by classify_command() above.
+_ANNOT_UNCONFIRMED_WRITE = {
+    "readOnlyHint": True,
+    "destructiveHint": False,
+    "idempotentHint": False,
+    "openWorldHint": False,
+}
+_ANNOT_LOCAL_WRITE = {
+    "readOnlyHint": False,
+    "destructiveHint": False,
+    "idempotentHint": False,
+    "openWorldHint": False,
+}
+#: Publishing hands out a password-like public link, so the client is told the
+#: tool reaches outside the host (openWorldHint). It is still not destructive.
+_ANNOT_PUBLISH = {
+    "readOnlyHint": True,
+    "destructiveHint": False,
+    "idempotentHint": False,
+    "openWorldHint": True,
+}
+_ANNOT_DESTRUCTIVE = {
+    "readOnlyHint": False,
+    "destructiveHint": True,
+    "idempotentHint": False,
+    "openWorldHint": False,
+}
+#: Camera, microphone, location, SMS and contacts. They delete nothing, so
+#: "destructive" is not literally true - but ``destructiveHint`` is the only hint
+#: clients such as Gemini Spark reliably turn into a "confirm this action?" prompt,
+#: and these calls observe the physical world (or a person's private messages)
+#: without the operator being able to see it happen. Marking them destructive is
+#: therefore the honest safety choice, and it is documented in the README.
+_ANNOT_SENSITIVE = {
+    "readOnlyHint": False,
+    "destructiveHint": True,
+    "idempotentHint": False,
+    "openWorldHint": False,
+}
+
+#: Confirmation policy per advertised tool; names must match core/mcp_tools.TOOLS.
+#: A tool left out stays unannotated on purpose and therefore asks for
+#: confirmation - the safe default for something nobody has judged yet.
+TOOL_ANNOTATIONS = {
+    # read-only: looking around never needs a prompt
+    "mesh_status": _ANNOT_READ_ONLY,
+    "system_info": _ANNOT_READ_ONLY,
+    "system_vitals": _ANNOT_READ_ONLY,
+    "get_orchestration_skill": _ANNOT_READ_ONLY,
+    "list_dir": _ANNOT_READ_ONLY,
+    "read_file": _ANNOT_READ_ONLY,
+    "grep_search": _ANNOT_READ_ONLY,
+    "glob_find": _ANNOT_READ_ONLY,
+    "job_output": _ANNOT_READ_ONLY,
+    "job_list": _ANNOT_READ_ONLY,
+    "share_list": _ANNOT_READ_ONLY,
+    "device_info": _ANNOT_READ_ONLY,
+    # Commands run without a dialog; classify_command() refuses the gated classes
+    # (install/delete, sudo, system paths) and routes them to system_change.
+    "bash_exec": _ANNOT_UNCONFIRMED_WRITE,
+    "run_job": _ANNOT_UNCONFIRMED_WRITE,
+    # Files are written without a dialog too; a write into a system path is refused
+    # and routed to system_write, which the user confirms.
+    "write_file": _ANNOT_UNCONFIRMED_WRITE,
+    "edit_file": _ANNOT_UNCONFIRMED_WRITE,
+    # Stopping a job is neither an install nor a delete, and bash_exec can
+    # terminate the same process anyway, so no prompt is spent on it.
+    "job_kill": _ANNOT_UNCONFIRMED_WRITE,
+    # Reversible actions on the node's own device (torch, volume, TTS, ...): they
+    # change state, but nothing is deleted, nothing is gated and nothing leaves the
+    # host. The node advertises the same hints and a test compares the two, so this
+    # stays the plain local-write profile rather than the classifier-backed one.
+    "device_control": _ANNOT_LOCAL_WRITE,
+    # publishing something on the internet: no dialog either, but the client is told
+    # the tool reaches outside the host
+    "share_file": _ANNOT_PUBLISH,
+    "serve_dir": _ANNOT_PUBLISH,
+    # destructive: install/delete, sudo, system paths -> confirm first
+    "system_change": _ANNOT_DESTRUCTIVE,
+    "system_write": _ANNOT_DESTRUCTIVE,
+    "mesh_update": _ANNOT_DESTRUCTIVE,
+    "unshare": _ANNOT_DESTRUCTIVE,
+    # sensitive: observing the world or a person's private messages. Nothing is
+    # deleted, but the client must always ask - see _ANNOT_SENSITIVE above.
+    "device_capture": _ANNOT_SENSITIVE,
+    "device_messages": _ANNOT_SENSITIVE,
+}
+
+
+def annotate_tools(tools):
+    """Return *tools* with the confirmation policy attached to each entry."""
+    annotated = []
+    for tool in tools:
+        profile = TOOL_ANNOTATIONS.get(tool.get("name"))
+        if profile is None:
+            annotated.append(tool)
+            continue
+        tool = dict(tool)
+        tool["annotations"] = dict(profile)
+        annotated.append(tool)
+    return annotated
+
+
+# Tool surface advertised for public shares. The gateway keeps its own static
+# tools/list (it must not import node code), so this list has to stay in step
+# with the node's core/mcp_tools.TOOLS; tests/test_gateway_share_route.py
+# compares the two surfaces to catch drift.
+SHARE_TOOL_SPECS = [
+    {
+        "name": "share_file",
+        "description": (
+            "Publish ONE local file on the internet through the gateway and return a public "
+            "HTTPS link (https://<domain>/<node>/<name>-<random>/<file>). Anyone with the link "
+            "can read it; revoke it with unshare when it is no longer needed."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Path of the local file to publish."},
+                "name": {"type": "string", "description": "Human name in the URL (default: file name)."},
+                "overwrite": {"type": "boolean", "description": "Replace an existing share with the same name."},
+            },
+            "required": ["path"],
+        },
+    },
+    {
+        "name": "serve_dir",
+        "description": (
+            "Start a static web server for a local directory and return its public HTTPS link "
+            "(https://<domain>/<node>/<name>-<random>/). Served in place, read-only (GET/HEAD); "
+            "unshare stops it and the directory itself is never deleted."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Local directory to serve."},
+                "name": {"type": "string", "description": "Human name in the URL (default: directory name)."},
+            },
+            "required": ["path"],
+        },
+    },
+    {
+        "name": "share_list",
+        "description": "List active public shares with their URLs and whether the local server is running.",
+        "inputSchema": {"type": "object", "properties": {}, "required": []},
+    },
+    {
+        "name": "unshare",
+        "description": "Stop a public share and revoke its link (accepts the name, slug or full URL).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Share name, slug or public URL from share_list."},
+            },
+            "required": ["name"],
+        },
+    },
+]
+
+
+# The node's own device: one relay branch in tools/call, one formatter. The four
+# names must match core/mcp_tools.TOOLS exactly (the same parity test as the
+# share tools above), and DEVICE_TOOLS is deliberately a tuple so the branch is a
+# single membership test instead of four elifs.
+#
+# core/mcp_tools.TOOLS is the source of truth for the device_* specs in tools/list
+# as well. Their descriptions and schemas above are copied from it verbatim; an
+# earlier draft of this file carried different prose, which the node's landed
+# version superseded. The node executes these calls and the client reads this
+# copy, so a wording difference here would be a lie the model acts on.
+DEVICE_TOOLS = ("device_info", "device_control", "device_capture", "device_messages")
+
+#: A device report is JSON by contract and ``device_info(section="all")`` can run
+#: to megabytes, so the gateway shows the head and names the way to ask for one
+#: block by itself - rather than cutting a table in the middle with no way back.
+DEVICE_REPORT_LIMIT = 8000
+
+
+def _device_report_lines(res):
+    """Render the device blocks of a ``system_info`` answer as readable lines.
+
+    The gateway used to print a fixed list of the original fields, which silently
+    dropped everything the device branch added - the client asked for the battery
+    and got a summary without it. Every block is rendered as either its facts or,
+    when the platform has no source for it, ``available: false`` with the reason and
+    the fix, because "not exposed here" and "0 %" must not look the same to a model.
+    """
+    if not isinstance(res, dict):
+        return []
+    lines = []
+    hint = res.get("device_hint")
+    if hint:
+        lines.append("\n[device] %s" % hint)
+
+    def block(name):
+        value = res.get(name)
+        return value if isinstance(value, dict) else None
+
+    def facts(name, fields, prefix=""):
+        value = block(name)
+        if value is None:
+            return
+        if value.get("available") is False:
+            line = "%s%s: not available - %s" % (prefix, name, value.get("reason") or "no reason given")
+            if value.get("fix"):
+                line += " (fix: %s)" % value["fix"]
+            lines.append(line)
+            return
+        shown = ["%s=%s" % (key, value[key]) for key in fields if value.get(key) not in (None, "")]
+        if shown:
+            lines.append("%s%s: %s" % (prefix, name, ", ".join(shown)))
+
+    device = block("device")
+    if device and device.get("available") is not False:
+        shown = [device.get(key) for key in ("class", "manufacturer", "model", "android_release")]
+        shown = [str(item) for item in shown if item]
+        if shown:
+            lines.append("\n[device] " + " ".join(shown))
+    facts("battery", ("percent", "status", "plugged", "temperature_c", "health",
+                      "time_remaining_s", "ac_online"))
+    network = block("network")
+    if network:
+        if network.get("available") is False:
+            facts("network", ())
+        else:
+            if network.get("signal"):
+                lines.append("signal: %s" % network["signal"])
+            shown = [network.get(key) for key in ("connected_kind", "interface_count",
+                                                  "default_route")]
+            shown = [str(item) for item in shown if item not in (None, "")]
+            if shown:
+                lines.append("network: " + ", ".join(shown))
+            wifi = network.get("wifi") or {}
+            if wifi:
+                detail = ["%s=%s" % (key, wifi[key]) for key in ("ssid", "rssi_dbm",
+                                                                 "link_speed_mbps", "frequency_mhz")
+                          if wifi.get(key) not in (None, "")]
+                if detail:
+                    lines.append("wifi: " + ", ".join(detail))
+            cellular = network.get("cellular") or {}
+            if cellular:
+                detail = ["%s=%s" % (key, cellular[key])
+                          for key in ("operator", "network_type", "signal_dbm", "level",
+                                      "roaming", "data_state")
+                          if cellular.get(key) not in (None, "")]
+                if detail:
+                    lines.append("cellular: " + ", ".join(detail))
+                if cellular.get("cellinfo_reason"):
+                    lines.append("cellular: %s" % cellular["cellinfo_reason"])
+    facts("locale", ("language", "region", "encoding"))
+    facts("time", ("iso_local", "utc_offset", "timezone", "abbreviation"))
+    hardware = block("hardware")
+    if hardware and hardware.get("available") is not False:
+        cpu = hardware.get("cpu") or {}
+        if cpu:
+            shown = ["%s=%s" % (key, cpu[key])
+                     for key in ("model", "cores", "freq_mhz_max", "temp_c", "load")
+                     if cpu.get(key) not in (None, "")]
+            if shown:
+                lines.append("cpu: " + ", ".join(shown))
+        memory = hardware.get("memory") or {}
+        if memory:
+            shown = ["%s=%s" % (key, memory[key])
+                     for key in ("total_mb", "used_mb", "free_mb", "used_pct", "swap_total_mb")
+                     if memory.get(key) not in (None, "")]
+            if shown:
+                lines.append("memory: " + ", ".join(shown))
+        thermal = hardware.get("thermal") or []
+        if thermal:
+            lines.append("thermal: " + ", ".join(
+                "%s=%s%s" % (item.get("name"), item.get("value"),
+                             item.get("unit") or "") for item in thermal[:6]
+                if isinstance(item, dict)))
+    storage = block("storage")
+    if storage:
+        if storage.get("available") is False:
+            facts("storage", ())
+        else:
+            shown = ["%s=%s" % (key, storage[key])
+                     for key in ("root", "total_gb", "free_gb", "used_pct", "shared",
+                                 "capture_dir")
+                     if storage.get(key) not in (None, "")]
+            if shown:
+                lines.append("storage: " + ", ".join(shown))
+            if storage.get("shared_fix"):
+                lines.append("storage: %s" % storage["shared_fix"])
+    for name, fields in (("cameras", ("count",)), ("microphones", ("count",)),
+                         ("sensors", ("count", "sampling"))):
+        value = block(name)
+        if value is None:
+            continue
+        if value.get("available") is False:
+            facts(name, ())
+            continue
+        shown = ["%s=%s" % (key, value[key]) for key in fields if value.get(key) not in (None, "")]
+        items = value.get(name) or value.get("sensors") or []
+        names = []
+        for item in items[:4] if isinstance(items, list) else []:
+            if isinstance(item, dict):
+                label = item.get("name") or item.get("facing") or item.get("id")
+                if label not in (None, ""):
+                    names.append(str(label))
+            elif isinstance(item, str):
+                names.append(item)
+        text = ", ".join(shown)
+        if names:
+            text = (text + " (" + ", ".join(names) + ")") if text else ", ".join(names)
+        if text:
+            lines.append("%s: %s" % (name, text))
+    capabilities = block("capabilities")
+    if capabilities:
+        api = capabilities.get("termux_api") or capabilities.get("api") or {}
+        if api:
+            lines.append("termux-api: installed=%s" % api.get("installed"))
+            if api.get("missing"):
+                lines.append("termux-api missing: %s" % ", ".join(api["missing"][:8]))
+        if capabilities.get("app_reachable") is False:
+            lines.append("termux-api app: not answering - %s"
+                         % (capabilities.get("app_fix") or "open the Termux:API app once"))
+        permissions = capabilities.get("permissions") or {}
+        denied = sorted(name for name, state in permissions.items() if state == "denied")
+        if denied:
+            lines.append("permissions denied: %s" % ", ".join(denied))
+    return lines
+
+
+def _format_device_result(name, res):
+    """Render one ``device_*`` answer for the model.
+
+    "Not available on this node" is deliberately NOT an error: on a Windows or
+    Linux laptop a phone-only action is the normal answer, the node reports it as
+    ``available: false`` with a reason (and often a fix), and reading that as a
+    crash would tell the model the host is broken when it is merely not a phone.
+    """
+    if not isinstance(res, dict):
+        return json.dumps(res, ensure_ascii=False, indent=2, default=str)
+    if "error" in res:
+        # The relay already turns a real failure into isError; this keeps the text
+        # consistent with the other "[Error] ..." answers if this path is reached.
+        return "[Error] " + str(res.get("error"))
+    if res.get("available") is False:
+        lines = ["%s: not available on this node - %s"
+                 % (name, res.get("reason") or "this device does not expose it")]
+        if res.get("fix"):
+            lines.append("Fix: %s" % res.get("fix"))
+        return "\n".join(lines)
+    text = json.dumps(res, ensure_ascii=False, indent=2, default=str)
+    if len(text) > DEVICE_REPORT_LIMIT:
+        text = text[:DEVICE_REPORT_LIMIT] + (
+            "\n... [device report truncated; call the tool again with section=<name> for one block]")
+    return text
+
+
+def _share_response(status: int, message: str, extra=None) -> Response:
+    headers = {"content-type": "text/plain; charset=utf-8", "cache-control": "no-store"}
+    if extra:
+        headers.update(extra)
+    return Response(message + "\n", status_code=status, headers=headers)
+
+async def public_share_endpoint(request: Request) -> Response:
+    """Relay one public share request to the node that owns it."""
+    user = (request.path_params.get("user") or "").strip().lower()
+    rest = (request.path_params.get("rest") or "").strip("/")
+    if not user or not rest:
+        return _share_response(404, "not found")
+    if user not in load_registry():
+        return _share_response(404, "not found")
+
+    slug, _, sub_path = rest.partition("/")
+    if not SHARE_SLUG_RE.match(slug):
+        return _share_response(404, "not found")
+
+    method = request.method.upper()
+    if method not in SHARE_METHODS:
+        return _share_response(405, "method not allowed", {"allow": "GET, HEAD"})
+    if user not in active_tunnels:
+        return _share_response(503, "node offline: the mesh agent on '%s' is not connected" % user)
+
+    result = await call_remote_tool(user, "_http_share", {
+        "slug": slug,
+        "path": "/" + sub_path,
+        "method": method,
+        "query": request.url.query or "",
+    })
+    if not isinstance(result, dict) or "status" not in result:
+        logger.warning("share relay for '%s' returned an invalid response: %r", user, result)
+        return _share_response(502, "bad gateway")
+    try:
+        status = int(result["status"])
+        body = base64.b64decode(result.get("body_b64") or "")
+    except Exception:
+        return _share_response(502, "bad gateway")
+    if not 200 <= status <= 599:
+        # 1xx is not a final response: h11 rejects it and the client gets no
+        # response at all, so a buggy node reply becomes a clean 502 instead.
+        return _share_response(502, "bad gateway")
+    headers = _relay_headers(result.get("headers"))
+    if status in (204, 304):
+        # These statuses must not carry a body or a Content-Length.
+        body = b""
+        headers.pop("content-length", None)
+    elif method == "HEAD":
+        # Keep the node's Content-Length - it describes the resource while the
+        # body is empty - but only a sane numeric value.
+        if not _CONTENT_LENGTH_RE.match(headers.get("content-length", "")):
+            headers.pop("content-length", None)
+    else:
+        # Never trust a declared length: a body that disagrees with
+        # Content-Length is a protocol error (h11 aborts the response).
+        headers["content-length"] = str(len(body))
+    return Response(content=body, status_code=status, headers=headers, media_type=None)
+
 
 routes = [
     Route("/", health, methods=["GET", "HEAD", "OPTIONS"]),
@@ -1427,6 +2783,10 @@ routes = [
     Route("/mcp", mcp_unified_endpoint, methods=["GET", "POST", "DELETE", "OPTIONS", "HEAD"]),
     Route("/messages", mcp_unified_endpoint, methods=["GET", "POST", "DELETE", "OPTIONS", "HEAD"]),
     WebSocketRoute("/ws/tunnel", ws_tunnel_endpoint),
+    # Public file shares. MUST stay last: it is a catch-all for two-segment
+    # paths and must never shadow /sse, /mcp, /health, /api/register or the
+    # WebSocket tunnel above.
+    Route("/{user}/{rest:path}", public_share_endpoint, methods=["GET", "HEAD", "OPTIONS"]),
 ]
 
 middleware = [
@@ -1460,9 +2820,15 @@ async def tunnel_watchdog():
                         if not fut.done():
                             fut.set_exception(ConnectionResetError("Tunnel was stale"))
                     active_tunnels.pop(user, None)
-            # drop subscriber queues that no stream is reading any more
+                    # The stale path is a real disconnect: without this event the
+                    # history would show a connect with no matching disconnect
+                    # after a host reboot or a NAT timeout.
+                    record_tunnel_event("disconnect", user, f"stale tunnel (state={state})")
+            # drop subscriber queues that no stream is reading any more. The
+            # per-user container is an ordered list, so the surviving queues keep
+            # their order (oldest first) for the next cap eviction.
             for user, queues in list(active_sse_subscribers.items()):
-                alive = {q for q in queues if not q.empty() or q in active_sse_sessions.values()}
+                alive = [q for q in queues if not q.empty() or q in active_sse_sessions.values()]
                 if alive != queues:
                     active_sse_subscribers[user] = alive
                 if not alive:
@@ -1488,4 +2854,9 @@ app = Starlette(debug=False, routes=routes, middleware=middleware, lifespan=life
 
 
 if __name__ == "__main__":
-    uvicorn.run(app, host="127.0.0.1", port=8096, log_level="info", timeout_graceful_shutdown=2)
+    # ws_max_size matters for public file shares: the node sends the base64
+    # payload through the tunnel as ONE websocket message, so uvicorn's 16 MiB
+    # default silently drops anything above ~12 MiB. 128 MiB carries the node's
+    # maximum share size (64 MiB -> ~85 MiB on the wire) with headroom.
+    uvicorn.run(app, host="127.0.0.1", port=8096, log_level="info",
+                timeout_graceful_shutdown=2, ws_max_size=128 * 1024 * 1024)