# Ship Note

Lane: Guarded Release Lane

Changed area: Legacy Windows first iteration for Windows 7 SP1 and Windows Server 2008 R2 SP1 endpoints. The pilot release covers the PowerShell legacy agent, SK watchdog, SK Tray, the Go 1.20-built `sk-recover-legacy.exe` peer healing daemon, operator-triggered `__LEGACY_LAB_SMOKE__`, remote `__LEGACY_LAB_COLLECT__` evidence collection, the guarded Windows 10 bridge commands `__WIN10_PROBE__` and `__UPGRADE_WIN10_MEDIA__`, and explicit legacy-lane visibility on the organization install page, public installer page, and artifact catalog.

Required release artifacts:

- `client/sk-agent-legacy.ps1`
- `client/sk-watchdog-legacy.ps1`
- `client/sk-tray-legacy.ps1`
- `client/legacy-windows-lab-smoke.ps1`
- `client/legacy-windows-lab-collect.ps1`
- `client/legacy-windows-lab-run.ps1`
- `client/upgrade_win10_media.ps1`
- `bin/sk-recover-legacy.exe`
- `bin/sk-recover-legacy.exe.version`
- `bin/sk-agent-checksums.txt` with a `sk-recover-legacy.exe` entry
- `bin/legacy-windows-first-iteration-build-manifest.json` with Go 1.20 provenance and SHA-256 hashes
- `scripts/legacy-windows-lab-intake.py` for Mac-Studio evidence intake and retained bundle creation
- `scripts/legacy-windows-first-iteration-finalize.py` for two-platform intake plus readiness and `legacy-windows-first-iteration-final-summary.json`
- `scripts/legacy-windows-first-iteration-pilot-approval.py` for retained one-machine customer pilot approval after lab readiness passes
- `scripts/legacy-windows-first-iteration-pilot-readiness.py` for the final retained approval/readiness chain check before touching the office endpoint
- `scripts/legacy-windows-lab-kit-verify.py` for ZIP sidecar and manifest-artifact verification after kit transfer
- `legacy-windows-lab-kit.zip`, `legacy-windows-lab-kit.zip.sha256`, sibling `legacy-windows-lab-kit-verify.py`, and `legacy-windows-lab-kit-verify.py.sha256` created by `scripts/legacy-windows-lab-kit.py` for lab handoff, including root-level `README-FIRST.txt`; both sidecars must use the exact two-token format `<sha256> <artifact-filename>`

Verification run:

- Local source gate on 2026-07-09: `scripts/legacy-windows-first-iteration-preflight.sh --source-only` passed with 398 pytest checks, the legacy recovery Go test, and two expected duplicate-entry warnings from negative ZIP tamper fixtures.
- Install-page slice on 2026-07-09: `tests/test_legacy_windows_install_pages_source.py` and `tests/test_public_install_source.py` passed. The broader selector also exposed unrelated dirty-worktree baseline failures in archived/missing deployment fixtures; those are outside this legacy release slice.
- `scripts/build-legacy-windows-first-iteration.sh --require-mac-studio` on Mac-Studio with `SK_LEGACY_GO` set to a Go 1.20 toolchain, or pass `--legacy-go /path/to/go1.20.x`.
- `scripts/build-sk-agent-release.sh` on Mac-Studio with `SK_LEGACY_GO` set to a Go 1.20 toolchain.
- `scripts/legacy-windows-first-iteration-preflight.sh --require-mac-studio` on Mac-Studio `10.0.10.41`; preflight verifies build manifest artifact list shape, entry shape, duplicate paths, Mac-Studio host IP provenance, SHA-256 shape, byte size, that manifest artifact hashes and sizes match the local files, and the full build-wrapper artifact set, including shipped helper scripts and release docs.
- `scripts/legacy-windows-lab-kit.py --output legacy-windows-lab-kit.zip` after the Mac-Studio artifact build passes; the lab kit builder rejects retained build manifests without Mac-Studio host IP provenance and ships helper scripts including the lab-kit builder and verifier for audit/reproduction. Retain `legacy-windows-lab-kit.zip.sha256`, the sibling `legacy-windows-lab-kit-verify.py`, and `legacy-windows-lab-kit-verify.py.sha256` with the ZIP. The sidecars must contain exactly the SHA-256 and artifact filename.
- `python legacy-windows-lab-kit-verify.py --kit legacy-windows-lab-kit.zip --require-verifier-sidecar` after transfer; it must print `legacy Windows lab kit verification passed` and `verifier self-check: passed` before extraction or lab use, and fails if `legacy-windows-lab-kit-verify.py.sha256` is missing beside the verifier, if either sidecar omits, mismatches, or adds extra tokens beyond the artifact filename, if the ZIP contains duplicate archive entries or duplicate manifest artifact roles or archive paths, or if 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 and finds a mismatch.
- Follow `docs/legacy-windows-first-iteration-runbook.md` for the operator sequence and retained evidence.
- `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-folder>` for each Windows 7 SP1 / Windows Server 2008 R2 SP1 lab result. Run the endpoint collector with `-ExercisePeerRecover -ExerciseSelfRescue -ApiKey <test-org-key>`; use `--require-self-rescue` for the signed rescue lab and `--require-win10-status` after running `__WIN10_PROBE__`; the smoke JSON and collector manifest must include string `hostname`, the collector manifest must include string `os_kind`, the collector manifest must include `build_manifest_sha256` matching the retained build manifest, smoke `ok` must be boolean `true`, smoke `checks` entries must be objects with nonblank string names and boolean `ok` values, names must be unique, smoke `failed` must be a string list and must not contain hard failures, the collector manifest must show `collector_exit: 0` and `smoke_exit: 0`, list nonblank string-only unique plain evidence filenames, the collector manifest hostname must match the smoke hostname, the collector manifest os_kind must match the smoke os_kind, and `operator-context.json` `computer_name` must match the collector manifest hostname.
- After the sacrificial Windows 10 bridge, rerun `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-folder> --win10-upgrade-status win10_upgrade.status.json --win10-upgrade-log win10_upgrade.log` to validate retained bridge artifacts, including a retained `Operator evidence notes recorded: customer-scoped enablement` log line. Retain `win10-probe.json` from the candidate probe in the same evidence folder.
- Run `scripts/legacy-windows-lab-intake.py --collect-root <legacy-windows-lab-evidence-folder> --build-manifest bin/legacy-windows-first-iteration-build-manifest.json --output-dir <retained-evidence-dir>` to validate and bundle each lab folder through the standard Mac-Studio intake path; it rejects collector manifest build_manifest_sha256 mismatch before writing a retained ZIP.
- Run `scripts/legacy-windows-first-iteration-finalize.py --win7-collect-root <win7-evidence-folder> --server-2008-r2-collect-root <server-2008-r2-evidence-folder> --build-manifest bin/legacy-windows-first-iteration-build-manifest.json --output-dir <retained-evidence-dir> --require-mac-studio` once both lab folders are copied back; it runs intake for both platforms, rejects 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, runs the readiness gate, and writes `legacy-windows-first-iteration-final-summary.json` plus `legacy-windows-first-iteration-final-summary.json.sha256` with retained bundle SHA-256 hashes, byte sizes, Windows 10 probe verdict and hardware context, and bridge proof. It also writes `legacy-windows-first-iteration-pilot-checklist.json` plus `legacy-windows-first-iteration-pilot-checklist.json.sha256`; the checklist records lab evidence, `final_summary_hash_sidecar` evidence, and `win10_bridge_media_url_redacted` as passed but keeps `customer_pilot_ready` false until customer-scoped enablement, backup or rollback proof, vendor software review, clinical equipment review, and customer approval are recorded for the one selected office endpoint. Always retain both checksum sidecars and verify both hashes before customer pilot approval.
- Run `scripts/legacy-windows-first-iteration-pilot-approval.py --checklist <retained-evidence-dir>/legacy-windows-first-iteration-pilot-checklist.json --output-dir <retained-evidence-dir> --customer <customer> --pilot-hostname <host> --operator <operator> --approval-ticket <ticket> --customer-scoped-enablement <scope-note> --backup-evidence <backup-note> --rollback-plan <rollback-note> --vendor-software-review <vendor-note> --clinical-equipment-review <equipment-note> --customer-approval <approval-note>` only after the one customer pilot machine is selected and approval evidence is recorded. The pilot hostname must be the selected doctor-office endpoint, must be a valid Windows computer name using only ASCII letters, numbers, or hyphens, and must not be one of the retained lab evidence hostnames. It verifies the checklist checksum sidecar SHA-256 and filename, rejects duplicate or unknown pilot checklist items, rejects placeholder pilot hostnames or approval evidence such as TBD, pending, unknown, none, or N/A, verifies that the checklist final summary reference is present, verifies the final summary checksum sidecar SHA-256 and filename, verifies `final_summary_hash_sidecar` evidence points to the final summary checksum sidecar, verifies the recorded final summary SHA-256 shape, 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 final-summary operator context with a case-insensitive Windows hostname match, and requires final summary `win10_bridge.media_url_query_redacted` is true before writing `legacy-windows-first-iteration-pilot-approval.json` plus `legacy-windows-first-iteration-pilot-approval.json.sha256`; retain both before touching the doctor-office endpoint.
- Run `scripts/legacy-windows-first-iteration-pilot-readiness.py --approval <retained-evidence-dir>/legacy-windows-first-iteration-pilot-approval.json` immediately before touching the doctor-office endpoint. It must print `legacy Windows first-iteration pilot readiness passed` after rechecking checksum sidecar SHA-256 values and required filenames, that the source checklist reference is present, that the approval final summary reference is present, recorded source checklist SHA-256 shape, 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, duplicate or unknown checklist or approval items, final-summary retained bundle SHA-256 hashes, byte sizes, final-summary collector build manifest SHA-256 proof, duplicate retained lab hostnames, collector exit proof, required smoke proof, Windows 10 probe/bridge proof including `win10_bridge.media_url_query_redacted` is true, required `final_summary_hash_sidecar` 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, 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; otherwise stop and fix the retained approval/evidence chain.
- Create a retained ZIP with `scripts/legacy-windows-first-iteration-evidence-bundle.py --hostname <host> --output legacy-windows-<host>-evidence.zip --lab-smoke legacy-windows-lab-smoke.json --collect-manifest legacy-windows-lab-collector-manifest.json --collect-root <legacy-windows-lab-evidence-folder> --win10-upgrade-status win10_upgrade.status.json --win10-upgrade-log win10_upgrade.log`.
- The evidence bundle helper requires collector manifest, collect-root, and build manifest provenance; refuses invalid lab smoke, unknown legacy OS identity, collector manifests, smoke-to-collector hostname mismatches, smoke-to-collector os_kind mismatches, collector manifest build_manifest_sha256 mismatches, collect-root smoke hostname or content mismatches, collect-root files, duplicate build manifest artifact paths, and invalid build manifest sk-recover-legacy.exe SHA-256/size metadata; requires build manifest sk-recover-legacy.exe SHA-256/size metadata; requires Windows 7 SP1 bridge/probe evidence with candidate probe verdict, positive RAM, and hardware context, refuses Windows 10 bridge artifacts on Server 2008 R2 SP1, and refuses Windows 10 probe evidence on Server 2008 R2 SP1 before writing the ZIP.
- Run `scripts/legacy-windows-first-iteration-readiness.py <win7-evidence.zip> <server-2008-r2-evidence.zip>` before customer pilot; it refuses to pass until retained bundles cover both Windows 7 SP1 and Windows Server 2008 R2 SP1, manifest `os_kind` is present, manifest `os_kind` agrees with smoke-derived platform identity, duplicate manifest artifact roles or paths are absent, collector manifest `collector_exit` and `smoke_exit` are both zero, collector manifest `build_manifest_sha256` matches the archived build manifest, `operator-context.json` is present, `is_elevated` is true, `computer_name` matches the retained bundle hostname, Windows 10 probe evidence and bridge launch artifacts are present on the Windows 7 bundle only, the Windows Server 2008 R2 SP1 bundle includes no Windows 10 bridge artifacts or Windows 10 probe evidence, final summary `win10_probe.verdict` is `candidate`, final summary `win10_bridge.acknowledgements_recorded` is true, final summary `win10_bridge.evidence_notes_recorded` is true, final summary `win10_bridge.media_url_query_redacted` is true, and positive live legacy agent process, live SK Tray process, watchdog log, signed `peer_recover`, self-rescue, and recovery health smoke checks.
- `go test ./...` from `agent-go/sk-recover-legacy`.
- Focused legacy pytest cluster covering agent lane, command catalog, inventory ingest, runtime scripts, peer recovery, operator UI, Windows 10 bridge, and command timeouts.
- Real lab smoke on Windows 7 SP1 and Windows Server 2008 R2 SP1 before customer rollout.

Pilot scope:

- SiteKings/internal lab first.
- One doctor-office test machine only after lab evidence is captured.
- Customer-scoped enablement only; no broad fleet rollout.
- Windows 10 upgrade bridge remains an exception path for legacy clinical equipment, not a preferred end state.

Runtime validation checklist:

- Install legacy lane and confirm check-in/inventory.
- Confirm `SK Agent`, `SK Watchdog`, and `SK Tray` scheduled tasks or service entries exist as expected, and retain smoke evidence for the live legacy agent process, live SK Tray process, and `watchdog.log`.
- Confirm SK Tray launches for the active user and Chat with IT includes endpoint context.
- Kill the legacy agent and confirm watchdog writes `restart-agent.flag` or restarts the agent.
- Confirm `sk-recover-legacy.exe` responds on port 47778 at `/health`.
- Exercise same-LAN peer healing with signed `/recover` and retain `peer_recover` smoke evidence.
- Exercise signed `/self-rescue` where test credentials are available.
- Queue `__LEGACY_LAB_SMOKE__` from the operator UI and retain `legacy-windows-lab-smoke.json`.
- Queue `__LEGACY_LAB_COLLECT__` from the operator UI or run `legacy-windows-lab-run.ps1` locally from an elevated PowerShell session, then retain the timestamped evidence folder and confirm the legacy panel's Last evidence collect summary has no missing required files. Retain `operator-context.json`; readiness requires it to prove the runner was elevated and that `computer_name` matches the retained bundle hostname.
- Run `legacy-windows-lab-collect.ps1` on each Windows 7 SP1 / Server 2008 R2 SP1 lab endpoint and retain the timestamped evidence folder.
- Validate retained smoke output with `scripts/legacy-windows-lab-evidence-check.py`.
- Queue `__WIN10_PROBE__` and retain readiness output.
- On one sacrificial Windows 7 SP1 machine or VM only, queue `__UPGRADE_WIN10_MEDIA__` with HTTPS media and a verified SHA-256 checksum after checking the required backup, rollback, vendor software, and clinical equipment acknowledgements and recording non-empty evidence notes for customer-scoped enablement, backup, rollback, vendor software, and clinical equipment; retain `win10-probe.json`, `win10_upgrade.status.json`, and `win10_upgrade.log`, and confirm the log contains a redacted media URL, `Operator acknowledgements recorded`, and `Operator evidence notes recorded: customer-scoped enablement`.

Rollback or fix-forward path:

- Disable customer-scoped legacy Windows enablement.
- Stop queueing `__UPGRADE_WIN10_MEDIA__`.
- Remove or replace `bin/sk-recover-legacy.exe` from served artifacts and rerun the release preflight.
- Reinstall the prior agent lane on affected endpoints using the existing installer or force-upgrade path.
- For failed Windows 10 bridge upgrades, use the local Windows setup rollback path or image backup for that pilot machine.

Notes:

- Deployment and live smoke must run on Mac-Studio at `10.0.10.41`.
- Do not start RMM servers, workers, migrations, or production-like listeners from a local workstation for this release.
- Windows 10 is also end-of-life, but it is a safer bridge than Windows 7 for older medical-office equipment that cannot yet move to Windows 11.
