claudetools/session-logs/2026-06/2026-06-22-howard-gururmm-software-uninstall.md

## User
- **User:** Howard Enos (howard)
- **Machine:** Howard-Home
- **Role:** tech

## Session Summary

Built the GuruRMM remote software-uninstall feature (SPEC-030) end to end, starting
from Howard's reference to `dUninstaller.exe` (a closed-source Codejock GUI binary —
nothing to lift). Confirmed the agent already inventories installed software and has a
robust command pipeline, so the gap was: capture uninstall metadata, an uninstall
engine, and a dashboard. Shaped the feature via `/shape-spec` into
`projects/msp-tools/guru-rmm/specs/remote-software-uninstall/`, then prototyped a
standalone PowerShell engine (`agent/scripts/uninstall-engine.ps1`) implementing a
silent-first tier ladder (MSI `/qn`, QuietUninstallString, detected NSIS/InnoSetup
switch, winget), validated by dry-run across 67 real programs and a live `-List` on
test box DESKTOP-MS42HNC.

Chose "Route B" (server-orchestrated): the server embeds the engine via `include_str!`
and dispatches it over the existing `powershell` command pipeline — no agent rebuild or
redeploy. Built `server/src/api/software.rs` (`GET /software`, `POST /software/uninstall`)
+ dashboard `SoftwareManager.tsx` in the Inventory tab (multi-select, confirm-gated bulk
uninstall, per-program results). Merged to main (PR #47, #48) and deployed; verified live
by removing Everything and FastStone on DESKTOP-MS42HNC through the real endpoints.

Then layered the removal knowledge loop: a per-agent tracking table (migration 061) and,
after Howard refined the model, a fleet knowledge catalog (migration 062,
`software_knowledge`) with three classifications — silent / requires_ui / unknown — keyed
by exact DisplayName, logs kept only for unknowns, dashboard promotion of unknowns. Added
BCU (Bulk Crap Uninstaller, Apache-2.0) informed engine upgrades: NSIS detection by binary
signature, MSI `REBOOT=ReallySuppress` + WiX Package Cache, fail-fast 120s timeout, and a
critical exit-code-capture fix (`Start-Process -PassThru` left `.ExitCode` null →
everything falsely reported success; switched to `System.Diagnostics.Process`). Ran a
multi-round live test battery (MSI, NSIS x2, quiet, vendor Firefox/OneDrive, interactive
AnyDesk, MSI-1605 path) — all correct, removals verified.

Captured three follow-on designs as specs: GuruConnect SPEC-019 (private Backstage GUI
desktop for interactive uninstall), rip-and-replace Tier 1.4 (vendor AV/RMM removal tools
for client takeovers), and Tier 1.5 (BCU-style headless UI automator). Fixed a fleet-wide
`sync.sh` bug that was repeatedly clobbering submodule branch work. Finished with a scoped
3-pass Opus audit (`/rmm-audit`) of the SPEC-030 code against GuruRMM standards; fixed all
HIGH + MEDIUM findings. The engine/catalog work remains on branch
`feat/engine-bcu-improvements` (pushed, NOT merged — Howard wants more validation first).

## Key Decisions

- **Route B (server-orchestrated) over a native agent command type.** The server embeds
  the validated engine and dispatches it via the existing `powershell` pipeline, so the
  feature works on the currently-deployed agent with no rebuild/redeploy. The native
  command-type port is a later internal refactor behind the same REST shape.
- **Windows-only for now; show-only on other OSs.** Removal is gated to Windows agents
  (server returns 501 for non-Windows; dashboard shows the live uninstall UI only on
  Windows and a read-only installed-software list elsewhere). Linux/macOS removal is a
  tracked follow-on.
- **Knowledge catalog keyed by exact DisplayName**, three states (silent/requires_ui/
  unknown); logs saved ONLY for unknown (undocumented) installers; promotion of unknowns
  done via a dashboard action (silent methods still added in engine code, not data-driven).
- **Use vendors' own removal tools for AV/RMM rip-and-replace** (Avast clear, McAfee MCPR,
  etc.) rather than reverse-engineering; host vetted checksummed copies on our infra.
- **GuruConnect owns interactive (Tier-2) removal** — silent removal is figured out first;
  SPEC-019 extends the existing SPEC-013 backstage from terminal to a private GUI desktop.
- **Engine exits 0 on per-target failures** (failures reported in JSON, not exit code) so
  one failed program can't fail a whole bulk batch.
- **Fleet knowledge endpoints are admin-only** (cross-tenant logs + shared writes), matching
  the `list_commands` convention.

## Problems Encountered

- **sync.sh repeatedly reset the guru-rmm submodule**, discarding committed branch work
  mid-build (HEAD jumped to a stale pinned commit twice). Root cause: Phase-3 post-rebase
  ran `git submodule update --init --recursive` unconditionally. Fixed with
  `submodule_update_safe()` that skips any submodule on a branch or with uncommitted
  changes; pushed to parent main so the whole fleet gets it. Recovered orphaned commits via
  cherry-pick onto a feature branch.
- **AnyDesk `--uninstall --silent` hung ~5+ min** (silent flag not honored on the tested
  build). Dropped the AnyDesk vendor rule → it now classifies as needs_remote instantly
  (interactive tier, no launch). Logged as a correction.
- **Exit codes were not captured** — `Start-Process -PassThru` returned `.ExitCode` null,
  so every uninstall mapped to exit 0 / false "success" (a failed MSI 1603 would read as
  removed). Switched to `System.Diagnostics.Process` with async stream reads; verified
  1605 + exit-0 now captured.
- **Engine embedded in server but the server build change-gate only watched `server/`** —
  an engine-only change would silently ship the old engine. Fixed `build-server.sh` to also
  watch `agent/scripts/uninstall-engine.ps1`.
- **Git-Bash `curl` started failing "Permission denied"** (AV/EDR on the workstation after
  many calls). Pivoted RMM API calls to PowerShell `Invoke-RestMethod`.
- **Hand-built JSON with `C:\\` backslashes was mangled** in Git-Bash (collapsed to single
  backslash → invalid JSON, ConvertFrom-Json failed). Fixed by building targets JSON with
  `jq` / extracting from already-valid JSON. Logged as friction.
- **PR auto-create failed** — `vault.sh get-field services/gitea credentials.api-token`
  mis-resolved (returned 4 chars). Worked around by parsing the api-token line directly;
  validated against the Gitea API before use.

## Configuration Changes

Branch `feat/engine-bcu-improvements` (guru-rmm submodule, pushed, NOT merged):
- `agent/scripts/uninstall-engine.ps1` — new engine (tiers, vendor table, binary-NSIS,
  Package Cache, fail-fast, exit-code fix, hardened self-uninstall guard)
- `server/src/api/software.rs` — endpoints (list/uninstall/removal-status/resolve/
  knowledge/classify), os_type gate, admin gating, error-leak fixes, pagination
- `server/src/api/mod.rs` — routes
- `server/src/db/software_removal.rs`, `server/src/db/software_knowledge.rs`, `db/mod.rs`
- `server/migrations/061_software_removal_attempts.sql`, `062_software_knowledge.sql`
- `dashboard/src/api/client.ts`, `dashboard/src/components/SoftwareManager.tsx`,
  `dashboard/src/components/InventoryTab.tsx`, `dashboard/src/pages/AgentDetail.tsx`
- `deploy/build-pipeline/build-server.sh` — change-gate watches the embedded engine
- `specs/remote-software-uninstall/` — plan, shape, references, standards, task1-results,
  bcu-research-and-tiers, knowledge-base-design, rip-and-replace-removal-tools
- `reports/2026-06-22-spec030-software-uninstall-audit.md`

Already on guru-rmm main (deployed): base inventory+uninstall + per-device tracking
(PR #47 merge 42681f2c, PR #48 merge c4c0ea7).

guru-connect submodule: `docs/specs/SPEC-019-private-backstage-session.md` +
`docs/FEATURE_ROADMAP.md` on branch `feat/spec-019-backstage-uninstall` (pushed, off main).

Parent claudetools (pushed to main): `.claude/scripts/sync.sh` (submodule_update_safe),
`.claude/memory/feedback_submodule_autosync_discipline.md`, `errorlog.md`.

## Credentials & Secrets

- No new credentials created. RMM admin creds read from vault
  `infrastructure/gururmm-server.sops.yaml` fields
  `credentials.gururmm-api.admin-email` / `admin-password` (used for API auth during
  testing). Gitea API token at `services/gitea` field `credentials.api-token` (used for
  PR create/merge). Temp credential files written under `.claude/tmp/` during testing were
  shredded; `.claude/tmp` is gitignored.

## Infrastructure & Servers

- GuruRMM API/server: `http://172.16.3.30:3001` (prod; also the build host, user `guru`,
  repo `/home/guru/gururmm`). Beta dashboard: `https://rmm-beta.azcomputerguru.com`
  (built from main, talks to prod API). Prod dashboard: `https://rmm.azcomputerguru.com`.
- Gitea internal API: `http://172.16.3.20:3000` (repo `azcomputerguru/gururmm`,
  `azcomputerguru/guru-connect`). Public host `git.azcomputerguru.com` is behind
  Cloudflare (blocks curl).
- Test box: **DESKTOP-MS42HNC** — AZ Computer Guru / Howard-VM, Windows, agent id
  `0de89b88-b21d-4647-ab64-96157ba87cc5`.

## Commands & Outputs

- Run engine standalone: `powershell -NoProfile -ExecutionPolicy Bypass -File
  agent/scripts/uninstall-engine.ps1 -List` (JSON inventory) /
  `... -TargetsJson <file> [-DryRun]`.
- Server build check: `SQLX_OFFLINE=true cargo check -p gururmm-server` (clean).
- Dashboard: `npx tsc -p tsconfig.app.json --noEmit` + `npm run build` (clean).
- Live results: classification 104/120 silent-capable on DESKTOP-MS42HNC; removed
  Everything, FastStone, HandBrake, ImgBurn, Paint.NET, GIMP, Firefox, OneDrive, AIMP
  (verified gone); AnyDesk correctly retained as needs_remote; fake-GUID MSI → exit 1605
  "not installed".
- Gitea PR+merge via `Invoke-RestMethod` / token from vault api-token line.

## Pending / Incomplete Tasks

- **Merge + deploy `feat/engine-bcu-improvements`** (engine improvements + knowledge
  catalog + audit fixes). Not merged per Howard ("keep testing before live"). Post-deploy:
  verify catalog populates + promote an unknown live; the catalog/dashboard cannot be
  exercised end-to-end until deployed (live server still runs the old engine).
- **Audit LOW items** (tracked in the report): `warn!` on audit-write failure, randomized
  temp filename, TS interface completeness, empty-states, ASCII em-dash/ellipsis cleanup.
- **GuruConnect SPEC-019** (private Backstage GUI desktop) — branch pushed, not merged.
- **Rip-and-replace Tier 1.4** (AV/RMM vendor removal tools) — spec written, not built.
- **Tier 1.5** (headless UI automator) — spec written, not built.
- **Linux/macOS removal** — Windows-only today; tracked follow-on.

## Reference Information

- Branch: `feat/engine-bcu-improvements` (guru-rmm) — latest commit `c982352`.
- Merged to guru-rmm main: PR #47 (`42681f2c`), PR #48 (`c4c0ea7`).
- guru-connect branch: `feat/spec-019-backstage-uninstall`; SPEC-019.
- Parent commits: `9108f94` (sync fix), `7ad4353` (memory).
- Specs: `projects/msp-tools/guru-rmm/specs/remote-software-uninstall/` (8 docs).
- Audit report: `projects/msp-tools/guru-rmm/reports/2026-06-22-spec030-software-uninstall-audit.md`.
- BCUninstaller (Apache-2.0): https://github.com/BCUninstaller/Bulk-Crap-Uninstaller
- Engine embed path: server `include_str!("../../../agent/scripts/uninstall-engine.ps1")`.

## Update: 19:15 PT — standards audit, fixes, and re-check

Ran a scoped `/rmm-audit` (3 parallel Opus passes: Rust/API/migrations, TypeScript,
engine/platform/security) against the actual GuruRMM standards. Core was compliant
(runtime sqlx, idempotent migrations, no unwrap/panic, injection-safe base64 dispatch,
audit logging, confirm-gated UI, ASCII engine markers). Fixed all HIGH + MEDIUM:
platform-parity (server gates on `os_type` → 501 non-Windows; dashboard shows live
uninstall only on Windows, read-only inventory list elsewhere — per Howard's
Windows-only-for-now call); admin-gated the fleet knowledge endpoints; stopped
agent-stderr error leakage; paginated the catalog; hardened the self-uninstall guard;
surfaced the dashboard knowledge-query error. Then fixed all LOW: `warn!` on audit-write
failure (via an `audit()` helper), randomized temp filenames, complete TS interfaces,
stable list keys + empty-states, ASCII-only strings.

Per Howard's request, ran a fresh Opus re-check of the post-fix branch. It caught a
**CRITICAL regression introduced by my own round-1 fix**: the hardened self-uninstall
guard read `$Target.install_location`, a field the server's `UninstallTarget` never
sends → under `Set-StrictMode` that throws → engine exit 3 → every bulk uninstall
failed, while `-List`/inventory kept working and masked it. Round-1 live tests passed
only because they used `-List`-shaped targets (which include `install_location`). Fixed
with a StrictMode-safe `Get-Prop` accessor routed through all `$Target.*` reads;
verified live with a **server-shaped target** (no `install_location`): 7-Zip removed,
exit 0; GuruRMM self still refused. Re-check also found + fixed a MEDIUM (knowledge
classified on attempted tier not outcome → a failed silent attempt mislabeled `silent`
and its log discarded; now classifies on outcome) and a LOW (`observe()` could null an
existing unknown's log → `COALESCE`). Logged the testing-shape lesson to errorlog
(friction): always re-test the destructive path with the actual serialized caller shape.

### Update — Configuration Changes (additional, all on `feat/engine-bcu-improvements`)
- `server/src/api/software.rs` — os_type gate, admin-gating, error-leak fixes,
  pagination, `audit()` helper, random temp filenames, knowledge-class-by-outcome
- `server/src/db/software_knowledge.rs` — `list()` limit param, `observe()` log COALESCE
- `agent/scripts/uninstall-engine.ps1` — `Get-Prop` StrictMode-safe accessor + guard fix
- `dashboard/src/components/InventoryTab.tsx` — Windows-only gating (read-only list on
  other OSs), `isWindows` prop
- `dashboard/src/components/SoftwareManager.tsx`, `dashboard/src/api/client.ts` — KB error
  surfacing, ASCII, empty-states, interface completeness
- `dashboard/src/pages/AgentDetail.tsx` — pass `isWindows` to InventoryTab
- `reports/2026-06-22-spec030-software-uninstall-audit.md` — audit report + round-2 re-check

### Update — Pending / Incomplete Tasks (current)
- Still NOT merged (prod untouched). Branch `feat/engine-bcu-improvements` head `0e8323b`.
- Merge + deploy when ready; post-deploy verify the catalog populates + promote an unknown.
- Follow-ons unchanged: GuruConnect SPEC-019, rip-and-replace Tier 1.4, Tier 1.5, Linux/macOS.

### Update — Reference (current)
- Branch head: `0e8323b` (guru-rmm `feat/engine-bcu-improvements`).
- Key commits this update: `584c3bc` (HIGH/MED), `c3e6259` (LOW), `6c8cbb1` (re-audit
  CRITICAL/MED/LOW), `0e8323b` (report round-2). Earlier parent sync log `86c789a`.