gemini-computer-use 0.2.4 → 0.4.2

package/ops/update.ps1

@@ -0,0 +1,373 @@
+# ==============================================================================
+#  Antigravity Mesh - Windows node updater (single shot)
+#
+#  Meant to be run by the Scheduled Task "AntigravityMeshUpdater" once a day, and
+#  by hand through "gemini-computer-use update". It answers one question: is a
+#  newer release published, and - unless -Check was given - install it.
+#
+#  WHY A POWERSHELL WRAPPER
+#  The updater itself is Python (core/updater.py), because it has to work on
+#  Linux and macOS too. This wrapper exists for the two things only Windows
+#  knows: which interpreter the node is actually pinned to (the Startup .vbs),
+#  and where the payload lives (WshShell.CurrentDirectory). Starting the updater
+#  with the WRONG interpreter - the Microsoft Store alias - was the failure that
+#  kept a node offline for a day, so the interpreter is taken from the same
+#  launcher the agent itself is started from and refused if it is an alias.
+#
+#  WHAT IT DOES, IN ORDER
+#    1. resolves the install directory (-InstallDir, the Startup launcher, this
+#       script's own location, the config directory - in that order) and refuses
+#       a directory that holds no core\agent.py;
+#    2. resolves the interpreter (-Python, the Startup launcher's Run line, the
+#       heartbeat, MESH_PYTHON, then a real python.exe on PATH) and refuses the
+#       Microsoft Store alias, which never runs Python;
+#    3. runs "python -m core.updater --check" (with -Check) or "--apply",
+#       capturing stdout and stderr separately so the JSON answer stays parseable
+#       on Windows PowerShell 5.1;
+#    4. prints (or logs, with -Quiet) the local version, the newest published
+#       version and what was done.
+#
+#  EXIT CODES
+#    0  the node is on the newest release (or was updated without a restart)
+#    2  an update is available and was not installed (-Check), or the node is
+#       misconfigured (no payload, no usable interpreter)
+#    3  the update failed: network, checksum mismatch, unusable payload
+#    4  the update was installed and the node is restarting
+#
+#  PARAMETERS
+#    -Check        report only; never download or replace anything
+#    -Force        ignore the check interval and the failed-attempt backoff
+#    -NoRestart    install the payload but do not restart the agent
+#    -Offline      with -Check: report the cached answer, touch no network
+#    -Json         print the updater's JSON answer verbatim (for scripts)
+#    -InstallDir   payload directory override
+#    -Python       interpreter override
+#    -ConfigDir    where agent.env / agent.heartbeat live.
+#                  Default: %USERPROFILE%\.config\antigravity-mesh
+#    -LogFile      this script's journal. Default: <ConfigDir>\update-task.log
+#    -Quiet        write to -LogFile only, print nothing to the console
+#
+#  This file is deliberately ASCII-only: Windows PowerShell 5.1 reads a BOM-less
+#  script with the ANSI code page, so non-ASCII text here is a portability bug.
+#
+#  Usage:
+#     .\update.ps1
+#     .\update.ps1 -Check
+#     .\update.ps1 -Quiet -LogFile C:\logs\update.log
+# ==============================================================================
+[CmdletBinding()]
+param(
+    [switch]$Check,
+    [switch]$Force,
+    [switch]$NoRestart,
+    [switch]$Offline,
+    [switch]$Json,
+    [string]$InstallDir = '',
+    [string]$Python = '',
+    [string]$ConfigDir = '',
+    [string]$LogFile = '',
+    [switch]$Quiet
+)
+
+$ErrorActionPreference = 'Continue'
+$WindowsAppsMarker = '\WindowsApps\'
+
+$script:QuietMode = [bool]$Quiet
+$script:LogTarget = ''
+$script:Utf8NoBom = New-Object System.Text.UTF8Encoding -ArgumentList @($false)
+
+function Write-LogLine {
+    param([string]$Text)
+    if ([string]::IsNullOrEmpty($script:LogTarget)) { return }
+    try {
+        $stamp = (Get-Date).ToString('yyyy-MM-ddTHH:mm:ssK')
+        [System.IO.File]::AppendAllText($script:LogTarget, "[$stamp] $Text" + [Environment]::NewLine, $script:Utf8NoBom)
+    } catch { }
+}
+
+function Write-Note {
+    param([string]$Text)
+    Write-LogLine $Text
+    if (-not $script:QuietMode) { Write-Host $Text }
+}
+
+function Stop-WithConfigError {
+    param([string]$Message)
+    Write-Note ('CONFIG ERROR: ' + $Message)
+    exit 2
+}
+
+function Resolve-FullPath {
+    param([string]$Path)
+    if ([string]::IsNullOrWhiteSpace($Path)) { return $Path }
+    try { return [System.IO.Path]::GetFullPath($Path) } catch { return $Path }
+}
+
+function Test-File {
+    # Test-Path refuses an empty -LiteralPath with a parameter binding error, and
+    # that error aborts the whole statement it sits in - including the body of the
+    # "if (Test-Path $x)" it guards. Every path check in this script goes through
+    # here, so an unresolved value is simply "not a file".
+    param([string]$Path)
+    if ([string]::IsNullOrWhiteSpace($Path)) { return $false }
+    return (Test-Path -LiteralPath $Path -PathType Leaf)
+}
+
+function Read-TextFile {
+    param([string]$Path)
+    $bytes = [System.IO.File]::ReadAllBytes($Path)
+    if ($bytes.Length -ge 3 -and $bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) {
+        return [System.Text.Encoding]::UTF8.GetString($bytes, 3, $bytes.Length - 3)
+    }
+    if ($bytes.Length -ge 2 -and $bytes[0] -eq 0xFF -and $bytes[1] -eq 0xFE) {
+        return [System.Text.Encoding]::Unicode.GetString($bytes, 2, $bytes.Length - 2)
+    }
+    if ($bytes.Length -ge 2 -and $bytes[0] -eq 0xFE -and $bytes[1] -eq 0xFF) {
+        return [System.Text.Encoding]::BigEndianUnicode.GetString($bytes, 2, $bytes.Length - 2)
+    }
+    # The launcher is written as UTF-16 ("Unicode") by install.ps1, but a
+    # hand-edited file may be ANSI or UTF-8, so a NUL byte decides.
+    $hasNul = $false
+    $limit = [Math]::Min($bytes.Length, 512)
+    for ($i = 0; $i -lt $limit; $i++) {
+        if ($bytes[$i] -eq 0) { $hasNul = $true; break }
+    }
+    if ($hasNul) { return [System.Text.Encoding]::Unicode.GetString($bytes) }
+    return [System.Text.Encoding]::UTF8.GetString($bytes)
+}
+
+# ------------------------------------------------------------------ paths ----
+if ([string]::IsNullOrWhiteSpace($ConfigDir)) {
+    $profileDir = $env:USERPROFILE
+    if ([string]::IsNullOrWhiteSpace($profileDir)) { $profileDir = [Environment]::GetFolderPath('UserProfile') }
+    if ([string]::IsNullOrWhiteSpace($profileDir)) {
+        Stop-WithConfigError 'cannot resolve the user profile directory; pass -ConfigDir explicitly'
+    }
+    $ConfigDir = Join-Path $profileDir '.config\antigravity-mesh'
+}
+$ConfigDir = Resolve-FullPath $ConfigDir
+if ([string]::IsNullOrWhiteSpace($LogFile)) { $LogFile = Join-Path $ConfigDir 'update-task.log' }
+$LogFile = Resolve-FullPath $LogFile
+try {
+    $logDir = Split-Path -Parent $LogFile
+    if ($logDir -and -not (Test-Path -LiteralPath $logDir -PathType Container)) {
+        $null = New-Item -ItemType Directory -Path $logDir -Force -ErrorAction Stop
+    }
+    $script:LogTarget = $LogFile
+} catch {
+    $script:LogTarget = ''
+}
+
+# ------------------------------------------------------------- the launcher --
+# install.ps1 writes this file; it names both the interpreter to run and the
+# directory the agent runs from, which is exactly what the updater needs.
+$startupDir = [Environment]::GetFolderPath('Startup')
+$vbsPath = ''
+$launcherText = ''
+if (-not [string]::IsNullOrWhiteSpace($startupDir)) {
+    $vbsPath = Join-Path $startupDir 'antigravity-agent.vbs'
+    if (Test-Path -LiteralPath $vbsPath -PathType Leaf) {
+        try { $launcherText = Read-TextFile $vbsPath } catch { $launcherText = '' }
+    }
+}
+
+function Get-LauncherInterpreter {
+    if ([string]::IsNullOrWhiteSpace($launcherText)) { return '' }
+    $run = [regex]::Match($launcherText, '(?im)^[^\r\n]*WshShell\.Run[^\r\n]*?cmd[ \t]+/c[ \t]+"+(?<exe>[^"]+?)"+[ \t]+(?:-u[ \t]+)?-m[ \t]+core\.agent[^\r\n]*')
+    if (-not $run.Success) {
+        $run = [regex]::Match($launcherText, '(?im)^[^\r\n]*WshShell\.Run[^\r\n]*?(?<exe>[A-Za-z]:\\[^"]*?\.(?:exe|cmd|bat))')
+    }
+    if ($run.Success) { return $run.Groups['exe'].Value.Trim() }
+    return ''
+}
+
+function Get-LauncherPayloadDir {
+    if ([string]::IsNullOrWhiteSpace($launcherText)) { return '' }
+    $dir = [regex]::Match($launcherText, '(?im)^[^\r\n]*WshShell\.CurrentDirectory[ \t]*=[ \t]*"(?<dir>[^"]+)"')
+    if ($dir.Success) { return $dir.Groups['dir'].Value.Trim() }
+    return ''
+}
+
+function Test-NodePayload {
+    param([string]$Path)
+    if ([string]::IsNullOrWhiteSpace($Path)) { return $false }
+    return (Test-Path -LiteralPath (Join-Path $Path 'core\agent.py') -PathType Leaf)
+}
+
+# --- install directory --------------------------------------------------------
+$PayloadReason = '-InstallDir'
+if (-not (Test-NodePayload $InstallDir)) {
+    $candidate = Get-LauncherPayloadDir
+    if (Test-NodePayload $candidate) {
+        $InstallDir = $candidate
+        $PayloadReason = 'the Startup launcher (WshShell.CurrentDirectory)'
+    } else {
+        $candidate = ''
+        if ($PSScriptRoot) { $candidate = Split-Path -Parent (Split-Path -Parent $PSScriptRoot) }
+        if (Test-NodePayload $candidate) {
+            $InstallDir = $candidate
+            $PayloadReason = 'the location of this script'
+        } elseif (Test-NodePayload $ConfigDir) {
+            $InstallDir = $ConfigDir
+            $PayloadReason = 'the config directory'
+        } else {
+            Stop-WithConfigError ('no node payload found: -InstallDir, the Startup launcher and the script location all lack core\agent.py')
+        }
+    }
+}
+$InstallDir = Resolve-FullPath $InstallDir
+if (-not (Test-NodePayload $InstallDir)) {
+    Stop-WithConfigError ('the install directory holds no core\agent.py: ' + $InstallDir)
+}
+
+# --- interpreter --------------------------------------------------------------
+function Get-HeartbeatInterpreter {
+    $heartbeat = Join-Path $ConfigDir 'agent.heartbeat'
+    if (-not (Test-Path -LiteralPath $heartbeat -PathType Leaf)) { return '' }
+    try {
+        $json = [System.IO.File]::ReadAllText($heartbeat) | ConvertFrom-Json
+    } catch { return '' }
+    $prop = $json.PSObject.Properties['interpreter']
+    if ($prop -and $prop.Value) { return ([string]$prop.Value).Trim() }
+    return ''
+}
+
+function Get-PythonOnPath {
+    # The first "python" on PATH is usually the Microsoft Store alias, so every
+    # candidate is checked and the alias is skipped rather than accepted.
+    foreach ($cmd in @(Get-Command python -All -ErrorAction SilentlyContinue)) {
+        if ($cmd -and $cmd.Source -and $cmd.Source -notlike "*$WindowsAppsMarker*" -and (Test-Path -LiteralPath $cmd.Source -PathType Leaf)) {
+            return $cmd.Source
+        }
+    }
+    $candidates = @(
+        "$env:LOCALAPPDATA\Programs\Python\Python313\python.exe",
+        "$env:LOCALAPPDATA\Programs\Python\Python312\python.exe",
+        "$env:LOCALAPPDATA\Programs\Python\Python311\python.exe",
+        "$env:ProgramFiles\Python313\python.exe",
+        "$env:ProgramFiles\Python312\python.exe",
+        "$env:ProgramFiles\Python311\python.exe"
+    )
+    foreach ($candidate in $candidates) {
+        if (Test-Path -LiteralPath $candidate -PathType Leaf) { return $candidate }
+    }
+    return ''
+}
+
+$InterpreterReason = '-Python'
+if (-not (Test-File $Python)) {
+    $Python = ''
+    $fromLauncher = Get-LauncherInterpreter
+    if ($fromLauncher) {
+        $Python = $fromLauncher
+        $InterpreterReason = 'the Startup launcher (WshShell.Run)'
+    }
+    if (-not (Test-File $Python)) {
+        $Python = Get-HeartbeatInterpreter
+        $InterpreterReason = 'the heartbeat'
+    }
+    if (-not (Test-File $Python)) {
+        $Python = $env:MESH_PYTHON
+        $InterpreterReason = 'MESH_PYTHON'
+    }
+    if (-not (Test-File $Python)) {
+        $Python = Get-PythonOnPath
+        $InterpreterReason = 'PATH'
+    }
+}
+if ([string]::IsNullOrWhiteSpace($Python)) {
+    Stop-WithConfigError 'no python.exe found: pass -Python, or re-run install.ps1 so the node pins a real interpreter'
+}
+if ($Python -like "*$WindowsAppsMarker*") {
+    Stop-WithConfigError ('the resolved interpreter is the Microsoft Store alias: ' + $Python + ' - that alias never runs Python; re-run install.ps1')
+}
+if (-not (Test-File $Python)) {
+    Stop-WithConfigError ('the resolved interpreter does not exist: ' + $Python)
+}
+
+Write-Note ('updater start: install=' + $InstallDir + ' (' + $PayloadReason + ') interpreter=' + $Python + ' (' + $InterpreterReason + ') mode=' + $(if ($Check) { 'check' } else { 'apply' }))
+
+# --------------------------------------------------------------- run Python --
+# stdout and stderr are redirected to files by cmd.exe, not captured by
+# Start-Process: on Windows PowerShell 5.1 a process started that way reports an
+# empty ExitCode once it has exited, and mixing stderr into stdout would break
+# the JSON answer the updater prints.
+$outFile = Join-Path $env:TEMP ('mesh-update-out-' + [Guid]::NewGuid().ToString('N') + '.json')
+$errFile = Join-Path $env:TEMP ('mesh-update-err-' + [Guid]::NewGuid().ToString('N') + '.log')
+if ($Check) { $mode = '--check' } else { $mode = '--apply' }
+$arguments = @('-m', 'core.updater', $mode, '--json', '--dir', $InstallDir)
+if ($Force) { $arguments += '--force' }
+if ($Offline -and $Check) { $arguments += '--offline' }
+if ($NoRestart -and -not $Check) { $arguments += '--no-restart' }
+
+$quoted = @($arguments | ForEach-Object { '"' + ($_ -replace '"', '\"') + '"' }) -join ' '
+$commandLine = '/c ""' + $Python + '" ' + $quoted + ' > "' + $outFile + '" 2> "' + $errFile + '""'
+$exitCode = 3
+try {
+    $null = & cmd.exe $commandLine
+    $exitCode = $LASTEXITCODE
+} catch {
+    Write-Note ('could not start the interpreter: ' + $_.Exception.Message)
+    exit 3
+}
+
+$answer = ''
+if (Test-Path -LiteralPath $outFile) {
+    try { $answer = ([System.IO.File]::ReadAllText($outFile)).Trim() } catch { $answer = '' }
+}
+$errors = ''
+if (Test-Path -LiteralPath $errFile) {
+    try { $errors = ([System.IO.File]::ReadAllText($errFile)).Trim() } catch { $errors = '' }
+}
+Remove-Item -LiteralPath $outFile, $errFile -Force -ErrorAction SilentlyContinue
+
+$parsed = $null
+if ($answer) {
+    try { $parsed = $answer | ConvertFrom-Json } catch { $parsed = $null }
+}
+
+# The updater's own log lines (a traceback, a watchdog note) belong in the
+# journal: they are the only trace when --apply fails before printing JSON.
+if ($errors) {
+    foreach ($line in @($errors -split "`r?`n")) {
+        if ($line.Trim()) { Write-LogLine ('python: ' + $line.Trim()) }
+    }
+}
+
+if ($parsed) {
+    $current = [string]$parsed.current
+    $latest = [string]$parsed.latest
+    $reason = [string]$parsed.reason
+    if ($Json) {
+        # The updater's own answer, verbatim: scripts read this, so it is not
+        # decorated with the human summary below.
+        Write-Output $answer
+    } else {
+        if ($Check) {
+            if ($exitCode -eq 2) {
+                Write-Note ('update available: ' + $current + ' -> ' + $latest + ' (' + $reason + ')')
+            } elseif ($exitCode -eq 0) {
+                Write-Note ('up to date: ' + $current + ' (' + $reason + ')')
+            } else {
+                Write-Note ('check failed: ' + $reason)
+            }
+        } else {
+            if ($exitCode -eq 0 -or $exitCode -eq 4) {
+                Write-Note ('updated: ' + $reason + ' (exit ' + $exitCode + ')')
+            } else {
+                Write-Note ('update failed: ' + $reason)
+            }
+        }
+        if (-not $script:QuietMode) {
+            if ($latest) { Write-Host ('latest  : ' + $latest) }
+            if ($reason) { Write-Host ('detail  : ' + $reason) }
+        }
+    }
+} elseif (-not $script:QuietMode -and -not $Json) {
+    Write-Host ('the updater produced no JSON answer (exit ' + $exitCode + ')')
+    if ($errors) { Write-Host $errors }
+}
+
+if ($Check -and $exitCode -eq 0 -and $parsed -and $parsed.update_available) { exit 2 }
+if ($exitCode -eq 2 -and -not $Check) { exit 2 }
+exit $exitCode

package/ops/windows/README.md

@@ -0,0 +1,298 @@
+# Windows agent watchdog and doctor
+
+| File | Role |
+| :--- | :--- |
+| `agent-watchdog.ps1` | single-shot supervisor: check the node, restart the agent if it is dead |
+| `../doctor.ps1` | read-only diagnostic: report every fact that explains an offline node |
+| `../update.ps1` | single-shot updater: install a newer release and let the node restart onto it |
+| `run-hidden.vbs` | the windowless launcher both scheduled tasks go through: no console is ever drawn |
+
+All three PowerShell scripts are ASCII-only, target Windows PowerShell 5.1 and use
+nothing but in-box cmdlets; `run-hidden.vbs` is ASCII-only too and needs only
+`wscript.exe`. None of them needs the task scheduler to be running in order to work.
+
+## Why `run-hidden.vbs` exists
+
+A scheduled task has no console of its own. When the action is `powershell.exe`,
+Windows therefore allocates a **new** console for it and only then applies
+`-WindowStyle Hidden`: the window is created, drawn and hidden again, and the user
+sees a black window appear and disappear. The watchdog fires every five minutes, so
+that flash is the most noticeable thing this project does on a desktop.
+
+`wscript.exe` is a GUI host and never allocates a console, and
+`WshShell.Run command, 0, False` hands the child `SW_HIDE` in its `STARTUPINFO` —
+the window is hidden from the first moment, so nothing is ever painted. That is the
+same mechanism as the logon launcher (`antigravity-agent.vbs`), which is why a node
+starts without a window either. Output goes to
+`<ConfigDir>\<script name>.out.log`, because a window that never appears also never
+shows an error.
+
+```powershell
+# exactly how the two tasks call it; the script path is relative to the payload
+wscript.exe "$Payload\ops\windows\run-hidden.vbs" "ops\windows\agent-watchdog.ps1" -Quiet
+wscript.exe "$Payload\ops\windows\run-hidden.vbs" "ops\update.ps1" -Quiet
+```
+
+## Why they exist
+
+After a Windows Update reboot the logon launcher did nothing, and the node stayed
+offline for about 29 hours. The interpreter pinned in the Startup `.vbs` was the
+Microsoft Store App Execution Alias `<...>\WindowsApps\python.exe` - a file that
+exists and starts, but runs no Python at all. The only trace was a truncated
+`Python ` fragment appended to `agent.log` with no trailing newline.
+
+The watchdog therefore **refuses any interpreter whose path contains
+`\WindowsApps\`**, and the doctor surfaces the same fact (plus the torn log line)
+within seconds.
+
+## `agent-watchdog.ps1` - single-shot supervisor
+
+Run every 5 minutes by the Scheduled Task **`AntigravityMeshWatchdog`**.
+
+| Parameter | Default | Meaning |
+| :--- | :--- | :--- |
+| `-ConfigDir` | `%USERPROFILE%\.config\antigravity-mesh` | where `agent.env`, `agent.log`, `agent.heartbeat` live |
+| `-LogFile` | `<ConfigDir>\watchdog.log` | the watchdog's own journal |
+| `-GraceSeconds` | `60` | a heartbeat younger than this counts as alive |
+| `-Quiet` | off | log only, no console output |
+
+Liveness is checked in this order, and the first positive answer wins:
+
+1. `<ConfigDir>\agent.heartbeat` is valid JSON and its `ts` is newer than
+   `-GraceSeconds`;
+2. `GET https://<gateway>/health?user=<node>` reports `node_online: true`;
+3. a verified agent process is running: a `python.exe`/`pythonw.exe`/`py.exe` with
+   `-m core.agent` as a real argument, or the `cmd.exe` launcher wrapper that also
+   carries the `agent.log` redirect. A process that merely mentions `core.agent`
+   (a PowerShell session, a grep) never counts - otherwise a dead node would look
+   alive and never be restarted.
+
+When the node is dead it appends **exactly one** diagnostic line to `agent.log`
+(reason + interpreter being started), starts the agent hidden with the same
+command line, environment and working directory as the `.vbs`
+(`cmd /c ""<python.exe>" -u -m core.agent >> "<agent.log>" 2>&1`), waits up to 20 s
+for liveness and journals the outcome.
+
+| Exit code | Meaning |
+| :--- | :--- |
+| `0` | the node is online (already, or recovered by this run); also when another watchdog instance is handling it |
+| `2` | configuration or launcher problem: `agent.env`, the Startup `.vbs` or the pinned interpreter is missing, unusable, or is the Store alias |
+| `3` | the node is still offline after the recovery attempt |
+
+It is idempotent: a live node (or a live `core.agent` process) is never started
+twice, and a named mutex serialises overlapping runs. The token is never printed
+and never logged - it is masked as `****`.
+
+## `../doctor.ps1` - read-only diagnostic
+
+| Parameter | Default | Meaning |
+| :--- | :--- | :--- |
+| `-ConfigDir` | `%USERPROFILE%\.config\antigravity-mesh` | same directory as above |
+| `-Json` | off | print exactly one JSON object and nothing else |
+| `-TailLines` | `20` | how many `agent.log` lines to show |
+
+It reports the interpreter from the `.vbs` (with `--version` and an
+`import websockets` probe, and whether it is the Store alias), the `.vbs` path and
+content with the token masked, the state of `AntigravityMeshWatchdog`, `agent.env`
+with the token masked, the heartbeat JSON and its age, the last `-TailLines` lines
+of `agent.log` with `torn-line: true` when the file does not end in a newline, the
+gateway `/health` JSON, and whether a verified `core.agent` process is running
+(the same rule the watchdog applies: a Python interpreter running `-m core.agent`,
+never a process that merely mentions it).
+
+It finishes with the verdict lines `interpreter_ok`, `autostart_ok`,
+`heartbeat_fresh`, `node_online`. Exit code `0` means all of `interpreter_ok`,
+`autostart_ok` and `node_online` are true; anything else is `2`. Nothing is
+written to disk.
+
+## Running them by hand
+
+```powershell
+# from the payload / repository root
+.\ops\doctor.ps1
+.\ops\doctor.ps1 -Json
+.\ops\doctor.ps1 -TailLines 50
+.\ops\windows\agent-watchdog.ps1
+.\ops\windows\agent-watchdog.ps1 -Quiet
+
+# through the CLI (same scripts, found next to bin/cli.js)
+npx gemini-computer-use doctor
+npx gemini-computer-use doctor --json
+npx gemini-computer-use restart
+
+# the scheduled task
+Get-ScheduledTask -TaskName AntigravityMeshWatchdog
+Get-ScheduledTaskInfo -TaskName AntigravityMeshWatchdog
+Start-ScheduledTask -TaskName AntigravityMeshWatchdog
+```
+
+## What the installer must register
+
+Task name: **`AntigravityMeshWatchdog`**.
+
+* **Action**: `wscript.exe`
+* **Arguments**: `"<payload>\ops\windows\run-hidden.vbs" "ops\windows\agent-watchdog.ps1" -Quiet`
+* **Working directory**: the payload directory (the directory that contains
+  `core\`, next to `install.ps1`). The launcher resolves the script against its own
+  location, so the registered path survives a payload that moves.
+* **Triggers**: once at logon of the installing user, plus a repeating trigger
+  (`-Once -RepetitionInterval 5 minutes`, indefinite duration). The logon trigger
+  mirrors the `.vbs`; the repeating trigger is what actually recovers the node, and
+  `-StartWhenAvailable` makes up a run missed during a reboot.
+* **Settings**: `-MultipleInstances IgnoreNew`, `-StartWhenAvailable`,
+  `-ExecutionTimeLimit 10 minutes`.
+
+```powershell
+$PayloadDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$Launcher   = Join-Path $PayloadDir 'ops\windows\run-hidden.vbs'
+$action     = New-ScheduledTaskAction -Execute 'wscript.exe' `
+                -Argument ('"' + $Launcher + '" "ops\windows\agent-watchdog.ps1" -Quiet') `
+                -WorkingDirectory $PayloadDir
+$atLogon    = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME
+$repeat     = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(2) `
+                -RepetitionInterval (New-TimeSpan -Minutes 5) `
+                -RepetitionDuration ([TimeSpan]::MaxValue)
+$settings   = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries `
+                -DontStopIfGoingOnBatteries -StartWhenAvailable `
+                -MultipleInstances IgnoreNew `
+                -ExecutionTimeLimit (New-TimeSpan -Minutes 10)
+Register-ScheduledTask -TaskName 'AntigravityMeshWatchdog' -Action $action `
+  -Trigger @($atLogon, $repeat) -Settings $settings -Force `
+  -Description 'Antigravity Mesh: keep the node agent running (every 5 minutes).'
+```
+
+The `ops\` directory must travel with the payload: it has to be listed in
+`package.json` (`files`), in `build-installer-exe.ps1` (`$PAYLOAD`) and in
+whatever `deploy_gateway.sh` stages for the node bootstrap.
+
+## `../update.ps1` - single-shot self-update
+
+Run once a day by the Scheduled Task **`AntigravityMeshUpdater`**, and by hand as
+`gemini-computer-use update [-Check]`.
+
+| Parameter | Default | Meaning |
+| :--- | :--- | :--- |
+| `-Check` | off | report only; never download or replace anything |
+| `-Force` | off | ignore the check interval and the failed-attempt backoff |
+| `-NoRestart` | off | install the payload but do not restart the agent |
+| `-Offline` | off | with `-Check`: report the cached answer, touch no network |
+| `-Json` | off | print the updater's JSON answer verbatim |
+| `-InstallDir` | from the Startup `.vbs` | payload directory |
+| `-Python` | from the Startup `.vbs` | interpreter to run the updater with |
+| `-ConfigDir` | `%USERPROFILE%\.config\antigravity-mesh` | where `agent.env` and `agent.heartbeat` live |
+| `-LogFile` | `<ConfigDir>\update-task.log` | this script's own journal |
+| `-Quiet` | off | log only, no console output |
+
+It resolves the install directory and the interpreter the same way the watchdog
+does - from the Startup launcher `install.ps1` wrote - and **refuses the Microsoft
+Store alias** for the same reason: that alias never runs Python. The work itself is
+done by `python -m core.updater` (`--check` or `--apply`), which downloads the
+release payload, verifies its published SHA-256, swaps it in with a rollback backup
+and starts a helper that brings the agent back. See
+[docs/UPDATES.md](../../docs/UPDATES.md).
+
+| Exit code | Meaning |
+| :--- | :--- |
+| `0` | the node is on the newest release, or was updated without a restart |
+| `2` | an update exists and was not installed (`-Check`), or the node is misconfigured |
+| `3` | the update failed: network, checksum mismatch, unusable payload |
+| `4` | the update was installed and the node is restarting |
+
+Register it as **`AntigravityMeshUpdater`**: action `wscript.exe` (through
+`run-hidden.vbs`, so the daily run never shows a window), arguments
+`"<payload>\ops\windows\run-hidden.vbs" "ops\update.ps1" -Quiet`, working directory
+the payload directory, trigger daily (the installer uses 03:30), settings
+`-MultipleInstances IgnoreNew` and `-StartWhenAvailable` (so a machine that was off
+at 03:30 updates at the next opportunity).
+
+---
+
+# Сторож и доктор для Windows
+
+| Файл | Назначение |
+| :--- | :--- |
+| `agent-watchdog.ps1` | однократная проверка: если узел мёртв - поднять агента |
+| `../doctor.ps1` | диагностика только на чтение: показать всё, что объясняет простой |
+
+Оба скрипта - ASCII-only, рассчитаны на Windows PowerShell 5.1 и используют
+только встроенные командлеты. Планировщик заданий для их работы не нужен.
+
+**Зачем это нужно.** После перезагрузки (Windows Update) автозапуск молча ничего
+не сделал, и узел оставался offline около 29 часов. В `.vbs` был прописан
+интерпретатор-алиас Microsoft Store `<...>\WindowsApps\python.exe`: файл
+существует и запускается, но Python не выполняет. Единственным следствием была
+обрезанная строка `Python ` в `agent.log` без завершающего перевода строки.
+
+Поэтому сторож **отказывается работать с интерпретатором, чей путь содержит
+`\WindowsApps\`**, а доктор за секунды показывает и это, и оборванную строку
+журнала.
+
+## `agent-watchdog.ps1`
+
+Запускается каждые 5 минут заданием планировщика **`AntigravityMeshWatchdog`**.
+
+| Параметр | Значение по умолчанию | Смысл |
+| :--- | :--- | :--- |
+| `-ConfigDir` | `%USERPROFILE%\.config\antigravity-mesh` | где лежат `agent.env`, `agent.log`, `agent.heartbeat` |
+| `-LogFile` | `<ConfigDir>\watchdog.log` | собственный журнал сторожа |
+| `-GraceSeconds` | `60` | heartbeat моложе этого возраста считается живым |
+| `-Quiet` | выключен | только журнал, без вывода в консоль |
+
+Признаки жизни проверяются по порядку, побеждает первый положительный:
+сердцебиение `agent.heartbeat` (свежее), затем `GET https://<gateway>/health?user=<узел>`
+с `node_online: true`, затем подтверждённый процесс агента: `python.exe`/`pythonw.exe`/`py.exe`
+с настоящим аргументом `-m core.agent` либо обёртка `cmd.exe`, в которой есть
+перенаправление вывода в `agent.log`. Процесс, который лишь упоминает `core.agent`
+(сессия PowerShell, grep), агентом не считается - иначе мёртвый узел выглядел бы
+живым и никогда не перезапускался.
+
+Если узел мёртв, сторож дописывает в `agent.log` **ровно одну** строку с причиной
+и путём интерпретатора, скрытно запускает агента ровно так же, как это делает
+`.vbs`, ждёт до 20 секунд и записывает результат в `-LogFile`.
+
+Коды возврата: `0` - узел онлайн (был или восстановлен); `2` - проблема
+конфигурации или автозапуска (`agent.env`, `.vbs` или интерпретатор отсутствуют,
+непригодны либо это алиас Store); `3` - узел так и остался offline. Токен никогда
+не печатается и не пишется в журнал: он маскируется как `****`.
+
+## `../doctor.ps1`
+
+| Параметр | Значение по умолчанию | Смысл |
+| :--- | :--- | :--- |
+| `-ConfigDir` | `%USERPROFILE%\.config\antigravity-mesh` | тот же каталог |
+| `-Json` | выключен | вывести ровно один JSON-объект и ничего больше |
+| `-TailLines` | `20` | сколько последних строк `agent.log` показать |
+
+Доктор показывает интерпретатор из `.vbs` (плюс `--version` и проверку
+`import websockets`, плюс признак алиаса Store), путь и содержимое `.vbs` с
+замаскированным токеном, состояние задания `AntigravityMeshWatchdog`, `agent.env`
+с замаскированным токеном, JSON сердцебиения и его возраст, последние строки
+`agent.log` с флагом `torn-line: true` (файл не заканчивается переводом строки),
+JSON ответа `/health` и наличие подтверждённого процесса агента.
+Завершается строки-вердикты
+`interpreter_ok`, `autostart_ok`, `heartbeat_fresh`, `node_online`. Код возврата
+`0` - всё в порядке, иначе `2`. На диск ничего не записывается.
+
+## Ручной запуск
+
+```powershell
+.\ops\doctor.ps1
+.\ops\doctor.ps1 -Json
+.\ops\windows\agent-watchdog.ps1
+.\ops\windows\agent-watchdog.ps1 -Quiet
+npx gemini-computer-use doctor
+npx gemini-computer-use restart
+Get-ScheduledTaskInfo -TaskName AntigravityMeshWatchdog
+Start-ScheduledTask -TaskName AntigravityMeshWatchdog
+```
+
+Установщик регистрирует задание **`AntigravityMeshWatchdog`**: действие
+`powershell.exe` с аргументами
+`-NoProfile -ExecutionPolicy Bypass -File "<payload>\ops\windows\agent-watchdog.ps1" -Quiet`,
+рабочий каталог - каталог payload (там, где лежит `core\`), триггеры - при входе
+пользователя и повтор каждые 5 минут без ограничения длительности, настройки -
+`-MultipleInstances IgnoreNew`, `-StartWhenAvailable`,
+`-ExecutionTimeLimit 10 минут`. Готовый вызов `Register-ScheduledTask` приведён в
+английской части выше. Каталог `ops\` должен попадать в payload: его нужно указать
+в `package.json` (`files`), в `build-installer-exe.ps1` (`$PAYLOAD`) и в том, что
+`deploy_gateway.sh` выкладывает для узла.