# Refactor And Installer Refresh Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Improve the most relevant maintainability hot spots for the installer release, verify behavior, rebuild Mac/Android installers, and publish current download metadata.

**Architecture:** Start from the desktop runtime orchestration surface because it directly affects the Mac installer and has focused coverage. Extract owned subsystems instead of moving code mechanically: health probing and runtime probe timers get their own files, then the orchestrator remains the lifecycle coordinator.

**Tech Stack:** TypeScript, Electron, Vitest, Vite, Android Gradle, Cloudflare Pages.

---

### Task 1: Desktop Runtime Probe Extraction

**Files:**
- Create: `platforms/desktop/src/runtime-health.ts`
- Create: `platforms/desktop/src/runtime-probe-controller.ts`
- Modify: `platforms/desktop/src/runtime-orchestrator.ts`
- Test: `platforms/desktop/test/runtime-orchestrator.test.ts`

- [ ] **Step 1: Extract runtime health checking**

Move the fetch/timeout/title-grep logic from `RuntimeOrchestrator.checkHealth()` into `checkRuntimeHealth(origin, options)`, and leave `RuntimeOrchestrator.checkHealth()` as the public delegating API.

- [ ] **Step 2: Extract attached/recovery probes**

Create `RuntimeProbeController` to own attached/recovery timers, generation counters, in-flight guards, and failure counters. Wire it into `RuntimeOrchestrator.setUrl()`, `handleCrash()`, `restart()`, `shutdown()`, and `dispose()`.

- [ ] **Step 3: Run focused desktop tests**

Run: `./node_modules/.bin/vitest run test/runtime-orchestrator.test.ts --passWithNoTests`

Expected: all runtime orchestrator tests pass.

### Task 2: Validation And Installer Rebuild

**Files:**
- Modify if artifact inputs change: `platforms/android/app/src/main/assets/termux/zonegaze-flow-runtime.tgz`
- Modify if version metadata changes: `platforms/desktop/package.json`, `platforms/desktop/package-lock.json`

- [ ] **Step 1: Run Flow validation**

Run the closest checks for touched desktop code, then web/runtime builds needed by installer packaging.

- [ ] **Step 2: Rebuild Mac and Android installers**

Build unsigned Mac DMGs for arm64/x64 when no signing identity is available, and build the signed Android release APK.

- [ ] **Step 3: Verify artifacts**

Use `hdiutil verify` for DMGs and `apksigner verify` for the APK. Record file size and SHA-256 for every published artifact.

### Task 3: Website Download Update

**Files:**
- Modify: ZoneGaze Web `src/data/downloads.ts`
- Modify: ZoneGaze Web `tests/site-contract.test.ts`
- Add/remove: ZoneGaze Web `public/downloads/assets/zonegaze-flow/<version>/...`

- [ ] **Step 1: Update assets and metadata**

Publish chunked Mac manifests and direct Android APK path with verified byte sizes and SHA-256 values.

- [ ] **Step 2: Validate and deploy web**

Run `vitest`, `astro check`, `astro build`, deploy with Wrangler, then verify `https://zonegaze.com/downloads` and installer endpoints.

- [ ] **Step 3: Close out branches**

Commit validated changes, merge task branches to `development`, push, restart Flow at `http://127.0.0.1:4217/demo-website`, and verify with browser evidence.
