PS5 Payload SDK v0.44, and scripts/update-ps5-sdk.sh to bump it

Pin v0.44 (sha256 4d06eab7...). Its crt/ and prospero-nid are identical to v0.43, so the vendored sdk-crt (+ ps5upload.patch) and the portable prospero-nid stay as they are; the helper, installer and elfldr build to the same code (only the build-id differs). v0.44 adds LLVM 23 to the candidate list, so the Makefile comment and Homebrew fallbacks move too. scripts/update-ps5-sdk.sh (make update-sdk): finds the latest release (or --tag), checks the zip, rewrites the pin, re-vendors prospero-nid and crt only when upstream changed them (stops if our crt patch no longer applies), moves the "SDK vX.Y" doc mentions and installs with install-ps5-sdk.sh, keeping the old SDK as a backup. --check only reports. The installer names its backups after the release they hold. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ub1mez9eaVtTF8pMEFXvA9
2026-10-18 18:10:05 -05:00 · 2026-10-10 11:14:44 -07:00
1 parent 154b195c5c
commit 8d05f60a7e
@@ -29,6 +29,10 @@ make run-client  # launch the Tauri dev app
 See the [README](README.md) and [TESTING.md](TESTING.md) for the full
 toolchain (PS5 Payload SDK, Rust, Node 22, Tauri prerequisites).

+The PS5 Payload SDK release is pinned in `scripts/ps5-sdk.env`. `make update-sdk`
+moves the pin to the latest upstream release and installs it (`SDK_TAG=vX.Y` for a
+specific one, `SDK_CHECK=1` to only check); see TESTING.md, Layer 2.
+
 ## Quality gate: run before opening a PR

 CI runs the same checks; running them locally first saves a round-trip.
@@ -245,7 +245,7 @@ so overlapping work (a temperature read during an install) cannot crash the help
 There is no 32-bit x86 (i386 / i686) build for any desktop OS.

 **Q: Which PS5 firmware works?**
-The helper is built against PS5 Payload SDK v0.43 and the same binary runs on **1.00 to 13.60**.
+The helper is built against PS5 Payload SDK v0.44 and the same binary runs on **1.00 to 13.60**.
 Tested on 5.10, 9.60 and 13.60 (and confirmed by users on 12.20). In practice the limit is the
 **ELF loader** on port 9021, a third-party component; loader coverage is roughly 4.x to 12.x.

@@ -30,14 +30,14 @@ export PS5_PAYLOAD_SDK
 PS5_SDK_TAG := $(shell sed -n 's/^PS5_SDK_TAG=//p' scripts/ps5-sdk.env 2>/dev/null)

 # On macOS the payload SDK's `prospero-clang` wrapper resolves `ld.lld`
-# and `clang` through `prospero-llvm-config`. SDK v0.43 supports LLVM 16–22.
-# Homebrew exposes the current major as `llvm` (not `llvm@22`), so discover
+# and `clang` through `prospero-llvm-config`. SDK v0.44 supports LLVM 16–23.
+# Homebrew exposes the current major as `llvm` (not `llvm@23`), so discover
 # its real prefix and retain versioned fallbacks for older installations.
 # Linux/WSL picks up `llvm-config-<N>` from apt naturally.
 ifeq ($(shell uname -s),Darwin)
  MACOS_LLVM_CONFIG := $(shell \
    if command -v brew >/dev/null 2>&1; then \
-      for formula in llvm llvm@22 llvm@18; do \
+      for formula in llvm llvm@23 llvm@22 llvm@18; do \
        prefix="$$(brew --prefix "$$formula" 2>/dev/null || true)"; \
        if [ -n "$$prefix" ] && [ -x "$$prefix/bin/llvm-config" ]; then \
          printf '%s\n' "$$prefix/bin/llvm-config"; \
@@ -96,7 +96,7 @@ ANDROID_ENV = JAVA_HOME="$(ANDROID_JAVA_HOME)" ANDROID_HOME="$(ANDROID_HOME)" ND
 ADB ?= $(ANDROID_HOME)/platform-tools/adb

 .PHONY: all help
-.PHONY: install install-ubuntu install-macos install-windows
+.PHONY: install install-ubuntu install-macos install-windows update-sdk
 .PHONY: setup setup-engine setup-payload setup-client
 .PHONY: build payload installer engine client _engine-release _payload-if-ready _android-build-if-ready
 .PHONY: test test-root test-engine test-engine-coverage test-desktop test-payload test-client test-client-coverage
@@ -129,6 +129,8 @@ help:
 	@echo "  make install-ubuntu   - Ubuntu/Debian/WSL2: apt + rustup + node + PS5 SDK $(PS5_SDK_TAG)"
 	@echo "  make install-macos    - macOS: brew + rustup + LLVM + PS5 SDK $(PS5_SDK_TAG)"
 	@echo "  make install-windows  - Windows 11: winget + rustup + VS Build Tools + PS5 SDK $(PS5_SDK_TAG)"
+	@echo "  make update-sdk       - Move the PS5 SDK pin to the latest release and install it"
+	@echo "                          (SDK_TAG=vX.Y for a specific one; SDK_CHECK=1 to only check)"
 	@echo ""
 	@echo "Quick start (after install):"
 	@echo "  1. make setup         - Check toolchains, install client deps"
@@ -243,6 +245,13 @@ install-windows:
 	  exit 1; \
 	fi

+# Bump the PS5 Payload SDK pin (scripts/ps5-sdk.env) to the latest upstream
+# release, or SDK_TAG, and install it into $(PS5_PAYLOAD_SDK); the old SDK is
+# kept as a backup. SDK_CHECK=1 only reports whether a newer release exists.
+update-sdk:
+	@PS5_SDK_INSTALL_DIR="$(PS5_PAYLOAD_SDK)" bash scripts/update-ps5-sdk.sh \
+	  $(if $(SDK_TAG),--tag $(SDK_TAG)) $(if $(SDK_CHECK),--check)
+
 #──────────────────────────────────────────────────────────────────────────────
 # Setup
 #──────────────────────────────────────────────────────────────────────────────
@@ -201,11 +201,11 @@ make run-client    # launch the Tauri dev app
  (`libwebkit2gtk-4.1-dev`, `libgtk-3-dev`, `librsvg2-dev`,
  `libayatana-appindicator3-dev`, `libxdo-dev`, `libssl-dev`,
  `build-essential`), Node.js 22 LTS via NodeSource (only if missing),
-  Rust via rustup, and checksum-verified PS5 Payload SDK v0.43 →
+  Rust via rustup, and checksum-verified PS5 Payload SDK v0.44 →
  `~/ps5-payload-sdk`.
 - **`make install-macos`** — macOS: Xcode CLT, Homebrew, `node`, current
-  `llvm` (LLVM 22 at this release), Rust via rustup, and checksum-verified
-  PS5 Payload SDK v0.43.
+  `llvm` (LLVM 23 at this release), Rust via rustup, and checksum-verified
+  PS5 Payload SDK v0.44.
 - **`make install-windows`** — Windows 11: Node.js LTS, Rust, VS 2022 Build
  Tools (C++ workload), WebView2 Runtime, 7-Zip, and PS5 Payload SDK
  via `winget`. Run from an elevated PowerShell (or any shell with
@@ -268,7 +268,7 @@ See [`TESTING.md`](TESTING.md) for the full workflow, and [`CONTRIBUTING.md`](CO

 ## Tech stack

- **Payload**: C (FreeBSD 11), prospero-clang, PS5 Payload SDK v0.43
+- **Payload**: C (FreeBSD 11), prospero-clang, PS5 Payload SDK v0.44
 - **Engine**: Rust, tokio + axum
 - **Client**: Tauri 2, React, TypeScript, Zustand, Tailwind CSS v4, Vite
 - **Protocol**: AVA1 (Noise XX handshake, ChaCha20-Poly1305, BLAKE3 verification)
@@ -62,9 +62,19 @@ Each self-test lives in `payload/tests/*_selftest.c` (hardware guards, ptrace re
 AVA1 C itself is tested by `ava1-ctest`, which compiles it on the host and checks it against the
 Rust side (see the full gate below).

-The SDK version is pinned in `scripts/ps5-sdk.env` (currently **v0.43**)
+The SDK version is pinned in `scripts/ps5-sdk.env` (currently **v0.44**)
 and verified by checksum. Local installers and CI read the same file.

+To move to a newer SDK release, run `make update-sdk` (or
+`scripts/update-ps5-sdk.sh [--tag vX.Y] [--check]`). It downloads the release,
+rewrites the pin and its checksum, refreshes the vendored `prospero-nid` and
+`payload/third_party/sdk-crt` if upstream changed them at that tag, and installs
+the SDK into `$PS5_PAYLOAD_SDK` (default `/opt/ps5-payload-sdk`), keeping the old
+one as a `.backup-<old tag>-<time>` directory. If `/opt` needs root it uses
+`sudo` from a terminal; without it, the backup goes to your home directory.
+Then `rm -rf payload/build payload/installer/build payload/third_party/sdk-crt/build`,
+run `make test-payload`, and commit the changed pin.
+
 **Adding payload logic?** If it can be separated from the console, put it
 header-only in `payload/include/` and give it a self-test here. That is
 the established convention and the reason the list above exists.
@@ -1,6 +1,6 @@
 # ps5upload's build of the PS5 Payload SDK's startup code (crt1.o).
 #
-# The SDK's own crt1.o (v0.43) stops every payload before main() when either of
+# The SDK's own crt1.o (v0.43; crt/ is unchanged in v0.44) stops every payload before main() when either of
 # two kernel searches it added comes up empty (see third_party/sdk-crt/
 # ps5upload.patch): reported on FW 5.50, where 6.x helpers never started while
 # 5.x (built on v0.42) did. The same sources, with those searches made
@@ -1,6 +1,7 @@
 # sdk-crt

-The startup code (`crt/`) of [ps5-payload-sdk](https://github.com/ps5-payload-dev/sdk) v0.43,
+The startup code (`crt/`) of [ps5-payload-sdk](https://github.com/ps5-payload-dev/sdk) v0.43
+(identical in v0.44),
 GPLv3 (see `LICENSE`), built by `payload/sdk-crt.mk` and linked into the helper, the installer
 daemon and the patched elfldr in place of the SDK's own `crt1.o`.

@@ -11,5 +12,7 @@ Only two fallbacks use those values, and both refuse without them: the IOMMU wri
 (which check for a missing softc themselves) and the physical-address path of
 `kernel_proc_copyin`/`kernel_proc_copyout` (a guard added in `kernel_procio.c`).

-To update: copy the new release's `crt/*.{c,h,S}` here, re-apply `ps5upload.patch`, and check
+`scripts/update-ps5-sdk.sh` does this check on every SDK bump: it re-vendors `crt/` and
+re-applies the patch when upstream changed it, and stops if the patch no longer applies.
+By hand: copy the new release's `crt/*.{c,h,S}` here, re-apply `ps5upload.patch`, and check
 that the exported symbols still match the SDK's `target/lib/crt1.o` (`llvm-nm`).
@@ -9,7 +9,7 @@
 #     (the Makefile discovers Homebrew's current LLVM prefix automatically)
 #   - Rust toolchain (rustup, stable, default profile)
 #   - Repository-pinned PS5 Payload SDK → $PS5_PAYLOAD_SDK
-#     (currently v0.43; default $HOME/ps5-payload-sdk)
+#     (currently v0.44; default $HOME/ps5-payload-sdk)
 #
 # After it finishes the script prints the env exports you need to add to ~/.zshrc
 # (or ~/.bash_profile) so `make build` and `make run-client` work in any new shell.
@@ -192,7 +192,10 @@ printf '%s\n' "$PS5_SDK_TAG" > "$STAGED_SDK/$VERSION_MARKER"
 mkdir -p "$(dirname "$SDK_DIR")"
 BACKUP_DIR=""
 if [ -e "$SDK_DIR" ]; then
-  BACKUP_DIR="${SDK_DIR}.backup-$(date +%Y%m%d-%H%M%S)-$$"
+  # Name the backup after the release it holds when it says (backup-v0.43-...).
+  OLD_TAG="$(tr -d '[:space:]' < "$SDK_DIR/$VERSION_MARKER" 2>/dev/null || true)"
+  case "$OLD_TAG" in v[0-9]*) OLD_TAG="$OLD_TAG-" ;; *) OLD_TAG="" ;; esac
+  BACKUP_DIR="${SDK_DIR}.backup-${OLD_TAG}$(date +%Y%m%d-%H%M%S)-$$"
  mv "$SDK_DIR" "$BACKUP_DIR"
  ok "Moved the previous SDK to $BACKUP_DIR"
 fi
@@ -8,7 +8,7 @@
 #     libxdo, libssl, build-essential, file, curl, wget, unzip, pkg-config, python3)
 #   - Rust toolchain (rustup, stable, default profile)
 #   - Node.js 22 LTS via NodeSource (only if `node` is missing — keeps existing installs)
-#   - Repository-pinned PS5 Payload SDK (currently v0.43) → $PS5_PAYLOAD_SDK
+#   - Repository-pinned PS5 Payload SDK (currently v0.44) → $PS5_PAYLOAD_SDK
 #     (default $HOME/ps5-payload-sdk)
 #
 # After it finishes, the script prints the env exports you need to add to ~/.bashrc
@@ -43,8 +43,8 @@ APT_DEPS=(
  python3
  # LLVM 22 toolchain — required by the PS5 SDK's `prospero-clang` wrapper,
  # which dispatches into `${llvm-bindir}/clang` + `${llvm-bindir}/ld.lld`.
-  # SDK v0.42 supports llvm 16–22; we pin to 22 to match macOS's
-  # macOS `LLVM_CONFIG` so both platforms use the same major. Ubuntu 24.04
+  # SDK v0.44 supports llvm 16–23; we pin to 22, the major CI builds
+  # releases with. Ubuntu 24.04
  # doesn't ship llvm-22 in its own repos, so we add apt.llvm.org below
  # before installing these.
  clang-22
@@ -8,7 +8,7 @@
 #   - Visual Studio 2022 Build Tools w/ C++ workload (MSVC + Windows SDK)
 #   - 7zip (used to extract the PS5 SDK zip in CI-clean way)
 #   - Microsoft Edge WebView2 Runtime (preinstalled on Win11; verified)
-#   - Repository-pinned PS5 Payload SDK (currently v0.43)
+#   - Repository-pinned PS5 Payload SDK (currently v0.44)
 #     → $env:USERPROFILE\ps5-payload-sdk
 #
 # Run from an elevated PowerShell:
@@ -1,6 +1,6 @@
 # Canonical PS5 Payload SDK release used by local installers and CI.
-PS5_SDK_TAG=v0.43
-PS5_SDK_SHA256=a9cc9929f21b2b2c5d5b309f3bab4997067c45281c0622cf4838b1aecba66fcb
+PS5_SDK_TAG=v0.44
+PS5_SDK_SHA256=4d06eab777bb135705b5a6816688c9132efb246093fe606ac488ab6cf65ca5b0
 PS5_SDK_NID_SHA256=2f9f9b7bb1d26b30b7e13f16f6a97b67c657f39f3d6d282475df2c3f0a90958a

 # SQLite amalgamation vendored into the payload (payload/third_party/sqlite3).
@@ -0,0 +1,302 @@
+#!/usr/bin/env bash
+# Move ps5upload to a newer PS5 Payload SDK release and install it.
+#
+#   scripts/update-ps5-sdk.sh               latest release
+#   scripts/update-ps5-sdk.sh --tag v0.44   a specific release
+#   scripts/update-ps5-sdk.sh --check       only report whether an update exists
+#                                           (exit 0: up to date, 3: update available)
+#   scripts/update-ps5-sdk.sh --no-install  update the pin, skip the local install
+#
+# Steps: resolve the tag, download the release zip and check it unpacks to an
+# SDK, rewrite PS5_SDK_TAG/PS5_SDK_SHA256 in scripts/ps5-sdk.env, refresh the
+# vendored prospero-nid and the vendored crt (payload/third_party/sdk-crt) when
+# upstream changed them at that tag, move the "SDK vX.Y" mentions in the docs,
+# then install with scripts/install-ps5-sdk.sh into
+# PS5_SDK_INSTALL_DIR (default /opt/ps5-payload-sdk). The previous SDK is kept
+# as a backup, never deleted. Re-running at the pinned tag changes nothing.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+SDK_METADATA="$SCRIPT_DIR/ps5-sdk.env"
+PORTABLE_NID="$SCRIPT_DIR/ps5-sdk/prospero-nid"
+CRT_DIR="$REPO_ROOT/payload/third_party/sdk-crt"
+REPO="ps5-payload-dev/sdk"
+INSTALL_DIR="${PS5_SDK_INSTALL_DIR:-/opt/ps5-payload-sdk}"
+VERSION_MARKER=".ps5upload-sdk-version"
+
+# Files that name the pinned release in prose ("SDK v0.43", "currently v0.43").
+DOC_FILES=(
+  README.md
+  FAQ.md
+  TESTING.md
+  scripts/install-macos.sh
+  scripts/install-ubuntu.sh
+  scripts/install-windows.ps1
+)
+
+TAG=""
+CHECK_ONLY=0
+DO_INSTALL=1
+TMP_DIR=""
+
+log() { printf '\n==> %s\n' "$*"; }
+ok() { printf '✓ %s\n' "$*"; }
+warn() { printf 'WARNING: %s\n' "$*" >&2; }
+die() { printf 'ERROR: %s\n' "$*" >&2; exit 1; }
+
+usage() {
+  sed -n '2,17p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+}
+
+cleanup() {
+  if [ -n "$TMP_DIR" ] && [ -d "$TMP_DIR" ]; then
+    rm -rf -- "$TMP_DIR"
+  fi
+}
+trap cleanup EXIT
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --tag) [ $# -ge 2 ] || die "--tag needs a value"; TAG="$2"; shift 2 ;;
+    --tag=*) TAG="${1#--tag=}"; shift ;;
+    --check) CHECK_ONLY=1; shift ;;
+    --no-install) DO_INSTALL=0; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "unknown argument: $1 (see --help)" ;;
+  esac
+done
+
+sha256_file() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | awk '{print $1}'
+  else
+    shasum -a 256 "$1" | awk '{print $1}'
+  fi
+}
+
+fetch() { # url dest
+  local auth=()
+  if [ -n "${GITHUB_TOKEN:-}" ]; then
+    case "$1" in https://api.github.com/*) auth=(-H "Authorization: Bearer $GITHUB_TOKEN") ;; esac
+  fi
+  curl --retry 3 --retry-delay 2 --retry-connrefused --fail --location \
+    --silent --show-error ${auth[@]+"${auth[@]}"} --output "$2" "$1"
+}
+
+latest_tag() {
+  local tag=""
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    tag="$(gh api "repos/$REPO/releases/latest" --jq .tag_name 2>/dev/null || true)"
+  fi
+  if [ -z "$tag" ]; then
+    local json="$TMP_DIR/latest.json"
+    fetch "https://api.github.com/repos/$REPO/releases/latest" "$json"
+    tag="$(sed -n 's/^ *"tag_name": *"\([^"]*\)".*/\1/p' "$json" | head -n1)"
+  fi
+  [ -n "$tag" ] || die "could not read the latest release of $REPO"
+  printf '%s\n' "$tag"
+}
+
+env_value() { sed -n "s/^$1=//p" "$SDK_METADATA" | head -n1; }
+
+set_env_value() { # key value
+  local tmp="$SDK_METADATA.tmp.$$"
+  awk -v k="$1" -v v="$2" 'index($0, k "=") == 1 { print k "=" v; next } { print }' \
+    "$SDK_METADATA" > "$tmp"
+  mv "$tmp" "$SDK_METADATA"
+}
+
+# "SDK v0.43" -> "SDK v0.44" and "currently v0.43" / "currently **v0.43**".
+move_doc_mentions() { # old new
+  local old="$1" new="$2" file changed=0
+  local old_re="${old//./\\.}"
+  for file in "${DOC_FILES[@]}"; do
+    [ -f "$REPO_ROOT/$file" ] || continue
+    if grep -qE "(SDK|currently) (\*\*)?$old_re([^0-9]|$)" "$REPO_ROOT/$file"; then
+      local tmp="$REPO_ROOT/$file.tmp.$$"
+      sed -E "s/(SDK|currently) (\*\*)?$old_re([^0-9]|$)/\1 \2$new\3/g" "$REPO_ROOT/$file" > "$tmp"
+      cat "$tmp" > "$REPO_ROOT/$file" # keep the file's mode
+      rm -f -- "$tmp"
+      ok "Docs: $file now says $new"
+      changed=1
+    fi
+  done
+  [ "$changed" -eq 1 ] || ok "Docs: no $old mentions to move"
+}
+
+# Re-vendor crt/ and re-apply ps5upload.patch when the tag's crt differs from
+# what we vendored. Refuses (before anything is rewritten) if the patch no
+# longer applies: that needs a person, see payload/third_party/sdk-crt/README.md.
+check_crt() { # source-dir
+  local src="$1/crt" work="$TMP_DIR/crt-check" f
+  [ -d "$src" ] || die "the $TAG source has no crt/ directory"
+  rm -rf -- "$work"
+  mkdir -p "$work/crt"
+  cp "$src"/*.c "$src"/*.h "$src"/*.S "$work/crt/"
+  (cd "$work" && patch -p1 --quiet --forward < "$CRT_DIR/ps5upload.patch" >/dev/null) || \
+    die "ps5upload.patch no longer applies to the $TAG crt; re-vendor it by hand (payload/third_party/sdk-crt/README.md)"
+  CRT_CHANGED=0
+  for f in "$work"/crt/*; do
+    cmp -s "$f" "$CRT_DIR/$(basename "$f")" || { CRT_CHANGED=1; break; }
+  done
+  CRT_PATCHED_DIR="$work/crt"
+}
+
+# ── Resolve the target release ─────────────────────────────────────────────
+
+[ -f "$SDK_METADATA" ] || die "missing $SDK_METADATA"
+TMP_DIR="$(mktemp -d)"
+CUR_TAG="$(env_value PS5_SDK_TAG)"
+CUR_SHA="$(env_value PS5_SDK_SHA256)"
+
+if [ -z "$TAG" ]; then
+  log "Looking up the latest $REPO release"
+  TAG="$(latest_tag)"
+fi
+case "$TAG" in
+  v[0-9]*.[0-9]*) ;;
+  *) die "not a release tag: $TAG" ;;
+esac
+ok "Pinned: $CUR_TAG   Target: $TAG"
+
+if [ "$CHECK_ONLY" -eq 1 ]; then
+  if [ "$TAG" = "$CUR_TAG" ]; then
+    ok "Up to date"
+    exit 0
+  fi
+  printf 'Update available: %s -> %s (run scripts/update-ps5-sdk.sh --tag %s)\n' "$CUR_TAG" "$TAG" "$TAG"
+  exit 3
+fi
+
+# ── Download and check the release ─────────────────────────────────────────
+
+log "Downloading $REPO $TAG"
+ZIP="$TMP_DIR/ps5-payload-sdk.zip"
+fetch "https://github.com/$REPO/releases/download/$TAG/ps5-payload-sdk.zip" "$ZIP"
+SHA="$(sha256_file "$ZIP")"
+ok "Release zip SHA-256 $SHA"
+if [ "$TAG" = "$CUR_TAG" ] && [ "$SHA" != "$CUR_SHA" ]; then
+  die "the $TAG zip no longer matches the pinned checksum ($CUR_SHA); upstream re-uploaded it, check before trusting it"
+fi
+while IFS= read -r entry; do
+  case "$entry" in
+    ps5-payload-sdk/*) ;;
+    *) die "unexpected archive entry: $entry" ;;
+  esac
+  case "/$entry/" in
+    */../*|*/./*) die "unsafe archive entry: $entry" ;;
+  esac
+done < <(unzip -Z1 "$ZIP")
+unzip -q "$ZIP" -d "$TMP_DIR/zip"
+[ -f "$TMP_DIR/zip/ps5-payload-sdk/toolchain/prospero.mk" ] || die "the $TAG zip has no toolchain/prospero.mk"
+[ -f "$TMP_DIR/zip/ps5-payload-sdk/target/lib/crt1.o" ] || die "the $TAG zip has no target/lib/crt1.o"
+ok "Archive unpacks to an SDK"
+
+log "Fetching the $TAG source (prospero-nid, crt)"
+SRC_TGZ="$TMP_DIR/src.tar.gz"
+fetch "https://codeload.github.com/$REPO/tar.gz/refs/tags/$TAG" "$SRC_TGZ"
+mkdir -p "$TMP_DIR/src"
+tar -xzf "$SRC_TGZ" -C "$TMP_DIR/src" --strip-components=1
+UP_NID=""
+for candidate in host/bin/prospero-nid bin/prospero-nid; do
+  if [ -f "$TMP_DIR/src/$candidate" ]; then UP_NID="$TMP_DIR/src/$candidate"; break; fi
+done
+[ -n "$UP_NID" ] || die "the $TAG source has no prospero-nid"
+head -n1 "$UP_NID" | grep -q python || die "upstream prospero-nid at $TAG is no longer a Python script; vendor it by hand"
+check_crt "$TMP_DIR/src"
+
+# ── Rewrite the pin ────────────────────────────────────────────────────────
+
+log "Updating the repository pin"
+if [ "$TAG" = "$CUR_TAG" ]; then
+  ok "scripts/ps5-sdk.env already pins $TAG"
+else
+  set_env_value PS5_SDK_TAG "$TAG"
+  set_env_value PS5_SDK_SHA256 "$SHA"
+  ok "scripts/ps5-sdk.env: $CUR_TAG -> $TAG"
+fi
+
+UP_NID_SHA="$(sha256_file "$UP_NID")"
+if [ "$UP_NID_SHA" = "$(sha256_file "$PORTABLE_NID")" ]; then
+  ok "prospero-nid unchanged upstream"
+else
+  install -m 0755 "$UP_NID" "$PORTABLE_NID"
+  set_env_value PS5_SDK_NID_SHA256 "$UP_NID_SHA"
+  ok "prospero-nid updated from $TAG (sha256 $UP_NID_SHA)"
+fi
+
+if [ "$CRT_CHANGED" -eq 0 ]; then
+  ok "crt unchanged upstream (vendored copy + ps5upload.patch is current)"
+else
+  cp "$CRT_PATCHED_DIR"/* "$CRT_DIR/"
+  warn "crt changed upstream at $TAG: re-vendored into payload/third_party/sdk-crt with ps5upload.patch re-applied."
+  warn "Review the diff, rebuild, and compare llvm-nm of payload/third_party/sdk-crt/build/crt1.o with the SDK's target/lib/crt1.o."
+fi
+
+if [ "$TAG" != "$CUR_TAG" ]; then
+  move_doc_mentions "$CUR_TAG" "$TAG"
+fi
+
+# ── Install ────────────────────────────────────────────────────────────────
+
+if [ "$DO_INSTALL" -eq 0 ]; then
+  ok "Skipping the install (--no-install)"
+  exit 0
+fi
+
+log "Installing $TAG into $INSTALL_DIR"
+INSTALLER="$SCRIPT_DIR/install-ps5-sdk.sh"
+PARENT="$(dirname "$INSTALL_DIR")"
+installed_tag() { tr -d '[:space:]' < "$INSTALL_DIR/$VERSION_MARKER" 2>/dev/null || true; }
+
+if [ -f "$INSTALL_DIR/toolchain/prospero.mk" ] && [ "$(installed_tag)" = "$TAG" ] \
+  && [ ! -w "$INSTALL_DIR" ]; then
+  ok "$TAG is already installed at $INSTALL_DIR"
+elif { [ -d "$PARENT" ] && [ -w "$PARENT" ]; } \
+  || { [ "$(installed_tag)" = "$TAG" ] && [ -w "$INSTALL_DIR" ]; }; then
+  # The installer moves an old SDK aside itself, next to the new one.
+  PS5_SDK_INSTALL_DIR="$INSTALL_DIR" bash "$INSTALLER"
+else
+  # The parent (e.g. /opt) needs root. Stage the SDK as this user (so the
+  # SQLite sources the installer fetches into the repo stay user-owned), then
+  # swap it in.
+  STAGE="$TMP_DIR/stage/ps5-payload-sdk"
+  mkdir -p "$(dirname "$STAGE")"
+  PS5_SDK_INSTALL_DIR="$STAGE" bash "$INSTALLER"
+  OLD_TAG="$(installed_tag)"
+  BACKUP_SUFFIX="backup-${OLD_TAG:-unknown}-$(date +%Y%m%d-%H%M%S)"
+  if [ -t 0 ] || sudo -n true 2>/dev/null; then
+    if [ -e "$INSTALL_DIR" ]; then
+      sudo mv "$INSTALL_DIR" "$INSTALL_DIR.$BACKUP_SUFFIX"
+      ok "Moved the previous SDK to $INSTALL_DIR.$BACKUP_SUFFIX"
+    fi
+    sudo mkdir -p "$PARENT"
+    sudo mv "$STAGE" "$INSTALL_DIR"
+  elif [ -d "$INSTALL_DIR" ] && [ -w "$INSTALL_DIR" ]; then
+    # No sudo, but the SDK directory itself is ours: swap its contents and
+    # keep the old ones in the home directory (the parent isn't writable).
+    BACKUP="${PS5_SDK_BACKUP_DIR:-$HOME}/$(basename "$INSTALL_DIR").$BACKUP_SUFFIX"
+    mkdir -p "$BACKUP"
+    find "$INSTALL_DIR" -mindepth 1 -maxdepth 1 -exec mv {} "$BACKUP/" \;
+    if ! find "$STAGE" -mindepth 1 -maxdepth 1 -exec mv {} "$INSTALL_DIR/" \;; then
+      find "$INSTALL_DIR" -mindepth 1 -maxdepth 1 -exec rm -rf {} + || true
+      find "$BACKUP" -mindepth 1 -maxdepth 1 -exec mv {} "$INSTALL_DIR/" \;
+      die "could not install into $INSTALL_DIR; the previous SDK was restored"
+    fi
+    ok "Moved the previous SDK to $BACKUP ($PARENT is not writable without sudo)"
+  else
+    die "$INSTALL_DIR is not writable; re-run from a terminal so sudo can ask for a password"
+  fi
+  ok "Installed PS5 Payload SDK $TAG at $INSTALL_DIR"
+fi
+
+[ "$(installed_tag)" = "$TAG" ] || die "$INSTALL_DIR does not report $TAG after the install"
+
+log "Done"
+printf 'SDK %s at %s.\nNext: rm -rf payload/build payload/installer/build payload/third_party/sdk-crt/build && make payload test-payload\n' \
+  "$TAG" "$INSTALL_DIR"
+if [ "$TAG" != "$CUR_TAG" ]; then
+  printf 'Review and commit: git diff -- scripts/ps5-sdk.env scripts/ps5-sdk payload/third_party/sdk-crt %s\n' "${DOC_FILES[*]}"
+fi
@@ -24,7 +24,7 @@ else
 endif

 # ps5upload: link ps5upload's own build of the SDK's startup code (see
-# payload/sdk-crt.mk). The SDK v0.43 one stops before main() on FW 5.50.
+# payload/sdk-crt.mk). The SDK's own one (v0.43 on) stops before main() on FW 5.50.
 include ../../payload/sdk-crt.mk

 CFLAGS := -Wall -Werror -O1