From a6a15a64ea3c2fc04cd0c0be358ea35bad19c9f4 Mon Sep 17 00:00:00 2001
From: "pulse-triage[bot]"
 <249995291+pulse-triage[bot]@users.noreply.github.com>
Date: Sun, 20 Sep 2026 02:57:17 +0100
Subject: [PATCH] docs(installer): record FreeBSD checksum tool contract

FreeBSD base ships sha256(1) but not GNU sha256sum or Perl shasum. Record the fallback contract for the unified and MCP installers and add the MCP installer proof the deployment-installability verification policy requires.

Change-source: pulse-maintainer
---
 .../v6/internal/subsystems/agent-lifecycle.md |  5 +++++
 .../subsystems/deployment-installability.md   |  6 ++++++
 .../installtests/build_release_assets_test.go | 20 +++++++++++++++++++
 3 files changed, 31 insertions(+)

diff --git a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
index f1a834635e..b8ba4adb6e 100644
--- a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
+++ b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
@@ -1163,6 +1163,11 @@ update, profile rollout, command reachability, or fleet-control authority.
     success. `scripts/installtests/install_sh_test.go` owns the static teardown
     contract, and native FreeBSD rehearsal must prove clean install, update,
     reboot persistence, and complete uninstall.
+    The installer's download verification is part of that FreeBSD lifecycle.
+    FreeBSD base provides `sha256(1)` but neither GNU `sha256sum` nor Perl
+    `shasum`, so checksum verification must fall back through the digest tools
+    actually present on the target platform rather than failing a valid agent
+    download when coreutils is absent.
 
 Server update planning is part of the same lifecycle contract. The System
 Updates plan must surface a structured upgrade-readiness verdict before an
diff --git a/docs/release-control/v6/internal/subsystems/deployment-installability.md b/docs/release-control/v6/internal/subsystems/deployment-installability.md
index 0066c6ccb6..8d2d72b974 100644
--- a/docs/release-control/v6/internal/subsystems/deployment-installability.md
+++ b/docs/release-control/v6/internal/subsystems/deployment-installability.md
@@ -1069,6 +1069,12 @@ artifact-selection behaviour.
    report success. A checksum-verified native rehearsal must cover install,
    update, reboot persistence, and clean uninstall rather than treating a
    cross-build as complete lifecycle proof.
+   Download verification must use a SHA-256 tool that exists on the target
+   platform. FreeBSD base ships `sha256(1)` and neither GNU `sha256sum` nor
+   Perl `shasum`, so the unified installer and the MCP installer must fall back
+   through the available digest tool instead of refusing an otherwise correct
+   download. The shared installer helper owns that fallback so every download
+   (agent, typed helper, action runner) is verified consistently.
    The shell installer must disclose `--enable-commands` as Pulse command
    execution, disabled by default, and must name both Patrol actions and
    Proxmox LXC Docker inventory as the operator-visible reasons to enable it.
diff --git a/scripts/installtests/build_release_assets_test.go b/scripts/installtests/build_release_assets_test.go
index b749f9cf0b..467324fcc8 100644
--- a/scripts/installtests/build_release_assets_test.go
+++ b/scripts/installtests/build_release_assets_test.go
@@ -4412,3 +4412,23 @@ func TestReleaseNodeSetupKeepsExplicitCacheIsolation(t *testing.T) {
 		})
 	}
 }
+
+func TestInstallMCPFreeBSDSHA256Fallback(t *testing.T) {
+	content, err := os.ReadFile(repoFile("scripts", "install-mcp.sh"))
+	if err != nil {
+		t.Fatalf("read install-mcp.sh: %v", err)
+	}
+	script := string(content)
+	// FreeBSD base provides sha256(1) but neither GNU sha256sum nor Perl's
+	// shasum, so the MCP installer must select the available digest tool.
+	for _, want := range []string{
+		"command -v sha256sum",
+		"command -v sha256 >/dev/null 2>&1",
+		`sha_cmd="sha256 -q"`,
+		"command -v shasum",
+	} {
+		if !strings.Contains(script, want) {
+			t.Fatalf("install-mcp.sh lost FreeBSD sha256 fallback %q", want)
+		}
+	}
+}