gitcommit90 · gitcommit90 · Aug 4, 2026 · Aug 4, 2026 · coderabbitai · Aug 4, 2026
@@ -67,6 +67,12 @@ previous candidate, and rollback result/time. Historical attempts are retained
 root-only beside it; detailed install logs are root-only under
 `/var/log/1helm-candidate`.
 
+Phase 4 retains this private status as the Linux dress-rehearsal proof and also
+runs an ephemeral hosted Linux acceptance lane for clean install, distinct
+prior Stable to candidate update, state identity, systemd health, and a forced
+failure rollback. The Phase 3 bundle requires both records. Phase 4 does not
+change or repurpose this guest or its unique runner.
+
 Integrate this read-only evidence with Phase 0 without tracking private
 coordinates:
 

@@ -0,0 +1,138 @@
+# Phase 4 cross-platform candidate acceptance
+
+1. Build the ready-to-run Linux TGZ on the hosted builder and retain its
+   GitHub-hosted provenance attestation.
+2. Build the Apple Silicon DMG and updater ZIP on the dedicated Mac runner;
+   Developer ID-sign, notarize, staple, and Gatekeeper-check both exact
+   payloads. Missing Apple credentials or runner capacity blocks the matrix.
+3. Run Linux, macOS, and Windows 11 acceptance concurrently after their exact
+   bytes exist. Each job rechecks repository, workflow, push event, main ref,
+   candidate SHA, CI run, and candidate run before repository code executes.
+4. Retain normalized JSON with exact artifact SHA-256 and byte counts, candidate
+   and CI run identities, machine/runner identity, check timestamps, state
+   digests, and rollback or scoped-uninstall outcome. Windows binds behavior to
+   the Linux TGZ and publishes no artifact or signing claim.
+5. Assemble Phase 3's promotion bundle only after all builds, the private Linux
+   dress rehearsal, and all three acceptance records pass. The assembler copies
+   retained bytes and cannot build. Missing, failed, skipped, or unavailable
+   lanes remain blockers in the retained candidate matrix status.
+
+## One-time dedicated runners
+
+Register repository-scoped runners with `--no-default-labels` and exactly one
+label: `1helm-macos-phase4` or `1helm-windows-phase4`. Do not put Proxmox,
+Stable, website, production, or broad repository-write credentials on either
+machine. The runner account is a dedicated ordinary user with no production
+data, no broad `sudo`/administrator membership, and no other workloads.
+
+Install the root-owned `ops/platform-acceptance/runner-job-started.sh` on macOS
+or the administrator-owned native PowerShell
+`ops/platform-acceptance/runner-job-started.ps1` on Windows as
+`ACTIONS_RUNNER_HOOK_JOB_STARTED`. The hook accepts only `gitcommit90/1Helm`, the Candidate dress
+rehearsal workflow, its allowlisted job, a successful CI `push` to trusted
+`main`, and the exact SHA. Do not set the enabling variables until the label,
+hook, account isolation, and prerequisites below have been inspected:
+
+- repository variable `HELM_PHASE4_MACOS_ENABLED=1` enables the Mac build and
+  acceptance jobs;
+- repository variable `HELM_PHASE4_WINDOWS_ENABLED=1` enables Windows
+  acceptance.
+
+Leaving either variable absent is the safe default: the lane is skipped by
+GitHub but recorded as **blocked**, and no complete promotion artifact exists.
+Registration tokens are one-use and transient; never save one in an image,
+shell profile, workflow, or repository file.
+
+### macOS runner and credentials
+
+Use an Apple Silicon Mac retained solely for release acceptance. Install the
+repository runner, Node 22, Xcode command-line tools, and the pinned npm
+dependencies. In the dedicated account's login keychain install:
+
+- one Developer ID Application certificate/private key;
+- `APPLE_TEAM_ID` and optionally `APPLE_SIGN_IDENTITY` as runner service
+  environment values;
+- an `APPLE_NOTARY_PROFILE` created with `xcrun notarytool store-credentials`.
+
+The workflow intentionally does not use GitHub repository secrets for signing:
+the secure credential and private key remain on the retained Mac. Configure the
+runner service to unlock only that dedicated user's keychain before a job and
+lock it in a job-completed hook; do not store the keychain password in the
+repository, runner labels, workflow environment, or shell history. The account's
+`~/Library/Application Support/1Helm-OCI-v1` must be absent before every job;
+residue is a hard failure. The job validates signature, notarization ticket,
+staple, Gatekeeper, exact versions/digests, clean launch/loopback health, updater
+ZIP replacement from the latest digest-qualified prior Stable DMG, and
+Application Support identity. Signing requirements are never downgraded to
+ad-hoc signing.
+
+### Windows 11 runner and reboot resume
+
+Use a dedicated Windows 11 x64 VM/account with no production data. The runner
+is non-elevated. The one-time operator proof starts from both WSL optional
+features disabled, invokes the tracked installer from an ordinary PowerShell
+window, records the single UAC approval, expected restart, and same-user resume,
+then stores an administrator-owned, user-readable
+`C:\ProgramData\1Helm-Phase4\provisioning-evidence.json`:
+
+```json
+{
+  "schema": 1,
+  "kind": "1helm-windows-runner-provisioning",
+  "features_initially_disabled": true,
+  "single_uac": true,
+  "restart_required": true,
+  "same_user_resume": true,
+  "keepalive_after_sign_in": true,
+  "service_active": true,
+  "localhost_health": true,
+  "snapshot_baseline": true,
+  "dedicated": true,
+  "production_data": false
+}
+```
+
+After that real provisioning exercise, use the scoped uninstaller, confirm the
+named product distribution and install root are absent, and capture the clean,
+WSL-enabled dedicated-VM snapshot used before every acceptance job. The runner
+registration, hook, pinned rootfs, and the administrator-owned provisioning
+record remain; 1Helm product state does not.
+
+Also stage the pinned Ubuntu rootfs at
+`C:\ProgramData\1Helm-Phase4\ubuntu-noble-wsl-amd64.rootfs.tar.gz`.
+
+The workflow does not claim an in-job Windows reboot: a self-hosted job cannot
+honestly survive one. Instead, it records the allowed snapshot-assisted
+equivalent. The provisioner restores the accepted clean snapshot before the
+job routes; the exact candidate job then stops the same-user limited logon
+keepalive, cold-stops only its named WSL distribution, restarts that keepalive,
+and requires systemd, localhost health, and retained state to recover. The JSON
+record names this mode `snapshot-assisted-equivalent`; it never labels the
+exercise as a real reboot. The administrator-owned record separately preserves
+the one-time real disabled-features/UAC/restart/same-user-resume proof.
+
+Windows uses the repository's tracked `install.ps1`, `install.sh`, keepalive,
+and `uninstall.ps1` with documented local candidate inputs, so it is a private
+site-equivalent path without touching the public website. It creates an
+unrelated WSL control distribution and proves uninstall retains it. It never
+claims Windows artifact creation or signing.
+
+## Recovery and teardown
+
+First disable the applicable repository variable so new jobs cannot route.
+Wait for any active job to finish, archive only the retained JSON and exact
+candidate artifacts needed by the owner, then remove the repo runner
+registration and stop its service. Remove only the dedicated account/VM after
+confirming its identity; never use a wildcard or a shared host.
+
+Mac cleanup quits the test app and removes transient app copies and Application
+Support after success; the dedicated Application Support directory is retained
+on failure for diagnosis and must be removed before re-enabling the runner. Windows cleanup
+uses the scoped product uninstaller for the exact `1helm-phase4` distribution
+and separately unregisters only its named unrelated test control. If teardown
+is interrupted, leave the runner disabled and inspect both exact names before
+retrying. Linux hosted runners are ephemeral; the Phase 2 private runner and
+its retained evidence are not teardown targets for Phase 4.
+
+No Phase 4 automation publishes Stable, creates a tag/Release, deploys the
+website, or changes production data/services.
@@ -156,8 +156,14 @@ current `main`; successful
 CI and candidate workflow identities; Linux attestation, archive digest, and
 embedded commit; private dress-rehearsal health for that digest; all three
 retained artifact records; and retained macOS, Linux, and Windows acceptance.
-Phase 3 does not manufacture platform records: until Phase 4 supplies them, the
-dry run reports them as blockers and publication remains paused.
+The trusted-main candidate workflow now retains the complete Phase 4 matrix:
+hosted Linux candidate and acceptance, signed/notarized Mac bytes and Apple
+Silicon acceptance, and Windows 11 behavior acceptance bound to the Linux TGZ.
+It assembles the Phase 3 promotion bundle only when every exact byte and record
+passes. Missing credentials, disabled/offline runners, failed checks, or absent
+evidence appear in the retained per-platform status as blockers; they never
+become skipped success. Provisioning and recovery are documented in
+[phase4-platform-acceptance.md](./phase4-platform-acceptance.md).
 
 Publication additionally requires `mode=publish`, the exact identity-bound
 confirmation printed by the dry run, and owner approval in the protected

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+ARCHIVE="${HELM_CANDIDATE_ARCHIVE:?exact Linux candidate archive is required}"
+MANIFEST="${HELM_CANDIDATE_MANIFEST:?exact candidate manifest is required}"
+PROVENANCE="${HELM_CANDIDATE_PROVENANCE:?exact hosted provenance bundle is required}"
+OUTPUT="${HELM_ACCEPTANCE_OUTPUT:?acceptance output is required}"
+STARTED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+VERSION="$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1])).version' "$MANIFEST")"
+DIGEST="$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1])).artifact.sha256' "$MANIFEST")"
+COMMIT="$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1])).source.commit' "$MANIFEST")"
+CI_RUN="$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1])).ci.run_id' "$MANIFEST")"
+
+[[ "$GITHUB_REPOSITORY" == "gitcommit90/1Helm" && "$GITHUB_EVENT_NAME" == "workflow_run" \
+   && "$GITHUB_REF" == "refs/heads/main" && "$GITHUB_SHA" == "$COMMIT" \
+   && "${HELM_EXPECTED_COMMIT:?}" == "$COMMIT" && "${HELM_EXPECTED_CI_RUN_ID:?}" == "$CI_RUN" ]] \
+  || { echo "Linux acceptance refused an untrusted candidate identity." >&2; exit 1; }
+export HELM_ACCEPTANCE_PLATFORM=linux
+export HELM_ACCEPTANCE_STARTED_AT="$STARTED_AT"
+export HELM_PHASE4_RUNNER_LABEL=ubuntu-latest
+node "$ROOT/scripts/pending-acceptance-evidence.mjs"
+[[ "$(id -u)" -ne 0 ]] || { echo "Linux acceptance must begin as the hosted ordinary runner user." >&2; exit 1; }
+[[ "$(sha256sum "$ARCHIVE" | awk '{print $1}')" == "$DIGEST" ]] \
+  || { echo "Linux candidate digest mismatch." >&2; exit 1; }
+node -e 'import("./scripts/candidate-manifest.mjs").then(({candidateIdentityFromArchive})=>{const x=candidateIdentityFromArchive(process.argv[1]); if(x.commit!==process.argv[2]) process.exit(2)})' "$ARCHIVE" "$COMMIT"
+gh attestation verify "$ARCHIVE" --bundle "$PROVENANCE" \
+  --repo gitcommit90/1Helm --signer-workflow gitcommit90/1Helm/.github/workflows/candidate.yml \
+  --source-ref refs/heads/main --source-digest "$COMMIT" --deny-self-hosted-runners
+
+work="$(mktemp -d)"
+trap 'rm -rf -- "$work"' EXIT
+prefix="$(tar -tzf "$ARCHIVE" | awk -F/ '/^[^/]+\/site\/public\/install\.sh$/ && !found { print $1; found=1 }')"
+[[ -n "$prefix" ]] || { echo "Candidate installer is missing." >&2; exit 1; }
+tar -xzf "$ARCHIVE" -C "$work" "$prefix/site/public/install.sh"
+
+# The hosted VM is disposable and contains no user or production data. Its
+# first installation is therefore an actual clean systemd installation.
+sudo env HELM_RELEASE_SHA256="$DIGEST" bash "$work/$prefix/site/public/install.sh" "$ARCHIVE"
+sudo systemctl is-active --quiet 1helm.service
+curl -fsS http://127.0.0.1:8123/api/setup/status >"$work/clean-health.json"
+[[ "$(readlink -f /opt/1helm/current)" == "/opt/1helm/releases/$VERSION-$DIGEST" ]]
+
+# Resolve the newest immutable public Stable release distinct from this
+# candidate version. Candidate versions normally remain unchanged during
+# preview phases, so `releases/latest` can legitimately be the same version.
+gh api "repos/$GITHUB_REPOSITORY/releases?per_page=20" >"$work/releases.json"
+node - "$work/releases.json" "$VERSION" >"$work/previous-release.json" <<'NODE'
+const fs = require("fs");
+const releases = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const current = process.argv[3];
+const release = releases.find((item) => !item.draft && !item.prerelease
+  && /^v\d+\.\d+\.\d+$/.test(String(item.tag_name || ""))
+  && String(item.tag_name).slice(1) !== current);
+if (!release) process.exit(2);
+process.stdout.write(JSON.stringify(release));
+NODE
+PREVIOUS_VERSION="$(node -p 'String(JSON.parse(require("fs").readFileSync(process.argv[1])).tag_name||"").replace(/^v/,"")' "$work/previous-release.json")"
+[[ "$PREVIOUS_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ && "$PREVIOUS_VERSION" != "$VERSION" ]] \
+  || { echo "A distinct previous Stable version is required for Linux updater acceptance." >&2; exit 1; }
+PREVIOUS_NAME="1Helm-$PREVIOUS_VERSION-linux-node.tgz"
+readarray -t previous_asset < <(node - "$work/previous-release.json" "$PREVIOUS_NAME" <<'NODE'
+const fs = require("fs");
+const release = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const asset = (release.assets || []).find((item) => item.name === process.argv[3]);
+if (!asset || !/^sha256:[a-f0-9]{64}$/.test(String(asset.digest || ""))) process.exit(2);
+console.log(asset.browser_download_url);
+console.log(asset.digest.slice(7));
+NODE
+)
+[[ "${#previous_asset[@]}" -eq 2 ]] || { echo "Prior Stable Linux asset lacks digest-qualified metadata." >&2; exit 1; }
+PREVIOUS_URL="${previous_asset[0]}"
+curl -fsSL --proto '=https' --tlsv1.2 --retry 3 -o "$work/$PREVIOUS_NAME" "$PREVIOUS_URL"
+PREVIOUS_DIGEST="$(sha256sum "$work/$PREVIOUS_NAME" | awk '{print $1}')"
+[[ "$PREVIOUS_DIGEST" == "${previous_asset[1]}" ]] || { echo "Prior Stable Linux digest mismatch." >&2; exit 1; }
+previous_prefix="$(tar -tzf "$work/$PREVIOUS_NAME" | awk -F/ '/^[^/]+\/site\/public\/install\.sh$/ && !found { print $1; found=1 }')"
+tar -xzf "$work/$PREVIOUS_NAME" -C "$work" "$previous_prefix/site/public/install.sh"
+sudo env HELM_RELEASE_SHA256="$PREVIOUS_DIGEST" bash "$work/$previous_prefix/site/public/install.sh" "$work/$PREVIOUS_NAME"
+[[ "$(node -p 'require("/opt/1helm/current/package.json").version')" == "$PREVIOUS_VERSION" ]]
+
+MARKER=/var/lib/1helm-oci-v1/phase4-acceptance-state
+openssl rand -hex 32 | sudo tee "$MARKER" >/dev/null
+sudo chown 1helm:1helm "$MARKER"
+STATE_BEFORE="$(sudo sha256sum "$MARKER" | awk '{print $1}')"
+CANDIDATE_RELEASE="/opt/1helm/releases/$VERSION-$DIGEST"
+[[ -d "$CANDIDATE_RELEASE" ]] || { echo "Clean candidate release was not retained for updater acceptance." >&2; exit 1; }
+sudo "$CANDIDATE_RELEASE/site/public/apply-linux-release.sh" "$CANDIDATE_RELEASE" "$VERSION"
+[[ "$(node -p 'require("/opt/1helm/current/package.json").version')" == "$VERSION" ]]
+sudo systemctl is-active --quiet 1helm.service
+curl -fsS http://127.0.0.1:8123/api/setup/status >"$work/update-health.json"
+
+# Exercise the candidate's real atomic host transaction with a derived local
+# startup-failure fixture. The fixture is never uploaded as candidate bytes.
+[[ "$(readlink -f /opt/1helm/current)" == "$CANDIDATE_RELEASE" ]]
+FAILURE_RELEASE="/opt/1helm/releases/$VERSION-$DIGEST-phase4-failure"
+sudo cp -a "$CANDIDATE_RELEASE" "$FAILURE_RELEASE"
+printf '%s\n' 'throw new Error("Phase 4 controlled startup failure");' | sudo tee "$FAILURE_RELEASE/src/server/index.ts" >/dev/null
+if sudo "$CANDIDATE_RELEASE/site/public/apply-linux-release.sh" "$FAILURE_RELEASE" "$VERSION"; then
+  echo "Controlled failure unexpectedly passed." >&2
+  exit 1
+fi
+[[ "$(readlink -f /opt/1helm/current)" == "$CANDIDATE_RELEASE" ]]
+sudo systemctl is-active --quiet 1helm.service
+curl -fsS http://127.0.0.1:8123/api/setup/status >"$work/rollback-health.json"
+STATE_AFTER="$(sudo sha256sum "$MARKER" | awk '{print $1}')"
+[[ "$STATE_BEFORE" == "$STATE_AFTER" ]]
+sudo rm -rf -- "$FAILURE_RELEASE"
+
+export HELM_PREVIOUS_VERSION="$PREVIOUS_VERSION"
+export HELM_STATE_BEFORE_SHA256="$STATE_BEFORE"
+export HELM_STATE_AFTER_SHA256="$STATE_AFTER"
+export HELM_MACHINE_OS_VERSION="$(. /etc/os-release; printf '%s' "$PRETTY_NAME")"
+node "$ROOT/scripts/linux-acceptance-evidence.mjs"