# Legacy Windows First Iteration Runbook

This runbook is for the guarded Windows 7 SP1 and Windows Server 2008 R2 SP1 pilot lane. It covers the first SiteKings/internal build, lab validation, and one customer-scoped doctor-office pilot machine. Do not use it for broad fleet rollout.

## Release Build

Run the release build only on Mac-Studio at `10.0.10.41`.

```bash
cd /path/to/live-edit
scripts/build-legacy-windows-first-iteration.sh --require-mac-studio --legacy-go /path/to/go1.20.x
```

If `SK_LEGACY_GO` already points to a Go 1.20 toolchain, this shorter command is acceptable:

```bash
scripts/build-legacy-windows-first-iteration.sh --require-mac-studio
```

The build wrapper runs `scripts/build-sk-agent-release.sh` and then runs `scripts/legacy-windows-first-iteration-preflight.sh --require-mac-studio`. The preflight verifies build manifest artifact list shape, entry shape, duplicate paths, Mac-Studio host IP provenance, SHA-256 shape, byte size, and the full build-wrapper artifact set before any lab kit or retained evidence is accepted. It also verifies build manifest artifact hashes and sizes match the local files. The full build-wrapper artifact set includes shipped helper scripts and release docs, not only endpoint PowerShell scripts.

## Preflight

Before any lab or customer endpoint receives this lane, verify the release artifacts and focused checks:

```bash
scripts/legacy-windows-first-iteration-preflight.sh --require-mac-studio
```

The preflight must find:

- `client/sk-agent-legacy.ps1`
- `client/sk-watchdog-legacy.ps1`
- `client/sk-tray-legacy.ps1`
- `client/legacy-windows-lab-smoke.ps1`
- `client/upgrade_win10_media.ps1`
- `bin/sk-recover-legacy.exe`
- `bin/sk-recover-legacy.exe.version`
- `bin/sk-agent-checksums.txt`
- `bin/legacy-windows-first-iteration-build-manifest.json`

Retain `legacy-windows-first-iteration-build-manifest.json` with the release bundle. It records the Go 1.20 toolchain, generated time, host IP evidence, artifact sizes, and SHA-256 hashes for the full first-iteration build artifact set, including the legacy agent/watchdog/tray scripts, lab scripts, Windows 10 bridge helper, shipped Python helper scripts, and release docs.

Create the lab handoff kit after the Mac-Studio build passes:

```bash
scripts/legacy-windows-lab-kit.py --output legacy-windows-lab-kit.zip \
  --note "Windows 7 SP1 and Server 2008 R2 SP1 lab handoff"
```

The lab kit includes the built Windows agent, `sk-recover-legacy.exe`, checksum metadata, build manifest, legacy PowerShell scripts, helper scripts including the lab-kit builder and verifier, this runbook, the guarded ship note, and a root-level `README-FIRST.txt`. The lab kit builder rejects retained build manifests without Mac-Studio host IP provenance. The kit builder also writes `legacy-windows-lab-kit.zip.sha256`, a sibling `legacy-windows-lab-kit-verify.py`, and `legacy-windows-lab-kit-verify.py.sha256`; retain them with the ZIP and verify the ZIP hash after transfer to the lab share or endpoint. The ZIP and verifier checksum sidecars must use the generated exact two-token format: `<sha256> <artifact-filename>`. Copy `legacy-windows-lab-kit.zip`, `legacy-windows-lab-kit.zip.sha256`, `legacy-windows-lab-kit-verify.py`, and `legacy-windows-lab-kit-verify.py.sha256` to the lab share or attach them to the retained release evidence before starting the Windows 7 SP1 and Windows Server 2008 R2 SP1 lab order below.

After transfer and before extraction on a machine with Python available, verify the ZIP and every manifest artifact with the sibling verifier emitted from `scripts/legacy-windows-lab-kit-verify.py`; retain `legacy-windows-lab-kit-verify.py.sha256` with it:

```bash
python legacy-windows-lab-kit-verify.py --kit legacy-windows-lab-kit.zip --require-verifier-sidecar
```

The verifier must print `legacy Windows lab kit verification passed` and `verifier self-check: passed`; with `--require-verifier-sidecar`, it fails if `legacy-windows-lab-kit-verify.py.sha256` is missing beside it. The verifier rejects duplicate archive entries and duplicate manifest artifact roles or archive paths before extraction. The verifier revalidates the archived build manifest schema, Go 1.20 provenance, Mac-Studio host IP provenance, artifact list, SHA-256 shape, byte sizes, and required artifact hashes and sizes against the packaged payload files. If Python is not available on the endpoint yet, use `certutil -hashfile legacy-windows-lab-kit.zip SHA256` and compare it with `legacy-windows-lab-kit.zip.sha256`, then run the verifier on Mac-Studio or the lab share before using the kit.

On each lab endpoint, run `payload\client\legacy-windows-lab-run.ps1 -ExercisePeerRecover -ExerciseSelfRescue -ApiKey <test-org-key>` from the extracted lab kit after install, tray, watchdog, and peer-healing checks. Use an elevated PowerShell session; the runner writes `operator-context.json`, and retained readiness requires that file because it must prove the runner used an elevated PowerShell session. In `operator-context.json`, computer_name must match the retained bundle hostname. The runner invokes `legacy-windows-lab-collect.ps1`, writes `LEGACY-LAB-NEXT-STEPS.txt`, and leaves a timestamped `legacy-windows-lab-evidence-*` folder. The collector runs `legacy-windows-lab-smoke.ps1`, captures `SK Agent`, `SK Watchdog`, `SK Tray`, `SKRecoverDaemon`, signed `peer_recover`, firewall, `netstat`, `tasklist`, `operator-context.json`, `status.json`, `win10-probe.json`, `win10_upgrade.status.json`, `win10_upgrade.log`, and repair flags into that evidence folder.

## Lab Order

Use one Windows 7 SP1 lab machine and one Windows Server 2008 R2 SP1 lab machine before touching customer equipment.

1. Install the legacy lane and confirm normal check-in and inventory.
2. Confirm SK Agent, SK Watchdog, SK Tray, and `SKRecoverDaemon` are registered.
3. Confirm SK Tray opens for the active user and Chat with IT includes endpoint context.
4. Kill the legacy agent and confirm watchdog self-correction writes `restart-agent.flag` or restarts the agent.
5. Confirm `sk-recover-legacy.exe` responds on port `47778` at `/health`.
6. Exercise same-LAN peer healing through signed `/recover`; retained smoke must include `peer_recover`.
7. Exercise signed `/self-rescue` where test credentials are available.
8. Queue `__WIN10_PROBE__` and retain the readiness output.
9. Queue `__LEGACY_LAB_SMOKE__` and retain `legacy-windows-lab-smoke.json`.
10. Queue `__LEGACY_LAB_COLLECT__` from RMM or run `legacy-windows-lab-run.ps1` locally, then retain the full evidence folder before reset or upgrade testing.
11. On the machine detail legacy panel, confirm the Last evidence collect summary shows the evidence folder path, captured file count, no missing required files, watchdog log evidence, and `SKRecoverDaemon` evidence.

Validate retained smoke and collector evidence. The smoke JSON must include string `hostname` and string `os_kind` (`windows_7_sp1` or `server_2008_r2`), smoke `ok` must be boolean `true`, its `checks` entries must be objects with nonblank string names and boolean `ok` values, names must be unique, `failed` must be a string list and must not contain hard failures, and the collector manifest `hostname` and `os_kind` must match it. The collector manifest must also include `build_manifest_sha256` and `build_manifest_path`; intake and bundling compare `build_manifest_sha256` against the retained build manifest before accepting the folder:

```bash
scripts/legacy-windows-lab-evidence-check.py legacy-windows-lab-smoke.json \
  --collect-manifest legacy-windows-lab-collector-manifest.json \
  --collect-root legacy-windows-lab-evidence-20260708-201100 \
  --require-self-rescue \
  --require-win10-status
```

Use `-ExercisePeerRecover` and `--require-self-rescue` for the signed rescue lab. Use `--require-win10-status` after `__WIN10_PROBE__` has generated Windows 10 bridge evidence.

## Windows 10 Bridge

The Windows 10 bridge is a guarded exception path for older clinical equipment. Windows 10 is also end-of-life, but it is a safer bridge than Windows 7 when Windows 11 is not supported by the machine or vendor software.

Only queue `__UPGRADE_WIN10_MEDIA__` after all of these are true:

- The endpoint is a Windows 7 SP1 workstation, not Windows Server 2008 R2 SP1.
- `__WIN10_PROBE__` reports a candidate verdict.
- `__LEGACY_LAB_SMOKE__` passes with fresh evidence.
- Backups or an image rollback path exist.
- Windows 10 media is served over HTTPS and has a verified 64-character SHA-256 checksum.
- The operator checks the required bridge acknowledgements and records non-empty evidence notes for customer-scoped enablement, backup evidence, rollback plan, vendor software review, and clinical equipment review. The queued command retains those notes in the Windows 10 bridge payload.
- Vendor software and clinical equipment risk has been reviewed.
- The pilot is customer-scoped and explicitly approved.

Run the first bridge on a sacrificial Windows 7 SP1 machine or VM. Retain:

- `win10_upgrade.status.json`
- `win10_upgrade.log`
- `win10-probe.json`
- The command history entry for `__UPGRADE_WIN10_MEDIA__`
- The post-upgrade inventory and SK Tray/check-in evidence

Validate the retained bridge artifacts:

```bash
scripts/legacy-windows-lab-evidence-check.py legacy-windows-lab-smoke.json \
  --collect-manifest legacy-windows-lab-collector-manifest.json \
  --collect-root legacy-windows-lab-evidence-20260708-201100 \
  --win10-upgrade-status win10_upgrade.status.json \
  --win10-upgrade-log win10_upgrade.log
```

The bridge artifact check expects `win10-probe.json` to show a `candidate` verdict, `win10_upgrade.status.json` to show `probe_verdict: candidate` plus a launched or completed setup stage, and `win10_upgrade.log` to include the Windows 10 bridge start with a redacted media URL, `Probe verdict candidate confirmed before media launch`, `Operator acknowledgements recorded`, `Operator evidence notes recorded: customer-scoped enablement`, and `setup.exe` launch trail. The collect-manifest and collect-root checks require collector manifest `hostname`, collector manifest `os_kind`, `build_manifest_sha256`, `build_manifest_path`, `collector_exit: 0`, `smoke_exit: 0`, and retained evidence files including non-empty smoke JSON, SK Agent/SK Watchdog/SK Tray task captures, `SKRecoverDaemon` service capture, firewall capture, `netstat`, `tasklist`, `watchdog.log`, and `operator-context.json` proving the evidence runner was elevated. The collector manifest file list must contain nonblank string-only, unique plain filenames. The evidence checker rejects the folder if the collector manifest hostname does not match the smoke hostname, if the collector manifest os_kind does not match the smoke os_kind, or if `operator-context.json` `computer_name` does not match the collector manifest hostname.

Create the retained evidence bundle on Mac-Studio with the intake wrapper:

```bash
scripts/legacy-windows-lab-intake.py \
  --collect-root legacy-windows-lab-evidence-20260708-201100 \
  --build-manifest bin/legacy-windows-first-iteration-build-manifest.json \
  --output-dir retained-legacy-windows-evidence \
  --note "sacrificial Windows 7 SP1 bridge VM"
```

The intake wrapper reads `legacy-windows-lab-smoke.json`, classifies the folder as Windows 7 SP1 or Windows Server 2008 R2 SP1, validates the collector manifest and physical files, matches collector manifest `build_manifest_sha256` to the supplied build manifest, requires and retains `win10-probe.json` only for Windows 7 SP1, requires `win10_upgrade.status.json` plus `win10_upgrade.log` for Windows 7 SP1, blocks Windows 10 bridge artifacts and Windows 10 probe evidence on Server 2008 R2 SP1, then writes `legacy-windows-<host>-evidence.zip`.

For troubleshooting or one-off retained evidence, the lower-level bundle command is:

```bash
scripts/legacy-windows-first-iteration-evidence-bundle.py \
  --hostname WIN7-LAB \
  --output legacy-windows-WIN7-LAB-evidence.zip \
  --lab-smoke legacy-windows-lab-smoke.json \
  --collect-manifest legacy-windows-lab-collector-manifest.json \
  --collect-root legacy-windows-lab-evidence-20260708-201100 \
  --build-manifest bin/legacy-windows-first-iteration-build-manifest.json \
  --win10-upgrade-status win10_upgrade.status.json \
  --win10-upgrade-log win10_upgrade.log \
  --note "sacrificial Windows 7 SP1 bridge VM"
```

The bundle includes `manifest.json`, the inferred `os_kind`, SHA-256 hashes, retained artifacts, this runbook, and the guarded ship note. Use the real endpoint hostname and add notes for customer-scoped pilots.
The bundle helper requires collector manifest, collect-root, and build manifest provenance, then validates lab smoke, collector manifest, collector-to-build-manifest SHA-256 provenance, smoke-to-collector hostname/os_kind consistency, exact collect-root smoke artifact preservation, collect-root files, build manifest duplicate artifact paths, build manifest sk-recover-legacy.exe SHA-256/size metadata, Windows 7 bridge/probe requirements, Windows 10 probe verdict, positive RAM, and hardware context, and Server 2008 R2 bridge/probe exclusions before writing the ZIP. It also validates the build manifest and includes the collected evidence folder under `artifacts/legacy-windows-lab-evidence/`, so an evidence bundle cannot be created from missing required smoke checks, mismatched smoke and collector manifest hostnames, smoke-to-collector os_kind mismatches, collector-to-build-manifest SHA-256 mismatches, mismatched top-level and collect-root smoke hostnames or content, missing collector evidence files, missing build provenance, duplicate build manifest artifact paths, missing or invalid recovery daemon hash/size provenance, missing Windows 7 SP1 bridge/probe evidence, a non-candidate Windows 10 probe verdict, non-positive probe RAM, missing probe hardware context, a failed Windows 10 bridge status, Windows 10 bridge artifacts on Server 2008 R2 SP1, or Windows 10 probe evidence on Server 2008 R2 SP1.

When both lab endpoint folders are back on Mac-Studio, run the two-platform finalizer:

```bash
scripts/legacy-windows-first-iteration-finalize.py \
  --win7-collect-root win7/legacy-windows-lab-evidence-20260708-201100 \
  --server-2008-r2-collect-root server2008r2/legacy-windows-lab-evidence-20260708-201100 \
  --build-manifest bin/legacy-windows-first-iteration-build-manifest.json \
  --output-dir retained-legacy-windows-evidence \
  --require-mac-studio \
  --note "two-platform first-iteration lab"
```

The finalizer runs the Mac-Studio intake wrapper for each folder, writes both retained ZIPs, rejects swapped platform folders, duplicate retained lab hostnames, non-Mac-Studio retained-evidence finalization, and retained build manifests without Mac-Studio host IP provenance when --require-mac-studio is used, and then runs the readiness gate. On success it also writes `legacy-windows-first-iteration-final-summary.json`, `legacy-windows-first-iteration-final-summary.json.sha256`, `legacy-windows-first-iteration-pilot-checklist.json`, and `legacy-windows-first-iteration-pilot-checklist.json.sha256` in the retained evidence directory. The final summary records the build manifest path, operator notes, both platform hostnames, retained ZIP paths, SHA-256 hashes, byte sizes, collector exit proof, required smoke check proof, Windows 10 probe verdict and hardware context, Windows 10 bridge acknowledgement, evidence-note, and media URL redaction proof, and the passed readiness status. The pilot checklist records that lab evidence passed, preserves `final_summary_hash_sidecar` evidence, and includes `win10_bridge_media_url_redacted` as passed while customer pilot approval is still blocked on the selected office machine, customer-scoped enablement, backup or image rollback, vendor software review, clinical equipment review, and explicit customer approval. Retain all four files and verify both hash sidecars before customer pilot approval.

After the one doctor-office endpoint is selected and the customer approvals are recorded, write a retained approval artifact. The selected pilot hostname must be the real doctor-office endpoint, not one of the retained lab evidence hostnames. The approval and pilot-readiness gates recheck the final summary operator context with a case-insensitive Windows hostname match so valid evidence is not rejected just because Windows reported `computer_name` in a different case:

```bash
scripts/legacy-windows-first-iteration-pilot-approval.py \
  --checklist retained-legacy-windows-evidence/legacy-windows-first-iteration-pilot-checklist.json \
  --output-dir retained-legacy-windows-evidence \
  --customer "Example Dental" \
  --pilot-hostname FRONTDESK-WIN7 \
  --operator "SiteKings Ops" \
  --approval-ticket SK-1234 \
  --customer-scoped-enablement "Enabled only for Example Dental pilot org" \
  --backup-evidence "Image backup captured before pilot" \
  --rollback-plan "Restore image or use Windows setup rollback" \
  --vendor-software-review "Vendor software reviewed for Windows 10 bridge" \
  --clinical-equipment-review "Clinical peripherals reviewed before pilot" \
  --customer-approval "Office manager approved pilot window"
```

The approval helper verifies the pilot checklist checksum sidecar SHA-256 and filename, rejects duplicate or unknown pilot checklist items, verifies that the checklist final summary reference is present, verifies the final summary checksum sidecar SHA-256 and filename, verifies that `final_summary_hash_sidecar` evidence points to the final summary checksum sidecar, verifies the recorded final summary SHA-256 shape and hash in the checklist, verifies the checklist build manifest SHA-256 shape, verifies the retained build manifest SHA-256 shape and byte size recorded by the final summary, rechecks that the Windows 7 SP1 final summary has `win10_bridge.media_url_query_redacted` true, verifies the selected pilot hostname is a valid Windows computer name using only ASCII letters, numbers, or hyphens that is not one of the retained lab evidence hostnames, and rejects placeholder pilot hostnames or approval evidence such as TBD, pending, unknown, none, or N/A. It then writes `legacy-windows-first-iteration-pilot-approval.json` plus `legacy-windows-first-iteration-pilot-approval.json.sha256`. Retain both files with the final summary and lab bundles. This approval artifact is the machine-readable handoff that turns the lab-passed checklist into a one-machine customer pilot approval; it is not a broad fleet approval.

Checksum sidecars must use the generated exact two-token format: `<sha256> <artifact-filename>`. A sidecar with a matching hash but no filename or extra tokens is not valid retained evidence.

Before touching the selected doctor-office endpoint, run the final pilot readiness verifier:

```bash
scripts/legacy-windows-first-iteration-pilot-readiness.py \
  --approval retained-legacy-windows-evidence/legacy-windows-first-iteration-pilot-approval.json
```

It must print `legacy Windows first-iteration pilot readiness passed`. The verifier checks the pilot approval checksum sidecar SHA-256 and filename, that the source checklist reference is present, that the approval final summary reference is present, the source checklist checksum sidecar SHA-256 and filename, recorded source checklist SHA-256 shape, duplicate or unknown checklist or approval items, the final summary checksum sidecar SHA-256 and filename, recorded final summary SHA-256 shape, approval final summary SHA-256 shape, checklist build manifest SHA-256 shape, approval build manifest SHA-256 shape, retained build manifest SHA-256 shape and byte size, final-summary retained bundle SHA-256 hashes and byte sizes, final-summary collector build manifest SHA-256 proof, duplicate retained lab hostnames, collector exit proof, required smoke proof, Windows 10 probe and bridge proof including `win10_bridge.media_url_query_redacted` is true, required Windows 7 SP1 and Windows Server 2008 R2 SP1 lab evidence, required `final_summary_hash_sidecar` checklist evidence pointing to the final summary checksum sidecar, that `win10_bridge_media_url_redacted` evidence matches the Windows 7 SP1 lab hostname, that the approved pilot hostname is a valid Windows computer name and is not one of the retained lab evidence hostnames, that the approved pilot hostname uses only ASCII letters, numbers, or hyphens, customer-scoped enablement, backup or image rollback proof, vendor software review, clinical equipment review, explicit customer approval, that placeholder approval evidence such as TBD, pending, unknown, none, or N/A is rejected, that approval item evidence matches the approval fields, and that source checklist evidence is preserved in the approval artifact.

Before any customer pilot, validate that retained bundles cover both required legacy platforms. The finalizer does this automatically; the lower-level readiness command is:

```bash
scripts/legacy-windows-first-iteration-readiness.py \
  legacy-windows-WIN7-LAB-evidence.zip \
  legacy-windows-SRV2008R2-LAB-evidence.zip
```

The readiness gate requires one Windows 7 SP1 bundle with Windows 10 probe evidence, Windows 10 bridge launch artifacts, proof that `win10_bridge.acknowledgements_recorded` is true, proof that `win10_bridge.evidence_notes_recorded` is true from a retained `Operator evidence notes recorded: customer-scoped enablement` log line, proof that `win10_bridge.media_url_query_redacted` is true, and one Windows Server 2008 R2 SP1 bundle with the legacy agent, SK Tray, watchdog, `SKRecoverDaemon`, and collector evidence. It also requires positive smoke evidence for SK Agent, SK Watchdog, SK Tray, live `process:sk-agent-legacy`, live `process:sk-tray`, retained `watchdog.log`, SKRecoverDaemon, port 47778, recover health, signed `peer_recover`, firewall, and self-rescue checks. It fails if either platform is missing, if the Windows 7 probe verdict is not `candidate`, if a bundle manifest omits `os_kind`, if a bundle manifest `os_kind` disagrees with the smoke-derived platform identity, if duplicate manifest artifact roles or paths are present, if proof that the collector manifest `collector_exit` and `smoke_exit` are both zero is absent, if the collector manifest `build_manifest_sha256` does not match the archived build manifest, if `operator-context.json` does not prove an elevated runner, if `operator-context.json` `computer_name` does not match the retained bundle hostname, if the Windows 10 bridge acknowledgement, customer-scoped evidence-note, and media URL redaction proof is absent, if the Windows Server 2008 R2 SP1 bundle includes Windows 10 bridge artifacts or Windows 10 probe evidence, or if the peer-healing/self-rescue proof is absent. The finalizer's pilot checklist must still show customer pilot approval as pending until the operator records customer-scoped enablement, backup or rollback proof, vendor software review, clinical equipment review, and customer approval for the one selected doctor-office endpoint.

## Customer Pilot

After lab evidence passes, pick one doctor-office test endpoint only. Keep enablement customer-scoped. Confirm the office understands this is a guarded pilot for legacy equipment, not a general upgrade campaign.

Minimum evidence for the customer pilot:

- Current inventory proves Windows 7 SP1.
- Latest `__WIN10_PROBE__` is fresh and candidate.
- Latest `__LEGACY_LAB_SMOKE__` is fresh and passing.
- Peer healing and watchdog evidence are captured.
- Rollback or image recovery is available before upgrade.
- `legacy-windows-first-iteration-pilot-approval.json` and `legacy-windows-first-iteration-pilot-approval.json.sha256` are retained after customer-scoped enablement, backup or image rollback, vendor software review, clinical equipment review, and explicit customer approval are recorded.
- `scripts/legacy-windows-first-iteration-pilot-readiness.py --approval retained-legacy-windows-evidence/legacy-windows-first-iteration-pilot-approval.json` prints `legacy Windows first-iteration pilot readiness passed`.

## Rollback

If the lane misbehaves before upgrade, stop queueing legacy bridge commands, disable customer-scoped enablement, and reinstall the prior agent lane through the existing installer or force-upgrade path.

If the Windows 10 bridge fails, use the local Windows setup rollback path or the machine image backup. Preserve `win10_upgrade.status.json`, `win10_upgrade.log`, and command output before remediation.
