sync: auto-sync from GURU-5070 at 2026-05-24 13:57:13

Author: Mike Swanson
Machine: GURU-5070
Timestamp: 2026-05-24 13:57:13

.claude/machines/pluto.md

@@ -0,0 +1,210 @@
+# Machine: Pluto (Claude-Builder)
+
+**Hostname:** Pluto / Claude-Builder
+**Last Updated:** 2026-05-24
+
+---
+
+## Identity
+
+Pluto is the **Windows build VM** for GuruRMM. It is the only machine in the fleet
+that produces Windows agent binaries and the WiX MSI installer. It is NOT a
+general-purpose workstation — it has no Claude Code, no vault, no coord API access.
+Its sole function is to run `cargo build` for Windows targets when `build-windows.sh`
+SSHes in.
+
+---
+
+## Hardware & Location
+
+| Spec | Value |
+|------|-------|
+| VM name | Claude-Builder (virsh domain on Jupiter) |
+| Host | Jupiter — Unraid primary, IP 172.16.3.20 |
+| VM IP | 172.16.3.36 |
+| OS | Windows Server 2019 (Standard) |
+| SSH user | Administrator |
+| SSH port | 22 |
+| SSH auth | Public key, from build server (172.16.3.30) |
+
+Pluto is a virsh VM. If it is unreachable from 172.16.3.30 but was recently
+building, check Jupiter first (`virsh list --all` on 172.16.3.20) before
+assuming a crash. SSH from DESKTOP-0O8A1RL and SSH from 172.16.3.30 traverse
+different network paths — one failing does not imply the other fails.
+
+---
+
+## Build Tools
+
+| Tool | Path |
+|------|------|
+| cargo (Rust stable) | `C:\Users\Administrator\.cargo\bin\cargo.exe` |
+| rustup | `C:\Users\Administrator\.cargo\bin\rustup.exe` |
+| WiX 4 (MSI builder) | `C:\Users\Administrator\.dotnet\tools\wix.exe` |
+| sccache | `C:\sccache\` (compiler cache, causes near-instant rebuilds when source unchanged) |
+| Git | standard PATH |
+
+**sccache note:** When agent/ has no code changes (only config bumps), sccache
+makes the full 5-target cargo run complete in ~1s rather than 3–5 min. This is
+expected and correct — do not interpret a fast build as a failed build.
+
+---
+
+## Repo
+
+| Item | Value |
+|------|-------|
+| Clone path | `C:\gururmm` |
+| Remote | Gitea: `https://azcomputerguru@git.azcomputerguru.com/azcomputerguru/gururmm.git` |
+| Branch | main (build-windows.sh pulls latest before building) |
+
+---
+
+## Build Role in Pipeline
+
+Pluto is invoked by `build-windows.sh` on the build server (172.16.3.30) via SSH.
+It is called only when `agent/` has changed since the last Windows build
+(`/opt/gururmm/last-built-commit-windows`).
+
+### What Pluto does (in order):
+
+```
+1. git pull (build-windows.sh does this via SSH before cargo invocations)
+2. cargo build --release --target x86_64-pc-windows-msvc     → stable x64
+3. cargo build --features debug-agent --target x86_64-pc-windows-msvc  → debug x64
+4. cargo build --release --target i686-pc-windows-msvc        → stable x86
+5. cargo build --release --target x86_64-pc-windows-msvc (legacy profile) → legacy x64
+6. cargo build --release --target i686-pc-windows-msvc (legacy profile)  → legacy x86
+7. wix build (WiX 4) → GuruRMM-<version>-x64.msi
+```
+
+All five cargo invocations run sequentially on Pluto. The MSI is built after all
+binaries complete.
+
+### Output artifacts (on Pluto):
+
+| Artifact | Pluto path |
+|----------|-----------|
+| Agent EXE (x64) | `C:\gururmm\target\x86_64-pc-windows-msvc\release\gururmm-agent.exe` |
+| Agent EXE (x86) | `C:\gururmm\target\i686-pc-windows-msvc\release\gururmm-agent.exe` |
+| Tray EXE | `C:\gururmm\target\x86_64-pc-windows-msvc\release\gururmm-tray.exe` |
+| MSI | `C:\gururmm\target\wix\GuruRMM-<version>-x64.msi` |
+
+`build-windows.sh` SCPs these from Pluto to the build server's distribution
+directory (`/var/www/gururmm/downloads/`) after the build completes.
+
+---
+
+## Connection from Build Server
+
+```bash
+# From 172.16.3.30 (build server), as guru
+ssh -o StrictHostKeyChecking=yes \
+    -o UserKnownHostsFile=/opt/gururmm/pluto_known_hosts \
+    Administrator@172.16.3.36
+```
+
+The known-hosts file at `/opt/gururmm/pluto_known_hosts` contains three pinned
+keys (RSA, ECDSA, ED25519) for 172.16.3.36. **Never use StrictHostKeyChecking=no
+for Pluto** — it would accept a MITM and inject malicious binaries into the
+build artifacts.
+
+To update the pinned keys (e.g., after OS reinstall):
+```bash
+ssh-keyscan 172.16.3.36 > /opt/gururmm/pluto_known_hosts
+```
+
+---
+
+## Pipeline Context
+
+| Script | Role |
+|--------|------|
+| `/opt/gururmm/webhook-handler.py` | Receives Gitea webhook on 172.16.3.30:9000, forks build threads |
+| `/opt/gururmm/build-shared.sh` | Version bump + repo sync; runs once per trigger |
+| `/opt/gururmm/build-linux.sh` | Linux cargo build; independent of Pluto |
+| `/opt/gururmm/build-windows.sh` | Invokes Pluto via SSH; handles change gate + artifact copy |
+| `/opt/gururmm/build-mac.sh` | Stub; no Mac build machine configured |
+
+`build-linux.sh` and `build-windows.sh` run in parallel threads from
+`webhook-handler.py` after `build-shared.sh` succeeds.
+
+### Build logs on 172.16.3.30:
+
+| Log | Content |
+|-----|---------|
+| `/var/log/gururmm-build-linux.log` | Linux build output |
+| `/var/log/gururmm-build-windows.log` | Windows build + Pluto SSH output (prefixed `[PLUTO]`) |
+| `/var/log/gururmm-build-mac.log` | Mac stub (minimal) |
+
+### Change tracking:
+
+| File | Tracks |
+|------|--------|
+| `/opt/gururmm/last-built-commit-linux` | Last SHA successfully built on Linux |
+| `/opt/gururmm/last-built-commit-windows` | Last SHA successfully built on Windows (Pluto) |
+| `/opt/gururmm/last-built-commit-mac` | Last SHA successfully built on Mac (stub) |
+
+---
+
+## Distribution Directory (on 172.16.3.30)
+
+Active artifacts served via nginx:
+
+```
+/var/www/gururmm/downloads/
+  windows/
+    amd64/
+      GuruRMM-<version>-x64.msi
+      gururmm-agent-<version>.exe
+      gururmm-tray-<version>.exe   (latest 2 versions kept)
+    x86/
+      gururmm-agent-<version>.exe
+```
+
+The legacy path `/opt/gururmm/updates/windows/amd64/` contains only old artifacts
+from before the pipeline split (last modified ~Feb 2026). It is NOT the active
+distribution path — do not check it to assess build freshness.
+
+---
+
+## Build Trigger Rules
+
+A build to Pluto is only initiated when:
+1. A push to `main` hits the Gitea webhook
+2. `build-shared.sh` succeeds (version bump + git sync)
+3. The diff between the new SHA and `last-built-commit-windows` includes changes
+   under `agent/` (excluding `agent/Cargo.lock`)
+
+If only `server/`, `dashboard/`, or docs changed, Pluto is NOT contacted.
+The Windows lock file (`/var/run/gururmm-build-windows.lock`) prevents concurrent
+builds if a previous run is still active.
+
+---
+
+## Capabilities
+
+- [x] Windows cargo builds (stable x64, debug x64, stable x86, legacy x64, legacy x86)
+- [x] WiX 4 MSI packaging
+- [x] sccache (compiler-level cache, C:\sccache)
+- [x] SSH access from 172.16.3.30 (key auth, pinned known-hosts)
+- [x] Git (pulls gururmm repo from Gitea)
+- [ ] Claude Code (not installed)
+- [ ] SOPS vault (not installed)
+- [ ] Coord API access (not installed)
+- [ ] Mac cross-compilation (not configured)
+
+---
+
+## Notes
+
+- **Do not SSH to Pluto manually to trigger builds.** All builds go through the
+  Gitea webhook pipeline. Manual SSH is for diagnostics only.
+- **If Pluto appears unreachable from DESKTOP:** Verify from 172.16.3.30 first.
+  Different network paths. DESKTOP is not on the same LAN segment as Pluto.
+- **sccache makes short work of rebuild-only pushes.** A 1-second Windows build
+  is normal when agent/ source hasn't changed since the last successful build.
+- **Build history:** Pluto has been building GuruRMM Windows agents since at least
+  early 2026. The MSI + EXE artifacts in `/var/www/gururmm/downloads/` are
+  authoritative freshness indicators — check their timestamps, not the legacy
+  `/opt/gururmm/updates/` path.

.claude/skills/rmm-audit/SKILL.md

@@ -1,14 +1,16 @@
 ---
 name: rmm-audit
 description: |
-  Periodic end-to-end verification of the GuruRMM codebase. Runs 5 parallel audit
+  Periodic end-to-end verification of the GuruRMM codebase and build infrastructure.
-  passes: (1) API/route inventory cross-reference, (2) UI coverage and gap update,
+  Runs 5 parallel audit passes: (1) API/route inventory cross-reference, (2) UI
-  (3) Rust code quality and standards compliance, (4) TypeScript/frontend quality,
+  coverage and gap update, (3) Rust code quality and standards compliance,
-  (5) security and data integrity. Produces a timestamped audit report and updates
+  (4) TypeScript/frontend quality, (5) security and data integrity. A 6th sequential
-  the living docs (UI_GAPS.md, FEATURE_ROADMAP.md). Takes 10-20 minutes.
+  pass audits build pipeline health (logs, artifacts, change gates, script integrity).
+  Produces a timestamped audit report and updates the living docs (UI_GAPS.md,
+  FEATURE_ROADMAP.md). Takes 10-20 minutes.
 
   Invoke explicitly only — no auto-trigger. Use /rmm-audit for a full audit.
-  Optional arg: --pass=<name> to run a single pass (api, ui, rust, ts, security).
+  Optional arg: --pass=<name> to run a single pass (api, ui, rust, ts, security, pipeline).
 ---
 
 # GuruRMM End-to-End Audit
@@ -22,14 +24,16 @@ report file and living docs are updated. No code is changed.
 
 ```
 Phase 0: Context load (coordinator reads key files)
-Phase 1: Spawn 4 parallel audit agents
+Phase 1: Spawn 5 parallel audit agents (codebase passes)
-Phase 2: Collect findings, aggregate, score
+Phase 2: Run build pipeline audit (sequential — requires SSH to build server)
-Phase 3: Write report + update living docs
+Phase 3: Collect findings, aggregate, score
-Phase 4: Present summary to user
+Phase 4: Write report + update living docs
+Phase 5: Present summary to user
 ```
 
-The audit is orchestrated here (Claude coordinator). All heavy passes run in
+The audit is orchestrated here (Claude coordinator). All codebase passes run in
-parallel subagents. Each agent returns structured findings; the coordinator
+parallel subagents. The build pipeline pass runs sequentially after (it touches
+live server state via SSH). Each agent returns structured findings; the coordinator
 aggregates and writes the final report.
 
 ---
@@ -214,9 +218,128 @@ Return structured findings with file:line references.
 
 ---
 
-## Phase 2: Aggregating Findings
+---
 
-Collect all four agents' outputs. Classify each finding:
+### Agent E — Build Pipeline Health
+
+**Goal:** Verify the build/deploy infrastructure is functioning correctly and producing
+fresh, trustworthy artifacts. This pass catches issues invisible to codebase-only
+audits: log rot, stale artifacts, dead pipeline paths, and change gate failures.
+
+**NOTE:** This agent runs sequentially (after Agents A–D complete) because it SSHes
+into the live build server. It is read-only — it checks state but does not trigger builds.
+
+**Instructions for agent:**
+
+Connect to the build server: `ssh guru@172.16.3.30`
+
+**1. Log integrity — check for doubling and freshness:**
+
+```bash
+# Check Windows build log — each line should appear exactly once
+tail -50 /var/log/gururmm-build-windows.log
+# Check Linux build log
+tail -50 /var/log/gururmm-build-linux.log
+```
+
+- Lines duplicated (same content appearing twice in a row) → `[HIGH]` log doubling — double-writer bug
+- Last entry timestamp > 7 days old AND recent pushes known → `[HIGH]` stale log — builds may be silently failing
+- Log file missing entirely → `[CRITICAL]` — build infrastructure not initialised
+- Presence of `=== PHASE:` markers → `[INFO]` phase tracking is active (expected)
+
+**2. Artifact freshness — check distribution directory:**
+
+```bash
+ls -lht /var/www/gururmm/downloads/windows/amd64/ | head -10
+ls -lht /var/www/gururmm/downloads/linux/amd64/ | head -10
+```
+
+- Newest MSI/EXE older than 14 days AND active development confirmed → `[HIGH]` artifacts stale
+- Legacy path `/opt/gururmm/updates/windows/amd64/` should NOT be served (it is the old path); if a
+  symlink or nginx config still points there → `[HIGH]` dead artifact path still active
+
+**3. Per-platform last-built-commit recency:**
+
+```bash
+cat /opt/gururmm/last-built-commit-linux
+cat /opt/gururmm/last-built-commit-windows
+cat /opt/gururmm/last-built-commit-mac
+```
+
+- SHA should be recent relative to `git log --oneline -5` in `/home/guru/gururmm`
+- Linux and Windows SHAs diverging by many commits → `[MEDIUM]` platform builds out of sync
+- A SHA that resolves to a commit months old while git log shows recent work → `[HIGH]` change gate stuck
+
+**4. Stale lock files:**
+
+```bash
+ls -la /var/run/gururmm-build-*.lock 2>/dev/null
+```
+
+- Lock file present with no corresponding running process → `[HIGH]` orphaned lock, all future builds for that
+  platform will be blocked until manually removed
+- Check: `ps aux | grep build-` — if no `build-linux.sh` / `build-windows.sh` running but lock exists, it's orphaned
+
+**5. Script syntax validity:**
+
+```bash
+bash -n /opt/gururmm/build-shared.sh
+bash -n /opt/gururmm/build-linux.sh
+bash -n /opt/gururmm/build-windows.sh
+bash -n /opt/gururmm/build-mac.sh
+```
+
+- Any syntax error → `[CRITICAL]` — that platform's builds will silently fail at next trigger
+
+**6. Webhook handler health:**
+
+```bash
+curl -s http://localhost:9000/health
+ps aux | grep webhook-handler
+```
+
+- `/health` returns non-200 or connection refused → `[CRITICAL]` webhook handler down
+- Handler not in process list → `[CRITICAL]` handler not running
+- Check handler is using the new multi-threaded version (should mention `PLATFORMS` in its source):
+  `grep -c PLATFORMS /opt/gururmm/webhook-handler.py`
+  Count of 0 → `[HIGH]` old monolithic handler still deployed
+
+**7. Pluto known-hosts file:**
+
+```bash
+ls -la /opt/gururmm/pluto_known_hosts
+wc -l /opt/gururmm/pluto_known_hosts
+```
+
+- File missing → `[CRITICAL]` Windows builds will fail (SSH strict host checking with no key file)
+- File empty (0 lines) → `[CRITICAL]` same
+- Confirm `build-windows.sh` references it: `grep pluto_known_hosts /opt/gururmm/build-windows.sh`
+  If missing → `[HIGH]` StrictHostKeyChecking=no likely, MITM risk on build artifacts
+
+**8. Tray EXE accumulation:**
+
+```bash
+ls -lht /var/www/gururmm/downloads/windows/amd64/gururmm-tray-* 2>/dev/null | wc -l
+```
+
+- More than 3 tray EXE versions present → `[LOW]` cleanup not running (design: keep latest 2)
+
+**9. Build compat wrapper check:**
+
+```bash
+head -5 /opt/gururmm/build-agents.sh
+```
+
+- Should begin with a deprecation warning and call to `build-shared.sh`
+- If it still contains the old monolithic build logic → `[HIGH]` pipeline split not deployed
+
+Return structured findings with source (file path + line or command output) for every finding.
+
+---
+
+## Phase 3: Aggregating Findings
+
+Collect all five agents' outputs. Classify each finding:
 
 | Severity | Meaning |
 |----------|---------|
@@ -244,7 +367,7 @@ Write to: `projects/msp-tools/guru-rmm/reports/YYYY-MM-DD-rmm-audit.md`
 # GuruRMM Audit Report — YYYY-MM-DD
 
 **Auditor:** Claude (claude-sonnet-4-6)
-**Passes:** API Coverage, UI Gaps, Rust Quality, TypeScript Quality, Data Integrity
+**Passes:** API Coverage, UI Gaps, Rust Quality, TypeScript Quality, Data Integrity, Build Pipeline
 **Previous audit:** [link to prior report if one exists, else "First audit"]
 
 ---
@@ -258,6 +381,7 @@ Write to: `projects/msp-tools/guru-rmm/reports/YYYY-MM-DD-rmm-audit.md`
 | Rust Quality | N | N | N | N | N |
 | TypeScript | N | N | N | N | N |
 | Data Integrity | N | N | N | N | N |
+| Build Pipeline | N | N | N | N | N |
 | **TOTAL** | **N** | **N** | **N** | **N** | **N** |
 
 **Requires immediate action:** [list of CRITICAL findings in one line each]
@@ -300,6 +424,13 @@ are now COMPLETE vs. still open vs. newly discovered.]
 
 ---
 
+## Pass 6: Build Pipeline Health
+
+[findings — log integrity, artifact freshness, change gate state, lock files, script
+syntax, webhook handler health, Pluto known-hosts, tray EXE accumulation]
+
+---
+
 ## UI_GAPS.md Delta
 
 Items completed since last audit:
@@ -330,7 +461,7 @@ After writing the report, update `docs/UI_GAPS.md`:
 
 ---
 
-## Phase 4: User Summary
+## Phase 5: User Summary
 
 Present a concise summary to the user:
 
@@ -341,6 +472,7 @@ CRITICAL (N): [one-line each]
 HIGH (N):     [one-line each]
 MEDIUM (N):   Batched in report.
 
+Pipeline: [one-line status — e.g. "all green" or highest-severity finding]
 UI_GAPS.md: N items marked complete, N new gaps added.
 
 Recommended first action: [the single highest-priority finding]
@@ -402,3 +534,19 @@ Then ask: "Want me to start on any of these findings?"
 | UI gaps tracker | `projects/msp-tools/guru-rmm/docs/UI_GAPS.md` |
 | Architecture decisions | `projects/msp-tools/guru-rmm/docs/ARCHITECTURE_DECISIONS.md` |
 | Past audit reports | `projects/msp-tools/guru-rmm/reports/` |
+
+### Build Pipeline (on 172.16.3.30)
+| Area | Path |
+|------|------|
+| Webhook handler | `/opt/gururmm/webhook-handler.py` |
+| Shared build script | `/opt/gururmm/build-shared.sh` |
+| Linux build script | `/opt/gururmm/build-linux.sh` |
+| Windows build script | `/opt/gururmm/build-windows.sh` |
+| Mac build script | `/opt/gururmm/build-mac.sh` |
+| Pluto known-hosts | `/opt/gururmm/pluto_known_hosts` |
+| Linux build log | `/var/log/gururmm-build-linux.log` |
+| Windows build log | `/var/log/gururmm-build-windows.log` |
+| Distribution dir | `/var/www/gururmm/downloads/` |
+| Per-platform last SHA | `/opt/gururmm/last-built-commit-{linux,windows,mac}` |
+| Lock files | `/var/run/gururmm-build-{linux,windows,mac}.lock` |
+| Pluto machine doc | `.claude/machines/pluto.md` |