docs(bot-desktop): comments match the human-lease lapse and the stable idle command

The idle check's module docstring and the launcher still said a human holding the screen is never timed
out (the four-window lapse changed that) and that the launcher runs `python -m`; stop()'s docstring said
the re-check always runs under start.lock (a sandbox screen's does not); the pinning note now says it
holds on a store install. Comments only.

tools/bot_desktop/idle_watch.py

@@ -2,11 +2,10 @@
 
 The screen outlives the gateway that started it on purpose (a restarted gateway re-attaches to it), so the
 gateway's display watcher cannot be the only thing that ever stops it: when no gateway comes back, Xvnc +
-Xfce and any browser left open run until reboot. ``launcher.sh`` therefore runs
-``python -m tools.bot_desktop.idle_watch`` in a loop of its own. Each run applies
-:func:`runtime.stop_if_idle` (the same ``bot_desktop.idle_stop_minutes`` window and the same rule that a
-human holding the screen is never timed out) and prints how long the launcher should sleep before the next
-run, so no interpreter stays resident between checks.
+Xfce and any browser left open run until reboot. ``launcher.sh`` therefore runs this module (through the
+install's stable command) in a loop of its own. Each run applies :func:`runtime.stop_if_idle` (the same
+``bot_desktop.idle_stop_minutes`` window and the same human-lease rule as the gateway's watcher) and prints
+how long the launcher should sleep before the next run, so no interpreter stays resident between checks.
 """
 
 from __future__ import annotations

tools/bot_desktop/launcher.sh

@@ -277,7 +277,7 @@ xset -display "$DISPLAY" s off -dpms s noblank 2>/dev/null || true
 
 # ---- idle self-stop: the screen outlives the gateway that started it (a restarted gateway re-attaches),
 # so it must also stop itself when no gateway ever comes back. tools/bot_desktop/idle_watch.py applies the
-# gateway watcher's own rule (bot_desktop.idle_stop_minutes; never while a human holds the screen) once per
+# gateway watcher's own rule (bot_desktop.idle_stop_minutes; never while a human is using the screen) once per
 # run and prints the seconds until the next check; nothing stays resident in between. runtime.py passes the
 # install's command for it, shell-quoted (the launcher's pid is appended); skipped when it passed none (the
 # sandbox-hosted screen, whose sandbox lifetime bounds it).

tools/bot_desktop/runtime.py

@@ -422,8 +422,9 @@ def _should_auto_start(env: dict[str, str]) -> bool:
 # A desktop nobody is using still holds ~220 MiB (plus whatever browser was left open). Every use —
 # a computer_use action, a browser spawn onto the screen, a viewer attached, a human takeover — stamps
 # ``activity``; :func:`stop_if_idle` stops a screen idle past ``bot_desktop.idle_stop_minutes`` unless a
-# human holds it. Two callers apply it: the gateway's display watcher and the screen's own launcher
-# (``idle_watch``), so a screen whose gateway never came back still stops. The next use starts it again.
+# human is using it (see the lease lapse below). Two callers apply it: the gateway's display watcher and
+# the screen's own launcher (``idle_watch``), so a screen whose gateway never came back still stops. The
+# next use starts it again.
 DEFAULT_IDLE_STOP_MINUTES = 30
 # A human holding the screen is never timed out while there is evidence of one: an attached viewer stamps
 # ``activity`` (every RFB update it receives, at most once a minute; the panel clock repaints every minute).
@@ -803,7 +804,8 @@ def _spawn_and_wait(sd: Path, wait_seconds: float) -> DesktopStatus:
             # command (the ``hermes --run-module`` launcher on a store install, which follows Python pin changes
             # and picks the current dependency generation at every run; this interpreter elsewhere), in this
             # home, first once the screen could be due (nothing is idle at start). The screen outlives updates,
-            # so neither this interpreter nor the inherited PYTHONPATH generation may be pinned.
+            # so the inherited PYTHONPATH generation is never pinned, and on a store install neither is this
+            # interpreter.
             "HERMES_BD_IDLE_CMD": shlex.join(installation_command(
                 Path(__file__).resolve().parents[2], module="tools.bot_desktop.idle_watch")),
             "HERMES_BD_HOME": str(get_hermes_home()),
@@ -888,7 +890,8 @@ def _sandbox_published_env() -> dict[str, str]:
 
 def stop(still_due: Optional[Callable[[], bool]] = None) -> bool:
     """Stop this profile's desktop; True when a running launcher (or the X server a dead one left behind)
-    was signalled. ``still_due`` is re-asked under ``start.lock``; False there leaves the screen running."""
+    was signalled. ``still_due`` is asked again before anything is killed (under ``start.lock`` for a screen on
+    this host); False there leaves the screen running."""
     from tools.bot_desktop import sandbox_host
     if sandbox_host._read_marker() or placement.resolve().where == placement.TERMINAL:
         if still_due is not None and not still_due():

website/docs/user-guide/features/bot-screen.md

@@ -94,8 +94,7 @@ reverse proxy's access log may record an already-spent ticket.
   started it is gone and never restarts. A screen a human has taken over is
   kept while their viewer keeps it in use; once nothing has used it for four
   windows, and at least 10 minutes (a viewer whose link dropped and never came
-  back), it stops as well.
-  Practical guidance
+  back), it stops as well and control returns to the agent. Practical guidance
   for small instances: 4 GB runs the desktop, 8 GB is where a takeover with a
   browser is comfortable.