fix: range-check uid, gid and sysfs integer conversions (#1601)

* feat(ec2): add CleanupStorage to delete free volumes and clear instance, volume and spot tag residue

* fix(ec2): read teardown before deleting volumes and report volumes that appear during cleanup

* test: align the fake deleter fields

* feat(ec2): add CleanupStorage to delete free volumes and clear instance, volume and spot tag residue

* fix(ec2): read teardown before deleting volumes and report volumes that appear during cleanup

* test: align the fake deleter fields

.github/CODEOWNERS

@@ -1,15 +0,0 @@
-# CODEOWNERS — GitHub PR review enforcement
-#
-# Format: <path pattern>  <owner> [<owner> …]
-# Order matters — last matching pattern wins.
-#
-# Set the matching branch protection rule on `dev` and `main` to
-# "Require review from Code Owners" or this file is advisory only.
-
-# Network layer is governed by its invariant tests.
-# Changes here must respect those clauses
-# see spinifex/domains/network/invariants/
-# mulga docs/development/proposals/region-local-architecture/0006-spinifex-network-layer-contract.md (proposal, not accepted)
-/spinifex/domains/network/          @joshsiv-mulga
-/spinifex/runtime/roles/vpcd/ @joshsiv-mulga
-/spinifex/domains/network/invariants/ @joshsiv-mulga

.github/pull_request_template.md

@@ -6,20 +6,6 @@
 
 <!-- The notable changes, as bullets. -->
 
-## Account-scoped lifecycle impact
-
-<!-- Complete this section only when the PR changes account-scoped resource lifecycle, account termination, resource cleanup, or a lifecycle boundary. Otherwise write: N/A. -->
-
-- Lifecycle owner and resource family:
-- Owner-local ordering, recovery, retained-state, or force impact:
-- Cross-domain dependency or ownership impact:
-- Evidence added or rechecked:
-- ADR-0008 lifecycle register / ADR-0001 migration-record / bead updates:
-
-## Mulga design
-
-<!-- One line, so a reviewer knows whether the design records in the private mulga repository need to change. Write either "Updated: <mulga PR or bead id>" or "Not needed: <reason>". This is a reminder, not a gate. -->
-
 ## Community Contribution License
 
 - [ ] All community contributions in this pull request are licensed to Mulga under the terms of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). By creating this pull request I represent that I have the right to license these contributions to Mulga under the Apache License 2.0.

.github/scripts/hypervisor-disk-preflight_test.sh

@@ -1,87 +0,0 @@
-#!/bin/sh
-# hypervisor-disk-preflight_test.sh — drives hypervisor-disk-preflight.sh against
-# a stub ssh that answers for each hypervisor from a canned file, so every
-# verdict is checked without a real host.
-set -eu
-
-SCRIPT_DIR=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
-PREFLIGHT="$SCRIPT_DIR/hypervisor-disk-preflight.sh"
-TMP=$(mktemp -d)
-trap 'rm -rf "$TMP"' EXIT
-
-fails=0
-pass() { echo "  ok   - $1"; }
-fail() { echo "  FAIL - $1"; fails=$((fails + 1)); }
-
-# The stub answers "<root-kb> <pool-kb> <path>" from $FAKE/<host>, or exits 255
-# when that host has no file, the way ssh does for a host it cannot reach.
-mkdir -p "$TMP/bin" "$TMP/hosts"
-cat > "$TMP/bin/ssh" <<'STUB'
-#!/bin/sh
-for a in "$@"; do case $a in *@*) host=${a#*@} ;; esac; done
-cat >/dev/null
-if [ -f "$FAKE/$host" ]; then cat "$FAKE/$host"; exit 0; fi
-echo "ssh: Could not resolve hostname $host" >&2
-exit 255
-STUB
-chmod +x "$TMP/bin/ssh"
-PATH="$TMP/bin:$PATH"
-FAKE="$TMP/hosts"
-export PATH FAKE
-
-cat > "$TMP/env.tfvars" <<'TFVARS'
-nodes = [
-  { name = "wattle", wan_ip = "192.0.2.1", storage_pool = "drive1-pool", base_image = "/x.qcow2" },
-  # { name = "retired", wan_ip = "192.0.2.9", storage_pool = "drive1-pool", base_image = "/x.qcow2" },
-  { name = "banksia", wan_ip = "192.0.2.2", storage_pool = "nvme1-pool", base_image = "/x.qcow2" },
-]
-TFVARS
-
-GiB=1048576
-plenty="$((50 * GiB)) $((200 * GiB)) /mnt/drive1/pool"
-
-# run <label> <want-rc> <want-text>
-run() {
-    rc=0
-    out=$(bash "$PREFLIGHT" "$TMP/env.tfvars" 2>&1) || rc=$?
-    if [ "$rc" -ne "$2" ]; then
-        fail "$1: exit $rc, want $2"
-        echo "$out" | sed 's/^/        /'
-        return
-    fi
-    case $out in
-        *"$3"*) pass "$1" ;;
-        *) fail "$1: output lacks '$3'"; echo "$out" | sed 's/^/        /' ;;
-    esac
-}
-
-echo "-- hypervisor-disk-preflight.sh"
-
-echo "$plenty" > "$FAKE/wattle"
-echo "$plenty" > "$FAKE/banksia"
-run "every host has room" 0 "banksia: root fs 51200 MiB free"
-
-echo "0 $((200 * GiB)) /mnt/drive1/pool" > "$FAKE/wattle"
-run "a full root filesystem fails fast" 1 "::error::hypervisor wattle has 0 MiB free on the filesystem holding /etc/libvirt/qemu"
-
-echo "$plenty" > "$FAKE/wattle"
-echo "$((50 * GiB)) $((3 * GiB)) /mnt/nvme1/pool" > "$FAKE/banksia"
-run "a nearly full pool fails fast" 1 "::error::hypervisor banksia has 3 GiB free in storage pool nvme1-pool"
-
-echo "$plenty" > "$FAKE/banksia"
-rm -f "$FAKE/wattle"
-run "an unreachable host is reported, not failed" 0 "::warning::hypervisor disk preflight: cannot reach wattle"
-
-echo "$plenty" > "$FAKE/wattle"
-echo "$((50 * GiB)) - -" > "$FAKE/banksia"
-run "a pool libvirt does not know is reported, not failed" 0 "pool nvme1-pool (-) not found"
-
-echo "0 0 /x" > "$FAKE/retired"
-echo "$plenty" > "$FAKE/banksia"
-run "a commented-out node is never checked" 0 "wattle: root fs"
-
-if [ "$fails" -ne 0 ]; then
-    echo "$fails failure(s)"
-    exit 1
-fi
-echo "  hypervisor-disk-preflight ok"

.github/scripts/mulga-design-check.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Warn when a PR body has no filled "Mulga design" line. Reads PR_BODY and
+# never fails the job: the check is a prompt, not a gate.
+set -euo pipefail
+shopt -s nocasematch
+
+section_re='^#{1,6}[[:space:]]*Mulga design[[:space:]]*$'
+line_re='^[[:space:]]*(Updated|Not needed)[[:space:]]*:[[:space:]]*(.*)$'
+placeholder_re='<[^<>]*>'
+
+filled() {
+  local body=$1 line value kept inside=0 pre rest
+  body=${body//$'\r'/}
+  while [[ $body == *'<!--'*'-->'* ]]; do
+    pre=${body%%'<!--'*}
+    rest=${body#*'<!--'}
+    body=$pre${rest#*'-->'}
+  done
+  while IFS= read -r line; do
+    if [[ $line =~ $section_re ]]; then
+      inside=1
+    elif ((inside)) && [[ ${line#"${line%%[![:space:]]*}"} == '#'* ]]; then
+      return 1
+    elif ((inside)) && [[ $line =~ $line_re ]]; then
+      value=${BASH_REMATCH[2]} kept=''
+      while [[ $value =~ $placeholder_re ]]; do
+        kept+=${value%%"${BASH_REMATCH[0]}"*}
+        value=${value#*"${BASH_REMATCH[0]}"}
+      done
+      [[ $kept$value == *[![:space:]]* ]] && return 0
+    fi
+  done <<<"$body"
+  return 1
+}
+
+if filled "${PR_BODY:-}"; then
+  echo "The Mulga design line is filled in."
+else
+  echo '::warning title=Mulga design::Add a "## Mulga design" section with one line: "Updated: <mulga PR>" or "Not needed: <reason>".'
+fi

.github/scripts/mulga_design_check.py

@@ -1,36 +0,0 @@
-#!/usr/bin/env python3
-"""Warn when a PR body has no filled "Mulga design" line. Reads PR_BODY; never fails the job."""
-
-import os
-import re
-
-COMMENT_RE = re.compile(r"<!--.*?-->", re.S)
-SECTION_RE = re.compile(r"^#{1,6}\s*Mulga design\s*$", re.I)
-LINE_RE = re.compile(r"^\s*(Updated|Not needed)\s*:\s*(.*?)\s*$", re.I)
-PLACEHOLDER_RE = re.compile(r"<[^<>]*>")
-
-
-def filled(body):
-    inside = False
-    for line in COMMENT_RE.sub("", body or "").splitlines():
-        if SECTION_RE.match(line):
-            inside = True
-        elif inside and line.lstrip().startswith("#"):
-            return False
-        elif inside:
-            m = LINE_RE.match(line)
-            if m and PLACEHOLDER_RE.sub("", m.group(2)).strip():
-                return True
-    return False
-
-
-def main():
-    if filled(os.environ.get("PR_BODY", "")):
-        print("The Mulga design line is filled in.")
-    else:
-        print('::warning title=Mulga design::Add a line under "## Mulga design": "Updated: <mulga PR or bead id>" or "Not needed: <reason>".')
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

.github/scripts/test_mulga_design_check.py

@@ -1,23 +0,0 @@
-import unittest
-
-from mulga_design_check import filled
-
-
-class FilledTest(unittest.TestCase):
-    def test_accepts_either_form(self):
-        self.assertTrue(filled("## Mulga design\nUpdated: mulga#275"))
-        self.assertTrue(filled("## Mulga design\n\nnot needed: internal refactor\n## Next"))
-
-    def test_rejects_unanswered(self):
-        self.assertFalse(filled(""))
-        self.assertFalse(filled("## Mulga design\n<!-- Updated: x -->"))
-        self.assertFalse(filled("## Mulga design\nUpdated: <mulga PR or bead id>"))
-        self.assertFalse(filled("## Mulga design\nUpdated:"))
-
-    def test_scoped_to_the_section(self):
-        self.assertFalse(filled("Updated: mulga#1"))
-        self.assertFalse(filled("## Mulga design\n## Other\nUpdated: mulga#1"))
-
-
-if __name__ == "__main__":
-    unittest.main()

.github/scripts/wait-for-memory_test.sh

@@ -1,47 +0,0 @@
-#!/bin/sh
-# wait-for-memory_test.sh — drives wait-for-memory.sh against a fake meminfo
-# that a background writer changes mid-wait, so each verdict is checked without
-# a loaded host.
-set -eu
-
-SCRIPT_DIR=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
-WAIT="$SCRIPT_DIR/wait-for-memory.sh"
-TMP=$(mktemp -d)
-trap 'rm -rf "$TMP"' EXIT
-
-fails=0
-pass() { echo "  ok   - $1"; }
-fail() { echo "  FAIL - $1"; fails=$((fails + 1)); }
-
-meminfo() { printf 'MemTotal:       65536000 kB\nMemAvailable:   %s kB\n' "$(( $1 * 1024 ))" > "$TMP/meminfo"; }
-MEMINFO="$TMP/meminfo"
-MEM_WAIT_POLL_S=1
-export MEMINFO MEM_WAIT_POLL_S
-
-meminfo 30000
-if MEM_WAIT_TIMEOUT_S=5 bash "$WAIT" 26624 > "$TMP/out" 2>&1; then
-  pass "enough memory returns at once"
-else
-  fail "enough memory returns at once: $(cat "$TMP/out")"
-fi
-
-meminfo 21577
-( sleep 2; meminfo 30000 ) &
-if MEM_WAIT_TIMEOUT_S=20 bash "$WAIT" 26624 > "$TMP/out" 2>&1 && grep -q waiting "$TMP/out"; then
-  pass "memory freed mid-wait is admitted"
-else
-  fail "memory freed mid-wait is admitted: $(cat "$TMP/out")"
-fi
-wait
-
-meminfo 21577
-if MEM_WAIT_TIMEOUT_S=2 bash "$WAIT" 26624 > "$TMP/out" 2>&1; then
-  fail "memory that never frees fails: exited 0"
-elif grep -q '::error::need 26624 MiB available, have 21577 MiB' "$TMP/out" && grep -q 'RSS' "$TMP/out"; then
-  pass "memory that never frees fails and names the biggest processes"
-else
-  fail "memory that never frees fails and names the biggest processes: $(cat "$TMP/out")"
-fi
-
-[ "$fails" -eq 0 ] || { echo "wait-for-memory: $fails failed"; exit 1; }
-echo "wait-for-memory: all passed"

.github/workflows/dev-release.yml

@@ -30,6 +30,10 @@ concurrency:
 jobs:
   prerelease:
     runs-on: ubuntu-26.04
+    env:
+      # Dev prereleases, newest published first: GitHub lists releases by tag name
+      # as text, so list order is not build order. The install Worker uses this rule.
+      DEV_RELEASES_JQ: '[.[] | select(.draft == false and .prerelease and .published_at != null and (.tag_name | test("-dev(\\.|$)")))] | sort_by(.published_at) | reverse'
     steps:
       # Full history and tags, because the tag name is git describe and a shallow
       # clone has no tag to describe against.
@@ -164,12 +168,12 @@ jobs:
               exit 1
           fi
           echo "latest is still $latest"
-          dev="$(gh api "repos/$GITHUB_REPOSITORY/releases?per_page=20" --jq 'map(select(.prerelease))[0].tag_name')"
+          dev="$(gh api "repos/$GITHUB_REPOSITORY/releases?per_page=100" --jq "$DEV_RELEASES_JQ | .[0].tag_name")"
           [ "$dev" = "$TAG" ] || { echo "::error::the dev channel resolves to $dev, not $TAG"; exit 1; }
 
-      # Kept rather than unbounded: the Worker reads the first page of releases to
-      # resolve the channel, so enough prereleases would eventually push the real
-      # ones off it. Five leaves a few recent builds to roll back to.
+      # Kept rather than unbounded: the Worker reads one page of releases to resolve
+      # the channel, so enough prereleases would eventually push the newest off it.
+      # Five leaves a few recent builds to roll back to.
       - name: Prune old dev prereleases
         if: steps.version.outputs.exists != 'true'
         env:
@@ -177,7 +181,7 @@ jobs:
         run: |
           set -euo pipefail
           gh api "repos/$GITHUB_REPOSITORY/releases?per_page=100" \
-              --jq 'map(select(.prerelease and (.tag_name | endswith("-dev")))) | .[5:] | .[].tag_name' \
+              --jq "$DEV_RELEASES_JQ | .[5:] | .[].tag_name" \
               > stale.txt
           while read -r tag; do
               [ -n "$tag" ] || continue

.github/workflows/e2e-nightly.yml

@@ -1017,7 +1017,7 @@ jobs:
         id: siblings
         env:
           BRANCH: ${{ env.GIT_BRANCH }}
-        run: bash .github/resolve-sibling-refs.sh
+        run: bash .github/scripts/resolve-sibling-refs.sh
         working-directory: mulga/spinifex
 
       - uses: actions/checkout@v7.0.1
@@ -1275,7 +1275,7 @@ jobs:
         id: siblings
         env:
           BRANCH: ${{ env.GIT_BRANCH }}
-        run: bash .github/resolve-sibling-refs.sh
+        run: bash .github/scripts/resolve-sibling-refs.sh
         working-directory: mulga/spinifex
 
       - uses: actions/checkout@v7.0.1
@@ -1423,7 +1423,7 @@ jobs:
         id: siblings
         env:
           BRANCH: ${{ github.ref_name }}
-        run: bash .github/resolve-sibling-refs.sh
+        run: bash .github/scripts/resolve-sibling-refs.sh
         working-directory: spinifex
 
       - name: Checkout Predastore
@@ -1547,7 +1547,7 @@ jobs:
         id: siblings
         env:
           BRANCH: ${{ github.ref_name }}
-        run: bash .github/resolve-sibling-refs.sh
+        run: bash .github/scripts/resolve-sibling-refs.sh
         working-directory: spinifex
 
       - name: Checkout Predastore

.github/workflows/mulga-design.yml

@@ -2,7 +2,8 @@ name: Mulga design
 
 # Reminds the author to say whether the Mulga design records need to change.
 # It reads only the pull request body, uses no secrets, and warns without ever
-# failing: the check is a prompt, not a gate.
+# failing: the check is a prompt, not a gate. Fork PRs are skipped because their
+# authors cannot see the design records.
 
 on:
   pull_request:
@@ -16,7 +17,7 @@ permissions:
 jobs:
   mulga_design:
     name: Mulga design line
-    if: ${{ !endsWith(github.actor, '[bot]') }}
+    if: ${{ !endsWith(github.actor, '[bot]') && github.event.pull_request.head.repo.full_name == github.repository }}
     runs-on: ubuntu-26.04
     steps:
       - name: Checkout Code
@@ -28,6 +29,4 @@ jobs:
         env:
           PR_BODY: ${{ github.event.pull_request.body }}
         working-directory: .github/scripts
-        run: |
-          python3 -m unittest -q test_mulga_design_check
-          python3 mulga_design_check.py
+        run: bash mulga-design-check.sh

.github/workflows/perf-3node.yml

@@ -113,7 +113,7 @@ jobs:
         id: siblings
         env:
           BRANCH: ${{ env.GIT_BRANCH }}
-        run: bash .github/resolve-sibling-refs.sh
+        run: bash .github/scripts/resolve-sibling-refs.sh
         working-directory: spinifex
 
       - uses: actions/checkout@v7.0.1

.github/workflows/publish-system-ami.yml

@@ -84,7 +84,7 @@ jobs:
 
       - name: Resolve sibling release tags from go.mod
         id: siblings
-        run: bash spinifex/.github/resolve-release-sibling-refs.sh spinifex/go.mod
+        run: bash spinifex/.github/scripts/resolve-release-sibling-refs.sh spinifex/go.mod
 
       - name: Checkout Viperblock
         uses: actions/checkout@v7.0.1

.github/workflows/release.yml

@@ -18,7 +18,7 @@ jobs:
 
       - name: Resolve sibling release tags from go.mod
         id: siblings
-        run: bash spinifex/.github/resolve-release-sibling-refs.sh spinifex/go.mod
+        run: bash spinifex/.github/scripts/resolve-release-sibling-refs.sh spinifex/go.mod
 
       - name: Checkout Predastore
         uses: actions/checkout@v7.0.1
@@ -85,7 +85,7 @@ jobs:
 
       - name: Resolve sibling release tags from go.mod
         id: siblings
-        run: bash spinifex/.github/resolve-release-sibling-refs.sh spinifex/go.mod
+        run: bash spinifex/.github/scripts/resolve-release-sibling-refs.sh spinifex/go.mod
 
       - name: Checkout Predastore
         uses: actions/checkout@v7.0.1
@@ -335,7 +335,7 @@ jobs:
 
       - name: Resolve sibling release tags from go.mod
         id: siblings
-        run: bash spinifex/.github/resolve-release-sibling-refs.sh spinifex/go.mod
+        run: bash spinifex/.github/scripts/resolve-release-sibling-refs.sh spinifex/go.mod
 
       - name: Checkout Predastore
         uses: actions/checkout@v7.0.1

.github/workflows/segscan-oracle.yml

@@ -34,7 +34,7 @@ jobs:
         id: siblings
         env:
           BRANCH: ${{ github.head_ref || github.ref_name }}
-        run: bash .github/resolve-sibling-refs.sh
+        run: bash .github/scripts/resolve-sibling-refs.sh
         working-directory: spinifex
 
       - name: Checkout Viperblock

.github/workflows/spinifex.yml

@@ -20,6 +20,12 @@ on:
 permissions:
   contents: read
 
+# A newer push to the same pull request supersedes its run. Pushes and dispatches
+# get a group of their own, so every commit on dev and main keeps its result.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
   build_and_test:
     name: Build and Test
@@ -36,7 +42,7 @@ jobs:
         id: siblings
         env:
           BRANCH: ${{ github.head_ref || github.ref_name }}
-        run: bash .github/resolve-sibling-refs.sh
+        run: bash .github/scripts/resolve-sibling-refs.sh
         working-directory: spinifex
 
       - name: Checkout Viperblock
@@ -166,7 +172,7 @@ jobs:
         id: siblings
         env:
           BRANCH: ${{ github.head_ref || github.ref_name }}
-        run: bash .github/resolve-sibling-refs.sh
+        run: bash .github/scripts/resolve-sibling-refs.sh
         working-directory: spinifex
 
       - name: Checkout Viperblock
@@ -268,7 +274,7 @@ jobs:
         id: siblings
         env:
           BRANCH: ${{ github.head_ref || github.ref_name }}
-        run: bash .github/resolve-sibling-refs.sh
+        run: bash .github/scripts/resolve-sibling-refs.sh
         working-directory: spinifex
 
       - name: Checkout Viperblock

.github/workflows/ui.yml

@@ -30,6 +30,12 @@ on:
 permissions:
   contents: read
 
+# A newer push to the same pull request supersedes its run. Pushes and dispatches
+# get a group of their own, so every commit on dev and main keeps its result.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
   ui_build_and_test:
     name: UI Build and Test

.gitignore

@@ -27,6 +27,7 @@ build/microvm/sqs-worker/.stage.*/
 build/microvm/lambda-runtime/vmlinuz
 build/microvm/lambda-runtime/initramfs.cpio.gz
 build/microvm/lambda-runtime/.stage.*/
+build/microvm/lambda-testlink-runtime/
 build/qboot/
 !spinifex/runtime/roles/spinifexui/frontend/dist/
 tmp/

Makefile

@@ -42,11 +42,15 @@ ifdef QUIET
   _COVQ  = 2>&1 | { grep -Ev '^\s*(ok|PASS|\?|=== RUN|--- PASS:)\s' | grep -v 'coverage: 0\.0%' || true; }; exit $${PIPESTATUS[0]}
   _RACEQ = 2>&1 | { grep -Ev '^\s*(ok|PASS|\?|=== RUN|--- PASS:)\s' || true; }; exit $${PIPESTATUS[0]}
   _SECQ  = >
+  _HDR   = :
+  _RUNSH = sh "$$t" >"$$log" 2>&1 || { echo "-- $$t"; cat "$$log"; exit 1; }
 else
   _Q     =
   _COVQ  =
   _RACEQ =
   _SECQ  = 2>&1 | tee
+  _HDR   = echo -e
+  _RUNSH = echo "-- $$t"; sh "$$t" || exit 1
 endif
 
 build: go_build build-installer build-lb-agent generate-aws-model-coverage
@@ -78,6 +82,35 @@ go_build:
 	@echo -e "\n....Building $(GO_PROJECT_NAME)"
 	go build $(GO_BUILD_MOD) -ldflags "$(LDFLAGS)" -o ./bin/$(GO_PROJECT_NAME) cmd/spinifex/main.go
 
+# Controlled-test only: builds the tagged daemon and its hard-kill initializer
+# together, pinning the initializer's digest into that daemon build. The daemon
+# keeps its symbols so the pin can be read back from the binary.
+# LAMBDA_IMAGE_DIGEST is the test-link runtime image digest that
+# build-lambda-testlink-image prints; it is read raw and validated before use.
+LAMBDA_TESTLINK_DIR := ./bin/lambda-testlink
+LAMBDA_TESTLINK_PKG := github.com/mulgadc/spinifex/spinifex/runtime/daemon
+LAMBDA_TESTLINK_PIN := $(LAMBDA_TESTLINK_PKG).lambdaHardKillSHA256
+LAMBDA_DIGEST_RE := ^[0-9a-f]{64}$$
+build-lambda-testlink: override export LAMBDA_IMAGE_DIGEST := $(value LAMBDA_IMAGE_DIGEST)
+build-lambda-testlink:
+	@[[ "$$LAMBDA_IMAGE_DIGEST" =~ $(LAMBDA_DIGEST_RE) ]] || { echo "LAMBDA_IMAGE_DIGEST must be 64 lowercase hex digits"; exit 1; }
+	@host=$$(uname -m); goos=$$(go env GOOS); goarch=$$(go env GOARCH); \
+	test "$$host" = x86_64 && test "$$goos/$$goarch" = linux/amd64 || { echo "the test link supports only an x86_64 host building linux/amd64, not $$host building $$goos/$$goarch"; exit 1; }
+	@rm -f $(LAMBDA_TESTLINK_DIR)/hardkill.so $(LAMBDA_TESTLINK_DIR)/$(GO_PROJECT_NAME)
+	@mkdir -p $(LAMBDA_TESTLINK_DIR).tmp
+	@rm -f $(LAMBDA_TESTLINK_DIR).tmp/hardkill.so $(LAMBDA_TESTLINK_DIR).tmp/$(GO_PROJECT_NAME)
+	cc -std=c17 -O2 -Wall -Wextra -Werror -shared -fPIC -o $(LAMBDA_TESTLINK_DIR).tmp/hardkill.so spinifex/runtime/compute/lambda/testlink/hardkill/hardkill.c -lrt
+	scripts/check-glibc-ceiling.sh 2.34 $(LAMBDA_TESTLINK_DIR).tmp/hardkill.so
+	@digest=$$(sha256sum $(LAMBDA_TESTLINK_DIR).tmp/hardkill.so | cut -d' ' -f1); \
+	test $${#digest} -eq 64 || { echo "initializer digest missing"; exit 1; }; \
+	echo "initializer sha256 $$digest"; \
+	pin="-X $(LAMBDA_TESTLINK_PIN)=$$digest -X $(LAMBDA_TESTLINK_PKG).lambdaImageDigest=$$LAMBDA_IMAGE_DIGEST"; \
+	LAMBDA_TESTLINK_INITIALIZER=$(abspath $(LAMBDA_TESTLINK_DIR).tmp/hardkill.so) go test -count=1 -tags lambdatestlink -ldflags "$$pin" -run '^TestLambda(HardKillPin|ImageDigestPin)$$' ./spinifex/runtime/daemon/ && \
+	go build $(GO_BUILD_MOD) -tags lambdatestlink -ldflags "$(subst -s -w ,,$(LDFLAGS)) $$pin" -o $(LAMBDA_TESTLINK_DIR).tmp/$(GO_PROJECT_NAME) cmd/spinifex/main.go
+	@mkdir -p $(LAMBDA_TESTLINK_DIR)
+	mv $(LAMBDA_TESTLINK_DIR).tmp/hardkill.so $(LAMBDA_TESTLINK_DIR).tmp/$(GO_PROJECT_NAME) $(LAMBDA_TESTLINK_DIR)/
+	@rmdir $(LAMBDA_TESTLINK_DIR).tmp
+
 build-installer:
 	@echo -e "\n....Building spinifex-installer"
 	go build -ldflags "-s -w" -o ./bin/spinifex-installer cmd/installer/main.go
@@ -193,6 +226,24 @@ bin/lambda-agent: go.mod go.sum $$(call go_local_srcs,./cmd/lambda-agent)
 	GOWORK=off CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags '-s -w' -o $@ ./cmd/lambda-agent
 
 build-lambda-runtime-microvm-image: $(LAMBDA_RUNTIME_MICROVM_ARTIFACTS) ## Build the Lambda runtime microVM kernel and initramfs (not shipped)
+	GOWORK=off go run ./cmd/lambda-image-agent-tag $(LAMBDA_RUNTIME_MICROVM_OUT_DIR)/initramfs.cpio.gz absent
+
+# Controlled-test only: a separately built guest whose agent has the
+# lambdatestlink tag, in its own outputs, never touching bin/lambda-agent or the
+# default image. It prints the digest to pass as LAMBDA_IMAGE_DIGEST.
+LAMBDA_TESTLINK_IMAGE_DIR := $(MICROVM_OUT_DIR)/lambda-testlink-runtime
+build-lambda-testlink-image: ## Build the test-link Lambda guest image and print its digest (not shipped)
+	@host=$$(uname -m); goos=$$(go env GOOS); goarch=$$(go env GOARCH); \
+	test "$$host" = x86_64 && test "$$goos/$$goarch" = linux/amd64 || { echo "the test link supports only an x86_64 host building linux/amd64, not $$host building $$goos/$$goarch"; exit 1; }
+	$(MAKE) --no-print-directory $(MICROVM_OUT_DIR)/qboot.rom
+	@mkdir -p bin $(LAMBDA_TESTLINK_IMAGE_DIR)
+	GOWORK=off GOFLAGS= CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -tags lambdatestlink -ldflags '-s -w' -o bin/lambda-agent-testlink ./cmd/lambda-agent
+	./scripts/build-lambda-runtime-microvm-image.sh bin/lambda-agent-testlink $(LAMBDA_TESTLINK_IMAGE_DIR)
+	GOWORK=off go run ./cmd/lambda-image-agent-tag $(LAMBDA_TESTLINK_IMAGE_DIR)/initramfs.cpio.gz present
+	install -m 0644 $(MICROVM_OUT_DIR)/qboot.rom $(LAMBDA_TESTLINK_IMAGE_DIR)/qboot.rom
+	@digest=$$(GOWORK=off go run -tags lambdatestlink ./cmd/lambda-image-digest $(LAMBDA_TESTLINK_IMAGE_DIR)) && \
+	[[ "$$digest" =~ $(LAMBDA_DIGEST_RE) ]] || { echo "image digest not computed"; exit 1; }; \
+	echo "LAMBDA_IMAGE_DIGEST=$$digest"
 
 # qboot is the microvm firmware. The source tarball ships with each release
 # because qboot is GPL-2.0.
@@ -240,27 +291,29 @@ preflight:
 NODE_SCRIPTS := scripts/setup.sh scripts/setup-ovn.sh scripts/install-node.sh scripts/smoke-test.sh scripts/node-reset.sh scripts/uninstall-spx.sh scripts/lib/distro.sh scripts/lib/stage-sqs-store-microvm.sh
 
 test-build-scripts:
-	@echo -e "\n....Running build/scripts/**/*_test.sh...."
-	@for t in $$(find build/scripts -name '*_test.sh' | sort); do \
-		echo "-- $$t"; \
-		sh "$$t" || exit 1; \
+	@$(_HDR) "\n....Running build/scripts/**/*_test.sh...."
+	@log=$$(mktemp); trap 'rm -f "$$log"' EXIT; for t in $$(find build/scripts -name '*_test.sh' | sort); do \
+		$(_RUNSH); \
 	done
-	@echo -e "\n....Running scripts/*_test.sh, scripts/lib/*_test.sh and scripts/appliance/*_test.sh...."
-	@for t in $$( (find scripts -maxdepth 1 -name '*_test.sh'; find scripts/lib scripts/appliance -name '*_test.sh') | sort); do \
-		echo "-- $$t"; \
-		sh "$$t" || exit 1; \
+	@$(_HDR) "\n....Running scripts/*_test.sh, scripts/lib/*_test.sh and scripts/appliance/*_test.sh...."
+	@log=$$(mktemp); trap 'rm -f "$$log"' EXIT; for t in $$( (find scripts -maxdepth 1 -name '*_test.sh'; find scripts/lib scripts/appliance -name '*_test.sh') | sort); do \
+		$(_RUNSH); \
 	done
-	@echo -e "\n....Running .github/scripts/*_test.sh...."
-	@for t in $$(find .github/scripts -maxdepth 1 -name '*_test.sh' | sort); do \
-		echo "-- $$t"; \
-		sh "$$t" || exit 1; \
+	@$(_HDR) "\n....Running scripts/terraform/latitude-spx/*_test.sh...."
+	@log=$$(mktemp); trap 'rm -f "$$log"' EXIT; for t in $$(find scripts/terraform/latitude-spx -maxdepth 1 -name '*_test.sh' | sort); do \
+		$(_RUNSH); \
 	done
-	shellcheck -S warning .github/scripts/hypervisor-disk-preflight.sh .github/scripts/hypervisor-disk-preflight_test.sh \
-		.github/scripts/wait-for-memory.sh .github/scripts/wait-for-memory_test.sh
-	@echo -e "\n....Running shellcheck over build/scripts/**/*.sh + the node scripts...."
-	shellcheck -S warning $$(find build/scripts -name '*.sh' | sort) $(NODE_SCRIPTS)
-	shellcheck -S warning -x scripts/build-oracle-appliance.sh $$(find scripts/appliance -name '*.sh' | sort)
-	@echo "  test-build-scripts ok"
+	@$(_HDR) "\n....Running .github/scripts/*_test.sh...."
+	@log=$$(mktemp); trap 'rm -f "$$log"' EXIT; for t in $$(find .github/scripts -maxdepth 1 -name '*_test.sh' | sort); do \
+		$(_RUNSH); \
+	done
+	$(_Q)shellcheck -S warning .github/scripts/hypervisor-disk-preflight.sh \
+		.github/scripts/wait-for-memory.sh \
+		.github/scripts/mulga-design-check.sh
+	@$(_HDR) "\n....Running shellcheck over build/scripts/**/*.sh + the node scripts...."
+	$(_Q)shellcheck -S warning $$(find build/scripts -name '*.sh' | sort) $(NODE_SCRIPTS)
+	$(_Q)shellcheck -S warning -x scripts/build-oracle-appliance.sh $$(find scripts/appliance -name '*.sh' | sort)
+	@$(_HDR) "  test-build-scripts ok"
 
 # E2E harness unit tests. Build-tagged `e2e` so they're skipped by the
 # default `go test ./spinifex/...`. Runs with mocked AWS clients — no
@@ -327,7 +380,10 @@ test-cover:
 test-race:
 	@echo -e "\n....Running tests with race detector for $(GO_PROJECT_NAME)...."
 	$(_Q)LOG_IGNORE=1 SPINIFEX_SQS_R3=1 go test $(GOTESTFLAGS) -race -timeout 300s ./spinifex/... ./cmd/... ./internal/... ./contracts/... ./architecture/... $(_RACEQ)
-	$(_Q)LOG_IGNORE=1 go test $(GOTESTFLAGS) -race -tags=lambdatestlink -timeout 120s ./cmd/lambda-agent/ ./spinifex/agents/lambda/hostlink/ $(_RACEQ)
+	$(_Q)LOG_IGNORE=1 go test $(GOTESTFLAGS) -race -tags=lambdatestlink -timeout 120s ./cmd/lambda-agent/ ./spinifex/agents/lambda/hostlink/ ./spinifex/runtime/compute/lambda/testlink/ ./spinifex/domains/network/host/ $(_RACEQ)
+	$(_Q)LOG_IGNORE=1 go test $(GOTESTFLAGS) -race -tags=lambdatestlink -timeout 120s -run '^TestLambdaTestLink(Executor|Reply)_' ./spinifex/runtime/roles/awsgw/ $(_RACEQ)
+	$(_Q)LOG_IGNORE=1 go test $(GOTESTFLAGS) -race -tags=lambdatestlink,lambdatestlinkseam -timeout 120s -run '^TestLambdaTestLinkSeam_' ./spinifex/runtime/roles/awsgw/ $(_RACEQ)
+	$(_Q)LOG_IGNORE=1 go test $(GOTESTFLAGS) -race -tags=lambdatestlink -timeout 120s -run '^TestLambdaTestLink' ./spinifex/runtime/daemon/ $(_RACEQ)
 
 # Unit tests for in-repo GitHub Actions (e.g. .github/actions/e2e-analyze).
 # Kept out of `test-cover` so coverage % isn't diluted by CI-only tooling.
@@ -538,7 +594,7 @@ distro-arm64:
 distro-clean:
 	rm -rf dist/
 
-.PHONY: test-package-check build build-ui test-ui-e2e ui-e2e-container ui-baselines build-installer build-lb-agent build-ecs-agent build-system-image build-eks-node-image import-eks-node-image publish-eks-node-image build-ecs-node-image import-ecs-node-image build-rds-postgres-image import-rds-postgres-image build-rds-mariadb-image import-rds-mariadb-image build-microvm-image build-sqs-worker-microvm-image build-lambda-runtime-microvm-image install-microvm install-sqs-worker-microvm go_build preflight test test-cover test-race diff-coverage bench fuzz test-actions test-images test-build-scripts test-harness test-integration generate-aws-model-coverage aws-model-coverage test-segscan-oracle \
+.PHONY: test-package-check build build-lambda-testlink build-lambda-testlink-image build-ui test-ui-e2e ui-e2e-container ui-baselines build-installer build-lb-agent build-ecs-agent build-system-image build-eks-node-image import-eks-node-image publish-eks-node-image build-ecs-node-image import-ecs-node-image build-rds-postgres-image import-rds-postgres-image build-rds-mariadb-image import-rds-mariadb-image build-microvm-image build-sqs-worker-microvm-image build-lambda-runtime-microvm-image install-microvm install-sqs-worker-microvm go_build preflight test test-cover test-race diff-coverage bench fuzz test-actions test-images test-build-scripts test-harness test-integration generate-aws-model-coverage aws-model-coverage test-segscan-oracle \
 	deploy reinstall clean \
 	install-system install-go install-aws quickinstall \
 	lint fix govulncheck nilaway \

README.md

@@ -70,8 +70,8 @@ The platform serves **405 AWS API operations** across the services below. See ex
 | **RDS** | Databases | PostgreSQL and MariaDB, with automated backups | Available |
 | **Route 53** | DNS | [Northstar](https://github.com/mulgadc/northstar): authoritative DNS with hosted zones | Available |
 | **Bedrock** | AI deployment | vLLM for text generation and Hugging Face TEI for embeddings and reranking | Q4 2026 |
-| **Lambda** | Serverless functions | | Q1 2027 |
-| **SQS** | Message queues | | Q1 2027 |
+| **Lambda** | Serverless functions | QEMU `microvm` execution environments | Q1 2027 |
+| **SQS** | Message queues | A dedicated NATS JetStream store in a per-Region QEMU `microvm` guest | Q1 2027 |
 
 Roadmap services ship under the same AWS API surface, so code written for AWS today works the moment they land. [Track what's shipped in the release notes](https://github.com/mulgadc/spinifex/releases).
 

cmd/lambda-agent/connect.go

@@ -6,6 +6,7 @@ import (
 	"errors"
 	"fmt"
 
+	lambdav1 "github.com/mulgadc/spinifex/contracts/lambda/v1"
 	"github.com/mulgadc/spinifex/spinifex/agents/lambda/hostlink"
 )
 
@@ -29,20 +30,20 @@ func defaultStartup() startup {
 
 // connect loads the identity, seals fw_cfg whether or not the load succeeded,
 // then dials the host. Under TLS 1.3 a host refusal is seen only on first read.
-func (s startup) connect(ctx context.Context) (*tls.Conn, int, error) {
+func (s startup) connect(ctx context.Context) (*tls.Conn, lambdav1.Scope, int, error) {
 	id, loadErr := hostlink.LoadIdentity(s.fwCfgDir)
 	if err := hostlink.SealFwCfg(s.fwCfgRoot, s.unload); err != nil {
-		return nil, exitRefused, errors.Join(loadErr, err)
+		return nil, "", exitRefused, errors.Join(loadErr, err)
 	}
 	if loadErr != nil {
-		return nil, exitRefused, loadErr
+		return nil, "", exitRefused, loadErr
 	}
 	conn, err := hostlink.Dial(ctx, id)
 	if err != nil {
 		if ctx.Err() != nil {
 			err = fmt.Errorf("%w: %w", err, context.Cause(ctx))
 		}
-		return nil, exitLink, err
+		return nil, "", exitLink, err
 	}
-	return conn, 0, nil
+	return conn, id.Scope, 0, nil
 }

cmd/lambda-agent/grant_testlink.go

@@ -0,0 +1,66 @@
+//go:build lambdatestlink
+
+package main
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	lambdav1 "github.com/mulgadc/spinifex/contracts/lambda/v1"
+	"github.com/mulgadc/spinifex/spinifex/agents/lambda/hostlink"
+)
+
+const entryGrant = "test-grant"
+
+// testGrant is the grant the host launched this VM under.
+type testGrant struct {
+	grantID, attemptID, environmentID string
+	generation                        uint64
+}
+
+// readGrant reads the test-grant fw_cfg entry: grant ID, attempt ID,
+// environment ID and generation, one per line.
+func readGrant(fwCfgDir string) (testGrant, error) {
+	b, err := os.ReadFile(filepath.Join(fwCfgDir, entryGrant, "raw"))
+	if err != nil {
+		return testGrant{}, fmt.Errorf("read %s: %w", entryGrant, err)
+	}
+	lines := strings.Split(strings.TrimSuffix(string(b), "\n"), "\n")
+	if len(lines) != 4 {
+		return testGrant{}, errors.New(entryGrant + " entry malformed")
+	}
+	g := testGrant{grantID: lines[0], attemptID: lines[1], environmentID: lines[2]}
+	g.generation, err = strconv.ParseUint(lines[3], 10, 64)
+	if err != nil || g.generation == 0 || g.grantID == "" || g.attemptID == "" || g.environmentID == "" {
+		return testGrant{}, errors.New(entryGrant + " entry malformed")
+	}
+	return g, nil
+}
+
+// checkBinding refuses a run unless the grant names the authenticated environment
+// generation, the request carries that grant and its deadline is still ahead. The
+// clock check is a local guard only: it cannot detect skew or a superseded grant.
+func checkBinding(scope lambdav1.Scope, g testGrant, req hostlink.Request, now time.Time) error {
+	parts := strings.Split(string(scope), "/")
+	if len(parts) != 5 {
+		return errors.New("authenticated scope malformed")
+	}
+	if parts[3] != g.environmentID || parts[4] != strconv.FormatUint(g.generation, 10) {
+		return errors.New("grant is not for the authenticated environment generation")
+	}
+	if req.GrantID != g.grantID || req.AttemptID != g.attemptID {
+		return errors.New("request does not carry this VM's grant")
+	}
+	if req.DeadlineMs <= 0 {
+		return errors.New("request has no deadline")
+	}
+	if !now.Before(time.UnixMilli(req.DeadlineMs)) {
+		return errors.New("request deadline already passed")
+	}
+	return nil
+}

cmd/lambda-agent/helpers_test.go

@@ -14,7 +14,7 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-const scope lambdav1.Scope = "ap-southeast-2/000000000001/fn-1/env-1/gen-1"
+const scope lambdav1.Scope = "ap-southeast-2/000000000001/fn-1/env-1/1"
 
 // guest is a fake fw_cfg tree; unload removes it as unloading the module would.
 type guest struct {

cmd/lambda-agent/package_testlink.go

@@ -18,6 +18,7 @@ import (
 	"strconv"
 	"strings"
 	"time"
+	"unicode"
 
 	"golang.org/x/sys/unix"
 )
@@ -28,6 +29,7 @@ import (
 const (
 	entryPackageSize   = "test-package-size"
 	entryPackageSHA256 = "test-package-sha256"
+	entryHandler       = "test-handler"
 
 	devMaxZipBytes    = 16 << 20
 	devMaxUnzipBytes  = 64 << 20
@@ -37,8 +39,9 @@ const (
 )
 
 type packageSpec struct {
-	size   int64
-	sha256 [sha256.Size]byte
+	size    int64
+	sha256  [sha256.Size]byte
+	handler string
 }
 
 type unpackLimits struct {
@@ -76,6 +79,13 @@ func readPackageSpec(fwCfgDir string) (packageSpec, error) {
 		return spec, errors.New("package sha256 is not 64 hex digits")
 	}
 	copy(spec.sha256[:], b)
+	if spec.handler, err = read(entryHandler); err != nil {
+		return spec, err
+	}
+	if spec.handler == "" || len(spec.handler) > 128 || strings.IndexFunc(spec.handler, unicode.IsSpace) >= 0 ||
+		strings.ContainsRune(spec.handler, 0) {
+		return spec, errors.New("handler must be 1..128 characters with no whitespace")
+	}
 	return spec, nil
 }
 

cmd/lambda-agent/package_testlink_test.go

@@ -12,6 +12,7 @@ import (
 	"os"
 	"path/filepath"
 	"sort"
+	"strings"
 	"syscall"
 	"testing"
 
@@ -165,19 +166,23 @@ func TestUnpackChecksSizeAndHash(t *testing.T) {
 func TestReadPackageSpecBounds(t *testing.T) {
 	sum := "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
 	cases := map[string]struct {
-		size, hash string
-		want       string
+		size, hash, handler string
+		want                string
 	}{
-		"valid":     {"10", sum, ""},
-		"zero":      {"0", sum, "outside"},
-		"too large": {"16777217", sum, "outside"},
-		"not hex":   {"10", "zz", "64 hex digits"},
-		"short":     {"10", sum[:62], "64 hex digits"},
+		"valid":            {"10", sum, "bootstrap.h", ""},
+		"zero":             {"0", sum, "bootstrap.h", "outside"},
+		"too large":        {"16777217", sum, "bootstrap.h", "outside"},
+		"not hex":          {"10", "zz", "bootstrap.h", "64 hex digits"},
+		"short":            {"10", sum[:62], "bootstrap.h", "64 hex digits"},
+		"empty handler":    {"10", sum, "", "handler"},
+		"handler space":    {"10", sum, "a b", "handler"},
+		"128-char handler": {"10", sum, strings.Repeat("h", 128), ""},
+		"129-char handler": {"10", sum, strings.Repeat("h", 129), "handler"},
 	}
 	for name, tc := range cases {
 		t.Run(name, func(t *testing.T) {
 			dir := t.TempDir()
-			for n, v := range map[string]string{entryPackageSize: tc.size, entryPackageSHA256: tc.hash} {
+			for n, v := range map[string]string{entryPackageSize: tc.size, entryPackageSHA256: tc.hash, entryHandler: tc.handler} {
 				require.NoError(t, os.MkdirAll(filepath.Join(dir, n), 0o700))
 				require.NoError(t, os.WriteFile(filepath.Join(dir, n, "raw"), []byte(v), 0o600))
 			}
@@ -185,6 +190,7 @@ func TestReadPackageSpecBounds(t *testing.T) {
 			if tc.want == "" {
 				require.NoError(t, err)
 				assert.Equal(t, int64(10), spec.size)
+				assert.Equal(t, tc.handler, spec.handler)
 				return
 			}
 			assert.ErrorContains(t, err, tc.want)

cmd/lambda-agent/start_tcp.go

@@ -25,7 +25,7 @@ func start(ctx context.Context) int {
 
 // run authenticates to the host and holds the connection until it closes.
 func (s startup) run(ctx context.Context) (int, error) {
-	conn, code, err := s.connect(ctx)
+	conn, _, code, err := s.connect(ctx)
 	if err != nil {
 		return code, err
 	}

cmd/lambda-agent/start_testlink.go

@@ -5,8 +5,8 @@ package main
 import (
 	"context"
 	"errors"
-	"flag"
 	"fmt"
+	"io"
 	"log/slog"
 	"net"
 	"net/http"
@@ -24,8 +24,6 @@ const (
 	taskRoot    = "/var/task"
 )
 
-var handler = flag.String("handler", os.Getenv("_HANDLER"), "function handler passed to the bootstrap")
-
 // testlink relays one invocation over the test carrier on the authenticated
 // connection; the carrier is not the guest protocol.
 type testlink struct {
@@ -54,13 +52,14 @@ func start(ctx context.Context) int {
 func (t testlink) run(parent context.Context) (int, error) {
 	// The package values are fw_cfg entries, so read them before connect seals it.
 	spec, specErr := readPackageSpec(t.fwCfgDir)
-	conn, code, err := t.connect(parent)
+	grant, grantErr := readGrant(t.fwCfgDir)
+	conn, scope, code, err := t.connect(parent)
 	if err != nil {
-		return code, errors.Join(err, specErr)
+		return code, errors.Join(err, specErr, grantErr)
 	}
 	defer conn.Close()
-	if specErr != nil {
-		return exitRefused, specErr
+	if err := errors.Join(specErr, grantErr); err != nil {
+		return exitRefused, err
 	}
 	link := hostlink.NewTestStream(conn)
 
@@ -76,6 +75,10 @@ func (t testlink) run(parent context.Context) (int, error) {
 	if parent.Err() != nil {
 		return exitLink, context.Cause(parent)
 	}
+	// Nothing of the tenant's is installed or run for an unbound request.
+	if err := checkBinding(scope, grant, first, time.Now()); err != nil {
+		return exitRefused, err
+	}
 	if err := t.pkg.install(spec); err != nil {
 		return exitRefused, fmt.Errorf("install package: %w", err)
 	}
@@ -93,7 +96,7 @@ func (t testlink) run(parent context.Context) (int, error) {
 	defer cancel(nil)
 	cmd, err := t.startBootstrap(ctx, []string{
 		"AWS_LAMBDA_RUNTIME_API=" + ln.Addr().String(),
-		"_HANDLER=" + *handler,
+		"_HANDLER=" + spec.handler,
 		"LAMBDA_TASK_ROOT=" + taskRoot,
 		"PATH=/bin:/sbin:/usr/bin",
 	})
@@ -104,7 +107,11 @@ func (t testlink) run(parent context.Context) (int, error) {
 	go func() {
 		defer close(exited)
 		err := cmd.Wait()
-		cancel(fmt.Errorf("bootstrap exited: %w", err))
+		// Once a response is being received the result stands, so only an
+		// exit before that cancels the invocation.
+		if srv.BootstrapExited() {
+			cancel(fmt.Errorf("bootstrap exited: %w", err))
+		}
 	}()
 
 	err = agent.Run(ctx, &oneInvocation{Link: link, first: &first}, srv)
@@ -116,11 +123,18 @@ func (t testlink) run(parent context.Context) (int, error) {
 	return exitClosed, nil
 }
 
+// shutdownGrace is how long past the invocation deadline the agent waits for
+// the host's shutdown frame once its result is written.
+const shutdownGrace = 2 * time.Second
+
 // oneInvocation serves the host's first request and then stops the agent:
-// each test VM runs a single invocation.
+// each test VM runs a single invocation. After the result is written it waits
+// for the host's shutdown frame or EOF, so the result is not cut off by the
+// poweroff that follows the agent's exit.
 type oneInvocation struct {
 	hostlink.Link
-	first *hostlink.Request
+	first      *hostlink.Request
+	deadlineMs int64
 }
 
 var _ hostlink.Link = (*oneInvocation)(nil)
@@ -129,10 +143,36 @@ func (o *oneInvocation) Next(ctx context.Context) (hostlink.Request, error) {
 	if err := ctx.Err(); err != nil {
 		return hostlink.Request{}, err
 	}
-	if o.first == nil {
-		return hostlink.Request{}, hostlink.ErrShutdown
+	if o.first != nil {
+		req := *o.first
+		o.first = nil
+		o.deadlineMs = req.DeadlineMs
+		return req, nil
 	}
-	req := *o.first
-	o.first = nil
-	return req, nil
+	return hostlink.Request{}, o.awaitShutdown(ctx)
+}
+
+// awaitShutdown reads the host's next frame and always ends the agent: with
+// ErrShutdown for a shutdown frame, EOF, a stray frame or an expired wait.
+func (o *oneInvocation) awaitShutdown(ctx context.Context) error {
+	end := time.UnixMilli(o.deadlineMs)
+	if now := time.Now(); end.Before(now) {
+		end = now
+	}
+	wctx, cancel := context.WithDeadline(ctx, end.Add(shutdownGrace))
+	defer cancel()
+	_, err := o.Link.Next(wctx)
+	switch {
+	case errors.Is(err, hostlink.ErrShutdown), errors.Is(err, io.EOF):
+		return hostlink.ErrShutdown
+	case err == nil:
+		slog.Warn("lambda-agent: frame after the invocation was not dispatched")
+		return hostlink.ErrShutdown
+	case ctx.Err() != nil:
+		return err
+	case wctx.Err() != nil:
+		slog.Warn("lambda-agent: no shutdown from the host; exiting")
+		return hostlink.ErrShutdown
+	}
+	return err
 }

cmd/lambda-agent/start_testlink_test.go

@@ -25,12 +25,18 @@ import (
 
 const helperEnv = "LAMBDA_AGENT_TEST_BOOTSTRAP"
 
+// helperHandlerOut names the file the helper bootstrap writes its _HANDLER to.
+const helperHandlerOut = "LAMBDA_AGENT_TEST_HANDLER_OUT"
+
 // TestHelperBootstrap is the fake function bootstrap, run as a subprocess: it
 // echoes one invocation through the Runtime API, then waits for the next.
 func TestHelperBootstrap(t *testing.T) {
 	if os.Getenv(helperEnv) != "1" {
 		return
 	}
+	if out := os.Getenv(helperHandlerOut); out != "" {
+		require.NoError(t, os.WriteFile(out, []byte(os.Getenv("_HANDLER")), 0o600))
+	}
 	base := "http://" + os.Getenv("AWS_LAMBDA_RUNTIME_API") + "/2018-06-01/runtime/invocation/"
 	resp, err := http.Get(base + "next")
 	require.NoError(t, err)
@@ -41,14 +47,28 @@ func TestHelperBootstrap(t *testing.T) {
 	post, err := http.Post(base+id+"/response", "application/json", bytes.NewReader(body))
 	require.NoError(t, err)
 	post.Body.Close()
+	if os.Getenv(helperExitAfterPost) == "1" {
+		return
+	}
 	_, _ = http.Get(base + "next")
 }
 
+// helperExitAfterPost makes the helper bootstrap exit once its response is posted.
+const helperExitAfterPost = "LAMBDA_AGENT_TEST_EXIT_AFTER_POST"
+
+// testGrantEntry grants g-1 for attempt a-1 on the fixture scope's env-1/1.
+const testGrantEntry = "g-1\na-1\nenv-1\n1\n"
+
+// testHandler is the handler the fixture's host configures.
+const testHandler = "bootstrap.fixture"
+
 type bootstrapStarts struct {
 	n       int
 	started chan struct{}
 	task    string
 	sealed  bool
+	// handlerOut receives the _HANDLER the bootstrap process itself saw.
+	handlerOut string
 }
 
 // testlink builds a guest whose fw_cfg also carries a controlled package,
@@ -61,9 +81,16 @@ func (b *bootstrapStarts) testlink(t *testing.T, entries map[string][]byte) test
 	sum := sha256.Sum256(zipBytes)
 	entries[entryPackageSize] = []byte(strconv.Itoa(len(zipBytes)))
 	entries[entryPackageSHA256] = []byte(hex.EncodeToString(sum[:]))
+	if _, ok := entries[entryHandler]; !ok {
+		entries[entryHandler] = []byte(testHandler)
+	}
+	if _, ok := entries[entryGrant]; !ok {
+		entries[entryGrant] = []byte(testGrantEntry)
+	}
 	g := newGuest(t, entries)
 	b.started = make(chan struct{}, 1)
 	b.task = t.TempDir()
+	b.handlerOut = filepath.Join(t.TempDir(), "handler")
 	return testlink{
 		startup: g.startup(),
 		pkg: taskPackage{
@@ -77,7 +104,7 @@ func (b *bootstrapStarts) testlink(t *testing.T, entries map[string][]byte) test
 			b.n++
 			b.started <- struct{}{}
 			cmd := exec.CommandContext(ctx, os.Args[0], "-test.run=^TestHelperBootstrap$")
-			cmd.Env = append(env, helperEnv+"=1")
+			cmd.Env = append(env, helperEnv+"=1", helperHandlerOut+"="+b.handlerOut)
 			return cmd, cmd.Start()
 		},
 	}
@@ -132,10 +159,105 @@ func TestTestlinkServesOneInvocationThenStops(t *testing.T) {
 		assert.Error(t, err, "agent answered a second invocation")
 	}
 	assert.Equal(t, 1, b.n)
+	seen, err := os.ReadFile(b.handlerOut)
+	require.NoError(t, err, "bootstrap process did not report its handler")
+	assert.Equal(t, testHandler, string(seen), "bootstrap process not given the configured handler")
 	assert.True(t, b.sealed, "task dir not made read-only")
 	assert.FileExists(t, filepath.Join(b.task, "lib", "data.txt"))
 }
 
+// A bootstrap that posts its response and exits at once does not cost the
+// host the result; the agent then waits for the host's shutdown.
+func TestTestlinkBootstrapExitingAfterResponseStillDelivers(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	h := newHost(t)
+	h.accept(ctx)
+	var b bootstrapStarts
+	tl := b.testlink(t, h.entries())
+	start := tl.startBootstrap
+	tl.startBootstrap = func(ctx context.Context, env []string) (*exec.Cmd, error) {
+		return start(ctx, append(env, helperExitAfterPost+"=1"))
+	}
+	done := runTestlinkAsync(ctx, tl)
+
+	conn := h.guest(t)
+	defer conn.Close()
+	hs := hostlink.NewTestStream(conn)
+	payload := bytes.Repeat([]byte("0123456789"), 300_000)
+	req := hostlink.Request{GrantID: "g-1", AttemptID: "a-1", RequestID: "r-1", DeadlineMs: time.Now().Add(5 * time.Second).UnixMilli(), Payload: payload}
+	require.NoError(t, hs.HostSend(req))
+	got, err := hs.HostResult(ctx)
+	require.NoError(t, err)
+	assert.Equal(t, hostlink.Response{GrantID: "g-1", AttemptID: "a-1", RequestID: "r-1", Payload: payload}, got)
+
+	require.NoError(t, hs.HostShutdown())
+	res := wait(t, done, "agent to stop after the host's shutdown")
+	assert.Equal(t, exitClosed, res.code)
+	assert.NoError(t, res.err)
+}
+
+// The agent stays up for the host's shutdown rather than exiting as soon as
+// its result is written, and never dispatches a stray frame.
+func TestOneInvocationAfterResult(t *testing.T) {
+	first := hostlink.Request{RequestID: "r-1", DeadlineMs: time.Now().Add(time.Minute).UnixMilli()}
+	cases := map[string]struct {
+		next func(context.Context) (hostlink.Request, error)
+		want error
+	}{
+		"shutdown frame": {func(context.Context) (hostlink.Request, error) { return hostlink.Request{}, hostlink.ErrShutdown }, hostlink.ErrShutdown},
+		"eof":            {func(context.Context) (hostlink.Request, error) { return hostlink.Request{}, io.EOF }, hostlink.ErrShutdown},
+		"a second request is not dispatched": {func(context.Context) (hostlink.Request, error) {
+			return hostlink.Request{RequestID: "r-2"}, nil
+		}, hostlink.ErrShutdown},
+	}
+	for name, tc := range cases {
+		t.Run(name, func(t *testing.T) {
+			o := &oneInvocation{Link: stubLink{tc.next}, first: &first}
+			_, err := o.Next(context.Background())
+			require.NoError(t, err)
+			req, err := o.Next(context.Background())
+			require.ErrorIs(t, err, tc.want)
+			assert.Empty(t, req.RequestID)
+		})
+	}
+	t.Run("host never sends shutdown", func(t *testing.T) {
+		past := first
+		past.DeadlineMs = time.Now().Add(-time.Second).UnixMilli()
+		o := &oneInvocation{Link: stubLink{func(ctx context.Context) (hostlink.Request, error) {
+			<-ctx.Done()
+			return hostlink.Request{}, ctx.Err()
+		}}, first: &past}
+		_, err := o.Next(context.Background())
+		require.NoError(t, err)
+		start := time.Now()
+		_, err = o.Next(context.Background())
+		require.ErrorIs(t, err, hostlink.ErrShutdown)
+		assert.GreaterOrEqual(t, time.Since(start), shutdownGrace-100*time.Millisecond, "waited the grace")
+	})
+	t.Run("parent cancel is not a shutdown", func(t *testing.T) {
+		o := &oneInvocation{Link: stubLink{func(ctx context.Context) (hostlink.Request, error) {
+			<-ctx.Done()
+			return hostlink.Request{}, ctx.Err()
+		}}, first: &first}
+		_, _ = o.Next(context.Background())
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel()
+		_, err := o.Next(ctx)
+		require.ErrorIs(t, err, context.Canceled)
+	})
+}
+
+type stubLink struct {
+	next func(context.Context) (hostlink.Request, error)
+}
+
+var _ hostlink.Link = stubLink{}
+
+func (l stubLink) Next(ctx context.Context) (hostlink.Request, error) { return l.next(ctx) }
+
+func (stubLink) Complete(context.Context, hostlink.Response) error { return nil }
+
 func TestTestlinkShutdownBeforeInvocationNeverStartsBootstrap(t *testing.T) {
 	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 	defer cancel()
@@ -218,7 +340,8 @@ func TestTestlinkBadPackageNeverStartsBootstrap(t *testing.T) {
 
 	conn := h.guest(t)
 	defer conn.Close()
-	require.NoError(t, hostlink.NewTestStream(conn).HostSend(hostlink.Request{RequestID: "r-1"}))
+	require.NoError(t, hostlink.NewTestStream(conn).HostSend(hostlink.Request{GrantID: "g-1", AttemptID: "a-1", RequestID: "r-1",
+		DeadlineMs: time.Now().Add(5 * time.Second).UnixMilli()}))
 	res := wait(t, done, "agent to stop")
 	assert.Equal(t, exitRefused, res.code)
 	assert.ErrorContains(t, res.err, "install package")
@@ -244,3 +367,87 @@ func TestTestlinkMissingPackageSpecRefuses(t *testing.T) {
 	_, err := os.Stat(tl.fwCfgRoot)
 	assert.ErrorIs(t, err, os.ErrNotExist, "fw_cfg not sealed")
 }
+
+// A request that does not carry this VM's grant, or a grant for another
+// environment generation than the one authenticated, installs and runs
+// nothing of the tenant's.
+func TestTestlinkUnboundRequestNeverStartsBootstrap(t *testing.T) {
+	cases := map[string]struct {
+		grant            string
+		grantID, attempt string
+		deadlineMs       int64
+		want             string
+	}{
+		"frame with no deadline":      {testGrantEntry, "g-1", "a-1", -1, "no deadline"},
+		"frame with expired deadline": {testGrantEntry, "g-1", "a-1", time.Now().Add(-time.Second).UnixMilli(), "deadline already passed"},
+		"frame for another grant":     {testGrantEntry, "g-2", "a-1", 0, "does not carry this VM's grant"},
+		"frame for another attempt":   {testGrantEntry, "g-1", "a-2", 0, "does not carry this VM's grant"},
+		"frame with no grant":         {testGrantEntry, "", "", 0, "does not carry this VM's grant"},
+		"grant for another env":       {"g-1\na-1\nenv-2\n1\n", "g-1", "a-1", 0, "not for the authenticated environment"},
+		"grant for another gen":       {"g-1\na-1\nenv-1\n2\n", "g-1", "a-1", 0, "not for the authenticated environment"},
+	}
+	for name, tc := range cases {
+		t.Run(name, func(t *testing.T) {
+			ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+			defer cancel()
+			h := newHost(t)
+			h.accept(ctx)
+			var b bootstrapStarts
+			entries := h.entries()
+			entries[entryGrant] = []byte(tc.grant)
+			done := runTestlinkAsync(ctx, b.testlink(t, entries))
+			conn := h.guest(t)
+			defer conn.Close()
+			deadline := time.Now().Add(5 * time.Second).UnixMilli()
+			switch {
+			case tc.deadlineMs < 0:
+				deadline = 0
+			case tc.deadlineMs > 0:
+				deadline = tc.deadlineMs
+			}
+			req := hostlink.Request{GrantID: tc.grantID, AttemptID: tc.attempt, RequestID: "r-1",
+				DeadlineMs: deadline, Payload: []byte(`{}`)}
+			require.NoError(t, hostlink.NewTestStream(conn).HostSend(req))
+
+			res := wait(t, done, "agent to stop")
+			assert.Equal(t, exitRefused, res.code)
+			assert.ErrorContains(t, res.err, tc.want)
+			assert.Zero(t, b.n)
+			assert.False(t, b.sealed)
+			assert.NoFileExists(t, filepath.Join(b.task, "bootstrap"), "package installed")
+		})
+	}
+}
+
+// A missing or malformed grant entry refuses before any frame is awaited.
+func TestTestlinkBadGrantEntryRefuses(t *testing.T) {
+	cases := map[string]*string{
+		"missing":       nil,
+		"too few lines": ptr("g-1\na-1\nenv-1\n"),
+		"generation 0":  ptr("g-1\na-1\nenv-1\n0\n"),
+		"empty grant":   ptr("\na-1\nenv-1\n1\n"),
+	}
+	for name, grant := range cases {
+		t.Run(name, func(t *testing.T) {
+			ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+			defer cancel()
+			h := newHost(t)
+			h.accept(ctx)
+			var b bootstrapStarts
+			entries := h.entries()
+			if grant != nil {
+				entries[entryGrant] = []byte(*grant)
+			}
+			tl := b.testlink(t, entries)
+			if grant == nil {
+				require.NoError(t, os.RemoveAll(filepath.Join(tl.fwCfgDir, entryGrant)))
+			}
+			res := wait(t, runTestlinkAsync(ctx, tl), "agent to stop")
+			assert.Equal(t, exitRefused, res.code)
+			assert.ErrorContains(t, res.err, entryGrant)
+			assert.Zero(t, b.n)
+		})
+	}
+}
+
+func ptr(s string) *string { return &s }

cmd/lambda-image-agent-tag/main.go

@@ -0,0 +1,221 @@
+// Command lambda-image-agent-tag checks whether the lambda-agent archived in a
+// built Lambda guest initramfs carries the lambdatestlink build tag. Build
+// information is recorded by the build; it is not proof of how the agent behaves.
+package main
+
+import (
+	"bufio"
+	"bytes"
+	"compress/gzip"
+	"debug/buildinfo"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"slices"
+	"strconv"
+	"strings"
+)
+
+const (
+	agentPath    = "usr/local/bin/lambda-agent"
+	maxArchive   = 1 << 30
+	maxAgent     = 256 << 20
+	maxName      = 4096
+	newcHeader   = 110
+	trailerName  = "TRAILER!!!"
+	modeTypeMask = 0o170000
+	modeDir      = 0o040000
+	modeRegular  = 0o100000
+)
+
+var agentParents = []string{"usr", "usr/local", "usr/local/bin"}
+
+func main() {
+	if len(os.Args) != 3 || (os.Args[2] != "present" && os.Args[2] != "absent") {
+		fmt.Fprintln(os.Stderr, "usage: lambda-image-agent-tag <initramfs.cpio.gz> present|absent")
+		os.Exit(2)
+	}
+	if err := run(os.Args[1], os.Args[2] == "present"); err != nil {
+		fmt.Fprintf(os.Stderr, "%s: %v\n", os.Args[1], err)
+		os.Exit(1)
+	}
+}
+
+func run(path string, want bool) error {
+	fi, err := os.Lstat(path)
+	if err != nil {
+		return err
+	}
+	if !fi.Mode().IsRegular() {
+		return errors.New("not a regular file")
+	}
+	f, err := os.Open(path)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	agent, err := archivedAgent(f)
+	if err != nil {
+		return err
+	}
+	return checkTag(agent, want)
+}
+
+// archivedAgent returns the single agent entry after checking listed names,
+// entry types, the agent's link count and zero-only padding after the trailer.
+// It is not a full kernel-equivalent parser; 070702 CRCs, for one, are unchecked.
+func archivedAgent(r io.Reader) ([]byte, error) {
+	zr, err := gzip.NewReader(bufio.NewReader(r))
+	if err != nil {
+		return nil, fmt.Errorf("not a readable gzip archive: %w", err)
+	}
+	raw, err := io.ReadAll(io.LimitReader(zr, maxArchive+1))
+	if err != nil {
+		return nil, fmt.Errorf("not a readable gzip archive: %w", err)
+	}
+	if len(raw) > maxArchive {
+		return nil, fmt.Errorf("archive larger than %d bytes", maxArchive)
+	}
+
+	seen := map[string]bool{}
+	var agent []byte
+	off := 0
+	for {
+		e, next, err := parseEntry(raw, off)
+		if err != nil {
+			return nil, fmt.Errorf("entry at offset %d: %w", off, err)
+		}
+		off = next
+		if e.name == trailerName {
+			break
+		}
+		if !canonical(e.name) {
+			return nil, fmt.Errorf("entry name %q is not canonical", e.name)
+		}
+		if seen[e.name] {
+			return nil, fmt.Errorf("entry %q appears more than once", e.name)
+		}
+		seen[e.name] = true
+		for _, p := range agentParents {
+			if e.name == p && e.mode&modeTypeMask != modeDir {
+				return nil, fmt.Errorf("%s is not a directory", p)
+			}
+		}
+		if e.name == agentPath {
+			for _, p := range agentParents {
+				if !seen[p] {
+					return nil, fmt.Errorf("%s has no %s directory entry before it", agentPath, p)
+				}
+			}
+			if e.mode&modeTypeMask != modeRegular {
+				return nil, fmt.Errorf("%s is not a regular file", agentPath)
+			}
+			if e.nlink != 1 {
+				return nil, fmt.Errorf("%s has %d links, want 1", agentPath, e.nlink)
+			}
+			if len(e.data) > maxAgent {
+				return nil, fmt.Errorf("%s is larger than %d bytes", agentPath, maxAgent)
+			}
+			agent = e.data
+		}
+	}
+	if i := bytes.IndexFunc(raw[off:], func(r rune) bool { return r != 0 }); i >= 0 {
+		return nil, fmt.Errorf("data after the archive trailer at offset %d", off+i)
+	}
+	if agent == nil {
+		return nil, fmt.Errorf("no %s entry", agentPath)
+	}
+	return agent, nil
+}
+
+type entry struct {
+	name  string
+	mode  uint64
+	nlink uint64
+	data  []byte
+}
+
+func parseEntry(raw []byte, off int) (entry, int, error) {
+	if len(raw)-off < newcHeader {
+		return entry{}, 0, errors.New("truncated header")
+	}
+	h := raw[off : off+newcHeader]
+	if m := string(h[:6]); m != "070701" && m != "070702" {
+		return entry{}, 0, fmt.Errorf("magic %q is not newc", m)
+	}
+	field := func(i int) (uint64, error) {
+		return strconv.ParseUint(string(h[6+8*i:14+8*i]), 16, 32)
+	}
+	mode, err1 := field(1)
+	nlink, err2 := field(4)
+	size, err3 := field(6)
+	nameSize, err4 := field(11)
+	if err := errors.Join(err1, err2, err3, err4); err != nil {
+		return entry{}, 0, fmt.Errorf("bad header field: %w", err)
+	}
+	if nameSize < 2 || nameSize > maxName {
+		return entry{}, 0, fmt.Errorf("name size %d out of range", nameSize)
+	}
+	nameEnd := off + newcHeader + int(nameSize)
+	dataOff := align4(nameEnd)
+	dataEnd := dataOff + int(size)
+	if dataEnd > len(raw) || align4(dataEnd) > len(raw) {
+		return entry{}, 0, errors.New("truncated entry")
+	}
+	name := raw[off+newcHeader : nameEnd]
+	if name[len(name)-1] != 0 || bytes.IndexByte(name[:len(name)-1], 0) >= 0 {
+		return entry{}, 0, errors.New("name is not one NUL-terminated string")
+	}
+	return entry{name: string(name[:len(name)-1]), mode: mode, nlink: nlink, data: raw[dataOff:dataEnd]}, align4(dataEnd), nil
+}
+
+func align4(n int) int { return (n + 3) &^ 3 }
+
+// canonical accepts "." and relative names with no empty, "." or ".." component.
+func canonical(name string) bool {
+	if name == "." {
+		return true
+	}
+	if name == "" || strings.HasPrefix(name, "/") {
+		return false
+	}
+	for c := range strings.SplitSeq(name, "/") {
+		if c == "" || c == "." || c == ".." {
+			return false
+		}
+	}
+	return true
+}
+
+func checkTag(agent []byte, want bool) error {
+	info, err := buildinfo.Read(bytes.NewReader(agent))
+	if err != nil {
+		return fmt.Errorf("no Go build information in %s: %w", agentPath, err)
+	}
+	return decide(info, want)
+}
+
+// decide refuses build information with no recorded settings, since their
+// absence does not show the tag was absent.
+func decide(info *buildinfo.BuildInfo, want bool) error {
+	if len(info.Settings) == 0 {
+		return fmt.Errorf("%s records no build settings", agentPath)
+	}
+	if hasTag(info, "lambdatestlink") != want {
+		return fmt.Errorf("%s: lambdatestlink build tag present=%v, want %v", agentPath, !want, want)
+	}
+	return nil
+}
+
+func hasTag(info *buildinfo.BuildInfo, tag string) bool {
+	for _, s := range info.Settings {
+		if s.Key != "-tags" {
+			continue
+		}
+		if slices.Contains(strings.Split(s.Value, ","), tag) {
+			return true
+		}
+	}
+	return false
+}

cmd/lambda-image-agent-tag/main_test.go

@@ -0,0 +1,154 @@
+package main
+
+import (
+	"bytes"
+	"compress/gzip"
+	"debug/buildinfo"
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime/debug"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+type fileEntry struct {
+	name  string
+	mode  uint32
+	nlink uint32
+	data  string
+}
+
+func dir(name string) fileEntry { return fileEntry{name: name, mode: modeDir | 0o755, nlink: 2} }
+func file(name, data string) fileEntry {
+	return fileEntry{name: name, mode: modeRegular | 0o755, nlink: 1, data: data}
+}
+func symlink(name, target string) fileEntry {
+	return fileEntry{name: name, mode: 0o120777, nlink: 1, data: target}
+}
+
+// newc writes entries and a trailer in the format the kernel unpacks.
+func newc(entries ...fileEntry) []byte {
+	var b bytes.Buffer
+	for i, e := range append(entries, fileEntry{name: trailerName, nlink: 1}) {
+		fmt.Fprintf(&b, "070701%08X%08X%08X%08X%08X%08X%08X%08X%08X%08X%08X%08X%08X",
+			i+1, e.mode, 0, 0, e.nlink, 0, len(e.data), 0, 0, 0, 0, len(e.name)+1, 0)
+		b.WriteString(e.name)
+		b.WriteByte(0)
+		pad(&b)
+		b.WriteString(e.data)
+		pad(&b)
+	}
+	return b.Bytes()
+}
+
+func pad(b *bytes.Buffer) {
+	for b.Len()%4 != 0 {
+		b.WriteByte(0)
+	}
+}
+
+func gz(parts ...[]byte) []byte {
+	var b bytes.Buffer
+	for _, p := range parts {
+		w := gzip.NewWriter(&b)
+		_, _ = w.Write(p)
+		_ = w.Close()
+	}
+	return b.Bytes()
+}
+
+func withAgent(agent fileEntry) []byte {
+	return newc(dir("."), dir("usr"), dir("usr/local"), dir("usr/local/bin"), agent, file("init", "#!/bin/sh"))
+}
+
+func TestArchivedAgent_ReturnsTheOneArchivedAgent(t *testing.T) {
+	got, err := archivedAgent(bytes.NewReader(gz(withAgent(file(agentPath, "agent-bytes")))))
+	require.NoError(t, err)
+	require.Equal(t, "agent-bytes", string(got))
+
+	padded := append(withAgent(file(agentPath, "agent-bytes")), make([]byte, 1024)...)
+	got, err = archivedAgent(bytes.NewReader(gz(padded)))
+	require.NoError(t, err, "zero padding after the trailer")
+	require.Equal(t, "agent-bytes", string(got))
+}
+
+func TestArchivedAgent_Refuses(t *testing.T) {
+	parents := []fileEntry{dir("."), dir("usr"), dir("usr/local"), dir("usr/local/bin")}
+	agent := file(agentPath, "untagged")
+	small := newc(append(parents, agent)...)
+	second := newc(append(parents[1:], file(agentPath, "tagged"))...)
+	// The second archive starts inside what would be the first one's final block.
+	sameBlock := append(append([]byte{}, small...), second...)
+	for len(sameBlock)%512 != 0 {
+		sameBlock = append(sameBlock, 0)
+	}
+
+	for name, archive := range map[string][]byte{
+		"aliased duplicate":            gz(newc(append(parents, agent, file("././"+agentPath, "tagged"))...)),
+		"leading slash alias":          gz(newc(append(parents, agent, file("/"+agentPath, "tagged"))...)),
+		"dot-dot component":            gz(newc(append(parents, agent, file("usr/local/../local/bin/lambda-agent", "x"))...)),
+		"empty component":              gz(newc(append(parents, agent, file("usr//local/bin/lambda-agent", "x"))...)),
+		"exact duplicate":              gz(newc(append(parents, agent, file(agentPath, "tagged"))...)),
+		"duplicate directory":          gz(newc(dir("usr"), dir("usr"), dir("usr/local"), dir("usr/local/bin"), agent)),
+		"missing directory entry":      gz(newc(dir("usr"), dir("usr/local/bin"), agent)),
+		"directory after the agent":    gz(newc(dir("usr"), dir("usr/local"), agent, dir("usr/local/bin"))),
+		"parent is a symlink":          gz(newc(dir("usr"), dir("usr/local"), symlink("usr/local/bin", "elsewhere"), agent)),
+		"agent is a symlink":           gz(newc(append(parents, symlink(agentPath, "/bin/sh"))...)),
+		"hard-linked agent":            gz(newc(append(parents, fileEntry{name: agentPath, mode: modeRegular | 0o755, nlink: 2, data: "x"})...)),
+		"no agent":                     gz(newc(parents...)),
+		"second archive appended":      gz(small, second),
+		"second archive in same block": gz(sameBlock),
+		"non-zero byte after trailer":  gz(append(append([]byte{}, small...), 0, 0, 1)),
+		"truncated archive":            gz(small[:len(small)-20]),
+		"not newc":                     gz([]byte("not cpio at all, but long enough to fill one newc header: " + string(make([]byte, 120)))),
+		"not gzip":                     small,
+	} {
+		t.Run(name, func(t *testing.T) {
+			_, err := archivedAgent(bytes.NewReader(archive))
+			require.Error(t, err)
+		})
+	}
+}
+
+func TestRun_RefusesASymlinkedImagePath(t *testing.T) {
+	d := t.TempDir()
+	img := filepath.Join(d, "initramfs.cpio.gz")
+	require.NoError(t, os.WriteFile(img, gz(withAgent(file(agentPath, "x"))), 0o644))
+	require.NoError(t, os.Symlink(img, filepath.Join(d, "link")))
+	require.ErrorContains(t, run(filepath.Join(d, "link"), false), "not a regular file")
+}
+
+func TestHasTag_MatchesWholeTagsOnly(t *testing.T) {
+	info := func(tags string) *buildinfo.BuildInfo {
+		return &buildinfo.BuildInfo{Settings: []debug.BuildSetting{{Key: "-buildmode", Value: "exe"}, {Key: "-tags", Value: tags}}}
+	}
+	require.True(t, hasTag(info("lambdatestlink,fips140v1.0"), "lambdatestlink"))
+	require.False(t, hasTag(info("fips140v1.0"), "lambdatestlink"))
+	require.False(t, hasTag(info("lambdatestlinkx,xlambdatestlink"), "lambdatestlink"))
+	require.False(t, hasTag(&buildinfo.BuildInfo{}, "lambdatestlink"))
+}
+
+// The test binary carries real build information, so checkTag reads it and
+// refuses the opposite answer; bytes with no build information are refused.
+func TestCheckTag_ReadsRealBuildInformation(t *testing.T) {
+	exe, err := os.Executable()
+	require.NoError(t, err)
+	raw, err := os.ReadFile(exe)
+	require.NoError(t, err)
+	info, err := buildinfo.Read(bytes.NewReader(raw))
+	require.NoError(t, err)
+	tagged := hasTag(info, "lambdatestlink")
+	require.NoError(t, checkTag(raw, tagged))
+	require.Error(t, checkTag(raw, !tagged))
+	require.Error(t, checkTag([]byte("not a Go binary"), false))
+}
+
+func TestDecide_RefusesMissingBuildSettings(t *testing.T) {
+	require.ErrorContains(t, decide(&buildinfo.BuildInfo{}, false), "no build settings")
+	require.ErrorContains(t, decide(&buildinfo.BuildInfo{}, true), "no build settings")
+	untagged := &buildinfo.BuildInfo{Settings: []debug.BuildSetting{{Key: "-buildmode", Value: "exe"}}}
+	require.NoError(t, decide(untagged, false))
+	require.Error(t, decide(untagged, true))
+}

cmd/lambda-image-digest/main.go

@@ -0,0 +1,26 @@
+//go:build lambdatestlink
+
+// Command lambda-image-digest prints the test-link runtime image digest of one
+// directory, selecting the boot files the same way the daemon does. The digest
+// identifies the bytes; it does not authenticate where they came from.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/mulgadc/spinifex/spinifex/runtime/compute/lambda/testlink"
+)
+
+func main() {
+	if len(os.Args) != 2 {
+		fmt.Fprintln(os.Stderr, "usage: lambda-image-digest <image-dir>")
+		os.Exit(2)
+	}
+	digest, err := testlink.DirDigest(os.Args[1])
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	fmt.Println(digest)
+}

contracts/cluster/v1/facts.go

@@ -56,6 +56,8 @@ type NodeFacts struct {
 	Memory      MemoryFacts       `json:"memory"`
 	NICs        []NICFacts        `json:"nics"`
 	Planes      []PlaneFacts      `json:"planes"`
+	Disks       []DiskFacts       `json:"disks,omitempty"`
+	Filesystems []FilesystemFacts `json:"filesystems,omitempty"`
 	Sources     map[string]string `json:"sources"`
 }
 
@@ -134,6 +136,42 @@ type MemoryGroup struct {
 	Serials       []string `json:"serials,omitempty"`
 }
 
+// DiskFacts is one physical drive as sysfs reports it. Transport is nvme, sata,
+// usb or virtio, and empty when the device path names none, as a RAID
+// controller's virtual disk does.
+type DiskFacts struct {
+	Name       string `json:"name"`
+	Path       string `json:"path"`
+	SizeBytes  uint64 `json:"size_bytes"`
+	Model      string `json:"model,omitempty"`
+	Transport  string `json:"transport,omitempty"`
+	Rotational bool   `json:"rotational,omitempty"`
+	Removable  bool   `json:"removable,omitempty"`
+}
+
+// FilesystemFacts is one mounted block-device or ZFS filesystem. BindOf names
+// the directory a bind mount shows; Disk names the drives under it. Error says
+// why Usage is missing or stale.
+type FilesystemFacts struct {
+	Mount  string           `json:"mount"`
+	Source string           `json:"source"`
+	Disk   string           `json:"disk,omitempty"`
+	Type   string           `json:"type"`
+	BindOf string           `json:"bind_of,omitempty"`
+	Usage  *FilesystemUsage `json:"usage,omitempty"`
+	Error  string           `json:"error,omitempty"`
+	// ID identifies the mount on its node, so a filesystem replaced at the
+	// same path is read afresh. Empty for a mount the daemon cannot see.
+	ID string `json:"-"`
+}
+
+// FilesystemUsage is a filesystem's last statfs reading, as df counts it.
+type FilesystemUsage struct {
+	SizeBytes  uint64 `json:"size_bytes"`
+	UsedBytes  uint64 `json:"used_bytes"`
+	AvailBytes uint64 `json:"avail_bytes"`
+}
+
 // NICFacts is one physical network interface and, where LLDP reports it, the
 // switch port it is cabled to.
 type NICFacts struct {

docs/DESIGN.md

@@ -111,7 +111,7 @@ Daemons (`spinifex/runtime/daemon/daemon.go`) subscribe to NATS topics and handl
 When a daemon handles `RunInstances`:
 
 1. **Resource Check**: Validates CPU/memory availability via `ResourceManager`
-2. **Volume Generation**: Creates the boot volume through the EBS provider and, for a UEFI guest, seeds its variable store as an object under `uefi/<instance-id>/` with a store record in `spinifex-uefi-stores` and a pointer on the instance record
+2. **Volume Generation**: Creates boot and EFI volumes via Viperblock
 3. **Volume Mount**: Publishes each volume through the EBS provider contract (`PublishVolume` on `ebs.provider.v1.{node}.mount`), receives its export
 4. **QEMU Launch**: Builds and executes QEMU command with NBD-backed disks
 5. **QMP Monitoring**: Establishes QEMU Machine Protocol connection for VM management

docs/testing/e2e-coverage.md

@@ -110,7 +110,7 @@ Three entry points, in the order they run:
 
 ### `iam` — everything IAM and STS
 
-Policy evaluation against live requests rather than unit-level: a deny applying to the next request without a new credential, resource-scoped grants naming one key pair, `aws:SourceIp` seeing the real client address, assumed-role sessions carrying role policies, and revocation stopping one key alone.
+Policy evaluation against live requests rather than unit-level: a deny applying to the next request without a new credential, resource-scoped grants naming one key pair, a user rename needing `iam:UpdateUser` on both the old and the new name, `aws:SourceIp` seeing the real client address, assumed-role sessions carrying role policies, and revocation stopping one key alone.
 
 ### `cert` — the cluster CA and TLS identity
 

internal/ecsgw/client.go

@@ -7,9 +7,10 @@ package ecsgw
 
 import (
 	"bytes"
-	"context"
+	"crypto/sha256"
 	"crypto/tls"
 	"crypto/x509"
+	"encoding/hex"
 	"fmt"
 	"io"
 	"net/http"
@@ -17,10 +18,8 @@ import (
 	"strings"
 	"time"
 
-	"github.com/aws/aws-sdk-go/aws/credentials"
-	v4 "github.com/aws/aws-sdk-go/aws/signer/v4"
-
 	"github.com/mulgadc/bluebottle/pkg/tlsconfig"
+	"github.com/mulgadc/spinifex/internal/gwsign"
 )
 
 // targetPrefix is the X-Amz-Target service prefix the gateway's ECS dispatch
@@ -28,31 +27,26 @@ import (
 // suffix); this one mirrors the AWS JSON 1.1 convention.
 const targetPrefix = "AmazonEC2ContainerServiceV20141113."
 
-// CredentialsFunc yields the current SigV4 credentials. It is called once per
-// request so a provider backed by IMDS can rotate instance-role creds (and their
-// session token) transparently. Must be safe for concurrent use.
-type CredentialsFunc func(ctx context.Context) (accessKey, secretKey, sessionToken string, err error)
-
 // Client posts SigV4-signed AWS JSON 1.1 requests to the gateway for service
 // "ecs". One client is reused for register/heartbeat/state/poll.
 type Client struct {
 	baseURL    string
-	creds      CredentialsFunc
+	signer     *gwsign.Signer
 	region     string
 	httpClient *http.Client
 }
 
 // New builds a client. caPath optionally pins the gateway TLS CA; empty relies on
-// the system trust store. creds supplies the per-call instance-role credentials.
+// the system trust store. signer supplies the per-call instance-role credentials.
 // region defaults to us-east-1 when empty (SigV4 requires a non-empty region).
 // timeout bounds a single call — callers needing a long-poll pass a larger value
 // than the default register/heartbeat timeout.
-func New(baseURL, caPath string, creds CredentialsFunc, region string, timeout time.Duration) (*Client, error) {
+func New(baseURL, caPath string, signer *gwsign.Signer, region string, timeout time.Duration) (*Client, error) {
 	if baseURL == "" {
 		return nil, fmt.Errorf("ecsgw: baseURL is required")
 	}
-	if creds == nil {
-		return nil, fmt.Errorf("ecsgw: credentials func is required")
+	if signer == nil {
+		return nil, fmt.Errorf("ecsgw: signer is required")
 	}
 	if region == "" {
 		region = "us-east-1"
@@ -79,7 +73,7 @@ func New(baseURL, caPath string, creds CredentialsFunc, region string, timeout t
 
 	return &Client{
 		baseURL: strings.TrimRight(baseURL, "/"),
-		creds:   creds,
+		signer:  signer,
 		region:  region,
 		httpClient: &http.Client{
 			Timeout:   timeout,
@@ -90,7 +84,7 @@ func New(baseURL, caPath string, creds CredentialsFunc, region string, timeout t
 
 // Call SigV4-signs and POSTs body under X-Amz-Target "<prefix><action>" to the
 // gateway root, returning the 2xx response body. Credentials are fetched per call
-// and the v4 signer emits X-Amz-Security-Token for instance-role (temporary)
+// and the signer emits X-Amz-Security-Token for instance-role (temporary)
 // creds, so the gateway's ASIA path verifies them. No retry; callers wrap.
 func (c *Client) Call(action string, body []byte) ([]byte, error) {
 	req, err := http.NewRequest(http.MethodPost, c.baseURL+"/", bytes.NewReader(body))
@@ -100,12 +94,8 @@ func (c *Client) Call(action string, body []byte) ([]byte, error) {
 	req.Header.Set("Content-Type", "application/x-amz-json-1.1")
 	req.Header.Set("X-Amz-Target", targetPrefix+action)
 
-	akid, secret, token, err := c.creds(req.Context())
-	if err != nil {
-		return nil, fmt.Errorf("retrieve credentials: %w", err)
-	}
-	signer := v4.NewSigner(credentials.NewStaticCredentials(akid, secret, token))
-	if _, err := signer.Sign(req, bytes.NewReader(body), "ecs", c.region, time.Now()); err != nil {
+	sum := sha256.Sum256(body)
+	if err := c.signer.Sign(req, hex.EncodeToString(sum[:]), "ecs", c.region); err != nil {
 		return nil, fmt.Errorf("sign request: %w", err)
 	}
 

internal/ecsgw/client_test.go

@@ -1,24 +1,29 @@
 package ecsgw
 
 import (
-	"context"
 	"io"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/aws/aws-sdk-go-v2/credentials"
+	"github.com/mulgadc/bluebottle/pkg/sigv4"
+	"github.com/mulgadc/spinifex/internal/gwsign"
 )
 
-// testCreds returns a fixed temporary credential set (with a session token, as
-// IMDS instance-role creds carry).
-func testCreds(context.Context) (string, string, string, error) {
-	return "ASIATEST", "secret", "session-token-xyz", nil
+const testSecret = "secret"
+
+// testSigner signs with a fixed temporary credential set (with a session token,
+// as IMDS instance-role creds carry).
+func testSigner() *gwsign.Signer {
+	return gwsign.New(credentials.NewStaticCredentialsProvider("ASIATEST", testSecret, "session-token-xyz"))
 }
 
 func newTestClient(t *testing.T, srv *httptest.Server) *Client {
 	t.Helper()
-	c, err := New(srv.URL, "", testCreds, "ap-southeast-2", time.Second)
+	c, err := New(srv.URL, "", testSigner(), "ap-southeast-2", time.Second)
 	if err != nil {
 		t.Fatalf("New: %v", err)
 	}
@@ -30,7 +35,14 @@ func newTestClient(t *testing.T, srv *httptest.Server) *Client {
 // 2xx body.
 func TestClient_CallSignsAndTargets(t *testing.T) {
 	var gotTarget, gotAuth, gotBody, gotToken string
+	var verifyErr error
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// sigv4.Parse reads and hashes the body itself, then restores it.
+		sr, err := sigv4.Parse(r)
+		if err == nil {
+			_, err = sr.Verify(testSecret, "ap-southeast-2", "ecs")
+		}
+		verifyErr = err
 		gotTarget = r.Header.Get("X-Amz-Target")
 		gotAuth = r.Header.Get("Authorization")
 		gotToken = r.Header.Get("X-Amz-Security-Token")
@@ -45,6 +57,9 @@ func TestClient_CallSignsAndTargets(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Call: %v", err)
 	}
+	if verifyErr != nil {
+		t.Fatalf("gateway-side SigV4 verify failed: %v", verifyErr)
+	}
 	if string(out) != `{"ok":true}` {
 		t.Errorf("body = %q", out)
 	}
@@ -78,10 +93,10 @@ func TestClient_CallErrorStatus(t *testing.T) {
 }
 
 func TestNew_Validation(t *testing.T) {
-	if _, err := New("", "", testCreds, "r", 0); err == nil {
+	if _, err := New("", "", testSigner(), "r", 0); err == nil {
 		t.Error("want error for empty baseURL")
 	}
 	if _, err := New("https://gw:9999", "", nil, "r", 0); err == nil {
-		t.Error("want error for nil credentials func")
+		t.Error("want error for nil signer")
 	}
 }

internal/gwsign/signer.go

@@ -23,6 +23,12 @@ type Signer struct {
 	provider aws.CredentialsProvider
 }
 
+// New returns a Signer over provider. Wrap a provider that fetches remotely in
+// aws.NewCredentialsCache, since Sign retrieves on every call.
+func New(provider aws.CredentialsProvider) *Signer {
+	return &Signer{provider: provider}
+}
+
 // NewStatic returns a Signer using fixed long-lived keys (no session token).
 func NewStatic(accessKey, secretKey string) *Signer {
 	return &Signer{provider: credentials.NewStaticCredentialsProvider(accessKey, secretKey, "")}

internal/imdscreds/imdscreds.go

@@ -21,31 +21,18 @@ import (
 	"github.com/aws/aws-sdk-go-v2/feature/ec2/imds"
 )
 
-// Credentials is a resolved instance-role credential set with parsed expiry.
-type Credentials struct {
-	AccessKeyID     string
-	SecretAccessKey string
-	SessionToken    string
-	Expiration      time.Time
-}
-
 // Fetch resolves the instance role then its credentials via the SDK's IMDSv2
 // client and the ec2rolecreds provider. base is the IMDS root, e.g.
 // http://169.254.169.254/latest.
-func Fetch(client *http.Client, base string) (Credentials, error) {
+func Fetch(client *http.Client, base string) (aws.Credentials, error) {
 	creds, err := NewProvider(client, base).Retrieve(context.Background())
 	if err != nil {
-		return Credentials{}, fmt.Errorf("fetch IMDS credentials: %w", err)
+		return aws.Credentials{}, fmt.Errorf("fetch IMDS credentials: %w", err)
 	}
 	if creds.AccessKeyID == "" || creds.SecretAccessKey == "" {
-		return Credentials{}, fmt.Errorf("IMDS credentials missing access/secret key")
+		return aws.Credentials{}, fmt.Errorf("IMDS credentials missing access/secret key")
 	}
-	return Credentials{
-		AccessKeyID:     creds.AccessKeyID,
-		SecretAccessKey: creds.SecretAccessKey,
-		SessionToken:    creds.SessionToken,
-		Expiration:      creds.Expires,
-	}, nil
+	return creds, nil
 }
 
 // NewProvider builds an ec2rolecreds provider against base, an IMDS root URL

internal/imdscreds/imdscreds_test.go

@@ -1,9 +1,11 @@
 package imdscreds
 
 import (
+	"context"
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -60,8 +62,8 @@ func TestFetch_OK(t *testing.T) {
 	if got.AccessKeyID != "AKIATEST" || got.SecretAccessKey != "secrettest" || got.SessionToken != "sessiontoken" {
 		t.Errorf("creds mismatch: %+v", got)
 	}
-	if !got.Expiration.Equal(exp) {
-		t.Errorf("Expiration = %v, want %v", got.Expiration, exp)
+	if !got.Expires.Equal(exp) {
+		t.Errorf("Expires = %v, want %v", got.Expires, exp)
 	}
 }
 
@@ -132,3 +134,46 @@ func TestNewProvider_WithholdsExtendOnFailure(t *testing.T) {
 		t.Error("provider dropped AdjustExpiresBy, which a caller using an ExpiryWindow relies on")
 	}
 }
+
+// Behind aws.CredentialsCache, as the ecs-agent uses it, a refresh that fails
+// against an expired credential must surface as an error rather than hand back
+// the dead key with a pushed-out expiry.
+func TestNewProvider_CachedFailedRefreshErrors(t *testing.T) {
+	var hits atomic.Int32
+	mux := http.NewServeMux()
+	mux.HandleFunc("/latest/api/token", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("X-Aws-Ec2-Metadata-Token-Ttl-Seconds", "21600")
+		_, _ = w.Write([]byte("v2-token"))
+	})
+	mux.HandleFunc("/latest/meta-data/iam/security-credentials/", func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/latest/meta-data/iam/security-credentials/" {
+			_, _ = w.Write([]byte("node-role"))
+			return
+		}
+		if hits.Add(1) > 1 {
+			w.WriteHeader(http.StatusInternalServerError)
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]string{
+			"Code":            "Success",
+			"AccessKeyId":     "AKIA",
+			"SecretAccessKey": "secret",
+			"Expiration":      time.Now().Add(-time.Minute).UTC().Format(time.RFC3339),
+		})
+	})
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+
+	cache := aws.NewCredentialsCache(NewProvider(srv.Client(), srv.URL+"/latest"))
+	first, err := cache.Retrieve(context.Background())
+	if err != nil {
+		t.Fatalf("first Retrieve: %v", err)
+	}
+	got, err := cache.Retrieve(context.Background())
+	if err == nil {
+		t.Fatalf("refresh failure was reported as success: %+v", got)
+	}
+	if got.Expires.After(first.Expires) {
+		t.Errorf("expiry extended on refresh failure: %v -> %v", first.Expires, got.Expires)
+	}
+}

internal/stsauth/stsauth.go

@@ -8,8 +8,8 @@ package stsauth
 import (
 	"fmt"
 	"net/http"
-	"time"
 
+	awsv2 "github.com/aws/aws-sdk-go-v2/aws"
 	"github.com/aws/aws-sdk-go/aws"
 	awscreds "github.com/aws/aws-sdk-go/aws/credentials"
 	"github.com/aws/aws-sdk-go/aws/session"
@@ -20,24 +20,15 @@ import (
 // scope and the gateway does not enforce a specific value.
 const defaultRegion = "us-east-1"
 
-// Credentials is the decoded result of AssumeRole: a SigV4 credential set bound
-// to the assumed role, with its expiry.
-type Credentials struct {
-	AccessKeyID     string
-	SecretAccessKey string
-	SessionToken    string
-	Expiration      time.Time
-}
-
 // AssumeRole builds an aws-sdk STS client pointed at the gateway and calls
 // AssumeRole with the supplied static (instance-role) credentials, returning the
 // assumed-role credential set. httpClient must trust the gateway CA.
-func AssumeRole(region, gatewayURL string, httpClient *http.Client, akid, secret, sessionToken, roleARN, sessionName string) (Credentials, error) {
+func AssumeRole(region, gatewayURL string, httpClient *http.Client, akid, secret, sessionToken, roleARN, sessionName string) (awsv2.Credentials, error) {
 	if region == "" {
 		region = defaultRegion
 	}
 	if roleARN == "" || sessionName == "" {
-		return Credentials{}, fmt.Errorf("stsauth: roleARN and sessionName are required")
+		return awsv2.Credentials{}, fmt.Errorf("stsauth: roleARN and sessionName are required")
 	}
 	sess, err := session.NewSession(&aws.Config{
 		Region:      aws.String(region),
@@ -47,7 +38,7 @@ func AssumeRole(region, gatewayURL string, httpClient *http.Client, akid, secret
 		DisableSSL:  aws.Bool(false),
 	})
 	if err != nil {
-		return Credentials{}, fmt.Errorf("new session: %w", err)
+		return awsv2.Credentials{}, fmt.Errorf("new session: %w", err)
 	}
 
 	out, err := sts.New(sess).AssumeRole(&sts.AssumeRoleInput{
@@ -55,16 +46,17 @@ func AssumeRole(region, gatewayURL string, httpClient *http.Client, akid, secret
 		RoleSessionName: aws.String(sessionName),
 	})
 	if err != nil {
-		return Credentials{}, fmt.Errorf("AssumeRole: %w", err)
+		return awsv2.Credentials{}, fmt.Errorf("AssumeRole: %w", err)
 	}
 	if out.Credentials == nil {
-		return Credentials{}, fmt.Errorf("AssumeRole returned no credentials")
+		return awsv2.Credentials{}, fmt.Errorf("AssumeRole returned no credentials")
 	}
 	c := out.Credentials
-	return Credentials{
+	return awsv2.Credentials{
 		AccessKeyID:     aws.StringValue(c.AccessKeyId),
 		SecretAccessKey: aws.StringValue(c.SecretAccessKey),
 		SessionToken:    aws.StringValue(c.SessionToken),
-		Expiration:      aws.TimeValue(c.Expiration),
+		CanExpire:       c.Expiration != nil,
+		Expires:         aws.TimeValue(c.Expiration),
 	}, nil
 }

internal/stsauth/stsauth_test.go

@@ -41,8 +41,8 @@ func TestAssumeRole_DecodesCredentials(t *testing.T) {
 		t.Errorf("bad creds: %+v", creds)
 	}
 	want, _ := time.Parse(time.RFC3339, "2031-01-02T03:04:05Z")
-	if !creds.Expiration.Equal(want) {
-		t.Errorf("Expiration = %v, want %v", creds.Expiration, want)
+	if !creds.Expires.Equal(want) {
+		t.Errorf("Expires = %v, want %v", creds.Expires, want)
 	}
 	// The request must carry the AssumeRole action and the role ARN we asked for.
 	if !strings.Contains(gotBody, "Action=AssumeRole") {

internal/testkit/awserror.go

@@ -0,0 +1,29 @@
+package testutil
+
+import (
+	"testing"
+
+	awserrors "github.com/mulgadc/spinifex/spinifex/foundation/aws/errors"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// RequireAWSError asserts err carries the AWS code and exact client-facing
+// message; an empty message asserts the bare code with no message attached.
+func RequireAWSError(t *testing.T, err error, code, message string) {
+	t.Helper()
+	require.Error(t, err)
+	got, msg, ok := awserrors.ResolveErrorDetail(err)
+	require.True(t, ok, "error %v carries no AWS code", err)
+	assert.Equal(t, code, got)
+	assert.Equal(t, message, msg)
+}
+
+// RequireAWSCode asserts err carries the AWS code, whatever its message.
+func RequireAWSCode(t *testing.T, err error, code string) {
+	t.Helper()
+	require.Error(t, err)
+	got, ok := awserrors.ResolveErrorCode(err)
+	require.True(t, ok, "error %v carries no AWS code", err)
+	assert.Equal(t, code, got)
+}

internal/testkit/nats.go

@@ -167,11 +167,11 @@ func registerVpcdStub(t *testing.T, nc *nats.Conn, defaultPayload []byte) {
 	})
 }
 
-// SeedKV creates a KV bucket and populates it with the given entries.
+// SeedKV creates or updates a KV bucket and populates it with the given entries.
 // Returns the KV handle for further use.
 func SeedKV(t *testing.T, js jetstream.JetStream, bucket string, entries map[string][]byte) jetstream.KeyValue {
 	t.Helper()
-	kv, err := js.CreateKeyValue(t.Context(), jetstream.KeyValueConfig{Bucket: bucket, History: 1})
+	kv, err := js.CreateOrUpdateKeyValue(t.Context(), jetstream.KeyValueConfig{Bucket: bucket, History: 1})
 	require.NoError(t, err)
 	for k, v := range entries {
 		_, err := kv.Put(t.Context(), k, v)

internal/testkit/nats_test.go

@@ -0,0 +1,19 @@
+package testutil
+
+import (
+	"testing"
+
+	"github.com/nats-io/nats.go/jetstream"
+	"github.com/stretchr/testify/require"
+)
+
+func TestSeedKV_ExistingBucket(t *testing.T) {
+	_, _, js := StartTestJetStream(t)
+	_, err := js.CreateKeyValue(t.Context(), jetstream.KeyValueConfig{Bucket: "seeded", History: 5})
+	require.NoError(t, err)
+
+	kv := SeedKV(t, js, "seeded", map[string][]byte{"k": []byte("v")})
+	entry, err := kv.Get(t.Context(), "k")
+	require.NoError(t, err)
+	require.Equal(t, []byte("v"), entry.Value())
+}

scripts/build-lambda-runtime-microvm-image.sh

@@ -3,24 +3,28 @@
 # + initramfs: a guest running the Lambda guest agent, with virtio-net for its
 # host control connection. It is not shipped.
 #
+# Usage: build-lambda-runtime-microvm-image.sh [agent-binary [output-dir]]
+#
 # Inputs:
 #   $REPO_ROOT/build/microvm/lambda-runtime/{init.sh,inittab,run-agent}
-#   $REPO_ROOT/bin/lambda-agent  (make bin/lambda-agent)
+#   agent binary, default $REPO_ROOT/bin/lambda-agent (make bin/lambda-agent)
 #
-# Outputs:
-#   $REPO_ROOT/build/microvm/lambda-runtime/vmlinuz
-#   $REPO_ROOT/build/microvm/lambda-runtime/initramfs.cpio.gz
+# Outputs, in output-dir (default $REPO_ROOT/build/microvm/lambda-runtime):
+#   vmlinuz
+#   initramfs.cpio.gz
 #
 # Rootfs strategy and module stripping: scripts/lib/microvm-image.sh.
 # shellcheck disable=SC2034 # variables are consumed by the sourced library
 set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-BUILD_DIR="$REPO_ROOT/build/microvm/lambda-runtime"
-INIT_SH="$BUILD_DIR/init.sh"
-INITTAB="$BUILD_DIR/inittab"
-RUN_AGENT="$BUILD_DIR/run-agent"
-LAMBDA_AGENT_BIN="$REPO_ROOT/bin/lambda-agent"
+INPUT_DIR="$REPO_ROOT/build/microvm/lambda-runtime"
+INIT_SH="$INPUT_DIR/init.sh"
+INITTAB="$INPUT_DIR/inittab"
+RUN_AGENT="$INPUT_DIR/run-agent"
+LAMBDA_AGENT_BIN="${1:-$REPO_ROOT/bin/lambda-agent}"
+# The library stages beside BUILD_DIR, so it names the output, not the inputs.
+BUILD_DIR="${2:-$INPUT_DIR}"
 TAG="[build-lambda-runtime-microvm-image]"
 
 ALPINE_VERSION="${ALPINE_VERSION:-3.24}"
@@ -38,7 +42,8 @@ MICROVM_GATE_MODULES="qemu_fw_cfg virtio_net"
 source "$REPO_ROOT/scripts/lib/microvm-image.sh"
 
 echo "$TAG repo root: $REPO_ROOT"
-echo "$TAG build dir: $BUILD_DIR"
+echo "$TAG input dir: $INPUT_DIR"
+echo "$TAG output dir: $BUILD_DIR"
 
 microvm_check_tools
 
@@ -57,6 +62,9 @@ if ! file -b "$LAMBDA_AGENT_BIN" | grep -q "statically linked"; then
     exit 1
 fi
 
+# Absolute, because packing the initramfs runs from inside the chroot.
+mkdir -p "$BUILD_DIR"
+BUILD_DIR=$(cd "$BUILD_DIR" && pwd)
 microvm_init_dirs
 microvm_make_rootfs
 microvm_empty_dev

scripts/build-lambda-runtime-microvm-image_test.sh

@@ -0,0 +1,81 @@
+#!/bin/sh
+# build-lambda-runtime-microvm-image_test.sh — a build into a chosen output
+# directory stages and publishes there, and leaves the default input directory
+# untouched.
+#
+# The script runs in a fixture repo against the real library, with only the
+# rootfs, kernel and packing steps replaced so no image is downloaded.
+set -eu
+
+SCRIPTS_DIR=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+
+fails=0
+pass() { echo "  ok   - $1"; }
+fail() { echo "  FAIL - $1"; fails=$((fails + 1)); }
+
+echo "-- build-lambda-runtime-microvm-image.sh output directory"
+
+REPO="$TMP/repo"
+IN="$REPO/build/microvm/lambda-runtime"
+mkdir -p "$REPO/scripts/lib" "$IN" "$REPO/bin" "$TMP/bin"
+cp "$SCRIPTS_DIR/build-lambda-runtime-microvm-image.sh" "$REPO/scripts/"
+for f in init.sh inittab run-agent; do printf '%s\n' "$f" > "$IN/$f"; done
+printf 'default image\n' > "$IN/vmlinuz"
+printf '#!/bin/sh\n' > "$REPO/bin/agent-testlink"
+chmod +x "$REPO/bin/agent-testlink"
+printf '#!/bin/sh\necho "ELF 64-bit, statically linked"\n' > "$TMP/bin/file"
+chmod +x "$TMP/bin/file"
+BEFORE=$(cd "$IN" && ls -A | cksum)
+
+# The real library, with the steps that need a rootfs or kernel replaced.
+# Packing runs from inside the chroot as the real step does, and records where
+# the stage is while it still exists.
+cat > "$REPO/scripts/lib/microvm-image.sh" <<EOF
+. "$SCRIPTS_DIR/lib/microvm-image.sh"
+microvm_check_tools() { :; }
+microvm_make_rootfs() { mkdir -p "\$CHROOT_DIR/etc"; }
+microvm_empty_dev() { :; }
+microvm_locate_kernel() { :; }
+microvm_strip_modules() { :; }
+microvm_strip_rootfs() { :; }
+microvm_stage_kernel() { printf 'kernel\n' > "\$STAGE_DIR/vmlinuz"; }
+microvm_pack_initramfs() {
+    (cd "\$CHROOT_DIR" && printf 'initramfs\n' | gzip > "\$STAGE_DIR/initramfs.cpio.gz")
+    dirname "\$STAGE_DIR" > "$TMP/stage-parent"
+    ls -A "$IN" > "$TMP/input-during"
+}
+EOF
+
+# The output is given relative to the repo root, as make passes it.
+OUT="$REPO/build/microvm/lambda-testlink-runtime"
+if ! (cd "$REPO" && PATH="$TMP/bin:$PATH" bash scripts/build-lambda-runtime-microvm-image.sh bin/agent-testlink build/microvm/lambda-testlink-runtime) > "$TMP/log" 2>&1; then
+    fail "build into output dir: $(tr '\n' ' ' < "$TMP/log")"
+else
+    if [ "$(cat "$TMP/stage-parent")" = "$OUT" ]; then
+        pass "stage created in the output directory"
+    else
+        fail "stage created in $(cat "$TMP/stage-parent"), want $OUT"
+    fi
+    if grep -q '^\.stage\.' "$TMP/input-during"; then
+        fail "stage present in the default input directory during the build"
+    else
+        pass "no stage in the default input directory during the build"
+    fi
+    if [ "$(cd "$IN" && ls -A | cksum)" = "$BEFORE" ] && grep -qx 'default image' "$IN/vmlinuz"; then
+        pass "default input directory unchanged"
+    else
+        fail "default input directory changed: $(cd "$IN" && ls -A | tr '\n' ' ')"
+    fi
+    if grep -qx kernel "$OUT/vmlinuz" && gzip -t "$OUT/initramfs.cpio.gz" && [ "$(ls -A "$OUT" | wc -l)" -eq 2 ]; then
+        pass "output directory holds exactly the published pair"
+    else
+        fail "output directory: $(ls -A "$OUT" | tr '\n' ' ')"
+    fi
+fi
+
+if [ "$fails" -ne 0 ]; then
+    echo "$fails failure(s)"
+    exit 1
+fi

scripts/images/ecs-agent-gpu/ecs-agent.service

@@ -9,8 +9,7 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-# Static config (gateway URL, CA, region, cluster, seeded IAM creds,
-# containerd socket) comes from /etc/spinifex-ecs/agent.env, dropped by
+# Static config (gateway URL, CA, region, cluster, containerd socket) comes from /etc/spinifex-ecs/agent.env, dropped by
 # cloud-init at launch. Absent file is tolerated — the agent falls back to
 # its built-in defaults.
 EnvironmentFile=-/etc/spinifex-ecs/agent.env

scripts/images/ecs-agent/ecs-agent.initd

@@ -3,8 +3,7 @@
 # IMDSv2, registers + heartbeats + polls task assignments through the AWS gateway
 # over TLS+SigV4 (no NATS), and pulls task images through containerd.
 #
-# Static config (gateway URL, CA, region, cluster, seeded IAM creds, containerd
-# socket) comes from /etc/spinifex-ecs/agent.env, dropped by cloud-init at launch.
+# Static config (gateway URL, CA, region, cluster, containerd socket) comes from /etc/spinifex-ecs/agent.env, dropped by cloud-init at launch.
 
 description="Spinifex ECS container-instance agent"
 command="/usr/local/bin/ecs-agent"
@@ -28,7 +27,7 @@ start_pre() {
         # shellcheck disable=SC1091
         . /etc/spinifex-ecs/agent.env
         export ECS_GATEWAY_URL ECS_GATEWAY_CA ECS_REGION ECS_CLUSTER \
-            ECS_ACCESS_KEY ECS_SECRET_KEY ECS_IMDS_BASE ECS_CONTAINERD_SOCKET \
+            ECS_IMDS_BASE ECS_CONTAINERD_SOCKET \
             ECS_HEARTBEAT_INTERVAL ECS_POLL_INTERVAL
     fi
 }

scripts/install-node.sh

@@ -260,6 +260,14 @@ out() {
     ssh "${SSH_OPTS[@]}" "$SSH_USER@$host" "$@" 2>/dev/null || true
 }
 
+# remote_join_cmd prints the command that joins one node. The token is not in it: it arrives on
+# stdin and is read after sudo has logged its command, so sudo's log never holds it. The other
+# values are positional arguments of a literal script, never spliced into it.
+remote_join_cmd() {
+    local script='exec spx admin join --force --node "$1" --bind "$2" --cluster-bind "$2" --advertise "$3" --host "$4" --token "$(cat)" --region "$5" --az "$6"'
+    printf 'sudo bash -c %q _ %q %q %q %q %q %q' "$script" "$@"
+}
+
 SETUP_OVN="/usr/local/share/spinifex/setup-ovn.sh"
 
 # --- Preflight -------------------------------------------------------------
@@ -652,14 +660,18 @@ fi
 [ -n "$EXT_IFACE" ] && init_args+=(--external-iface="$EXT_IFACE")
 [ -n "$EMAIL" ] && init_args+=(--email="$EMAIL")
 
-INIT_LOG=/tmp/spx-init.log
+# init prints the join token, so its log is root-only and outside the world-writable /tmp.
+INIT_LOG=/var/log/spx-init.log
+
+# redact_tokens hides join tokens in text about to be shown to the operator.
+redact_tokens() { sed -E 's/spx_join_[A-Za-z0-9_-]+/spx_join_[redacted]/g'; }
 
 log "initializing ${HOSTS[0]} as ${NODE_NAMES[0]} (waiting for $((N - 1)) node(s) to join)"
 
 # init blocks in a formation server until every node has joined, so it runs
 # detached and the token is read back out of its output.
 on "${HOSTS[0]}" "sudo rm -f $INIT_LOG; \
-    sudo setsid sh -c 'spx admin init ${init_args[*]} >$INIT_LOG 2>&1' </dev/null >/dev/null 2>&1 & \
+    sudo setsid sh -c 'umask 077; spx admin init ${init_args[*]} >$INIT_LOG 2>&1' </dev/null >/dev/null 2>&1 & \
     exit 0" || fail "${HOSTS[0]}: could not start spx admin init"
 
 TOKEN=""
@@ -675,7 +687,7 @@ else
         elapsed=$((elapsed + 5))
     done
     if [ -z "$TOKEN" ]; then
-        out "${HOSTS[0]}" "sudo tail -40 $INIT_LOG" | sed 's/^/  | /' >&2
+        out "${HOSTS[0]}" "sudo tail -40 $INIT_LOG" | redact_tokens | sed 's/^/  | /' >&2
         fail "${HOSTS[0]}: spx admin init produced no join token within ${TOKEN_TIMEOUT}s"
     fi
     log "  join token issued"
@@ -691,11 +703,9 @@ fi
 # waiting on a shell that node 2 is still holding.
 JOIN_PIDS=()
 for i in $(seq 1 $((N - 1))); do
-    on "${HOSTS[$i]}" "sudo spx admin join --force \
-        --node ${NODE_NAMES[$i]} \
-        --bind ${LAN_IPS[$i]} --cluster-bind ${LAN_IPS[$i]} --advertise ${WAN_IPS[$i]} \
-        --host ${LAN_IPS[0]}:$PORT --token $TOKEN \
-        --region $REGION --az $AZ" &
+    # The token goes to the node on stdin, so it is in no ssh argument and not in sudo's log.
+    # spx admin join takes it only as --token, so it is still in that process's arguments.
+    on "${HOSTS[$i]}" "$(remote_join_cmd "${NODE_NAMES[$i]}" "${LAN_IPS[$i]}" "${WAN_IPS[$i]}" "${LAN_IPS[0]}:$PORT" "$REGION" "$AZ")" <<<"$TOKEN" &
     JOIN_PIDS+=("$!")
 done
 
@@ -724,7 +734,7 @@ if ! $DRY_RUN; then
         elapsed=$((elapsed + 5))
     done
     if [ "$elapsed" -ge "$FORMATION_TIMEOUT" ]; then
-        out "${HOSTS[0]}" "sudo tail -40 $INIT_LOG" | sed 's/^/  | /' >&2
+        out "${HOSTS[0]}" "sudo tail -40 $INIT_LOG" | redact_tokens | sed 's/^/  | /' >&2
         fail "${HOSTS[0]}: formation did not complete within ${FORMATION_TIMEOUT}s"
     fi
     log "  formation complete"

scripts/install-node_test.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Tests remote_join_cmd from install-node.sh: the join token must reach spx only on stdin, so
+# sudo's log (which holds the command it was given) never contains it, and the other values must
+# arrive as plain arguments even when they hold shell syntax.
+# preflight runs this with sh
+[ -n "${BASH_VERSION:-}" ] || exec bash "$0" "$@"
+set -euo pipefail
+here="$(cd "$(dirname "$0")" && pwd)"
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+mkdir "$work/bin"
+cd "$work"
+
+cat > "$work/bin/sudo" <<'SH'
+#!/bin/sh
+echo "$*" >> "$FAKE_SUDO_LOG"
+exec "$@"
+SH
+cat > "$work/bin/spx" <<'SH'
+#!/bin/sh
+for a in "$@"; do printf '<%s>' "$a"; done > "$FAKE_SPX_ARGV"
+SH
+chmod +x "$work/bin/sudo" "$work/bin/spx"
+export FAKE_SUDO_LOG="$work/sudo.log" FAKE_SPX_ARGV="$work/spx.argv" PATH="$work/bin:$PATH"
+
+eval "$(sed -n '/^remote_join_cmd()/,/^}/p' "$here/install-node.sh")"
+
+fails=0
+check() { if [ "$2" = "$3" ]; then echo "ok   $1"; else echo "FAIL $1: want '$3' got '$2'"; fails=$((fails + 1)); fi; }
+
+TOKEN=spx_join_FAKETOKEN-abc_1
+cmd="$(remote_join_cmd node2 10.0.0.2 203.0.113.2 '10.0.0.1:4432;touch PWNED' us-east-1 'az $(touch PWNED2)')"
+bash -c "$cmd" <<<"$TOKEN"
+
+check "the token is not in the command" "$(printf '%s' "$cmd" | grep -c FAKETOKEN || true)" 0
+check "the token is not in sudo's log" "$(grep -c FAKETOKEN "$FAKE_SUDO_LOG" || true)" 0
+check "spx got the token" "$(grep -o '<--token><[^>]*>' "$FAKE_SPX_ARGV")" "<--token><$TOKEN>"
+check "spx got the other values as given" "$(cat "$FAKE_SPX_ARGV")" "<admin><join><--force><--node><node2><--bind><10.0.0.2><--cluster-bind><10.0.0.2><--advertise><203.0.113.2><--host><10.0.0.1:4432;touch PWNED><--token><$TOKEN><--region><us-east-1><--az><az \$(touch PWNED2)>"
+check "no value was run as a command" "$(find "$work" -maxdepth 1 -name 'PWNED*' | wc -l | tr -d ' ')" 0
+
+[ "$fails" -eq 0 ]

scripts/lib/lambda-testlink-build_test.sh

@@ -0,0 +1,111 @@
+#!/bin/sh
+# lambda-testlink-build_test.sh — the test-link make targets refuse a malformed
+# image digest and an unsupported host or GOARCH before touching any output.
+#
+# Every case is refused on the recipe's first lines, so nothing is compiled.
+set -eu
+
+LIB_DIR=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
+REPO_ROOT=$(dirname -- "$(dirname -- "$LIB_DIR")")
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+
+fails=0
+pass() { echo "  ok   - $1"; }
+fail() { echo "  FAIL - $1"; fails=$((fails + 1)); }
+
+echo "-- make build-lambda-testlink / build-lambda-testlink-image guards"
+
+PWN="$TMP/pwn"
+OUT="$TMP/out"
+HEX=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+mkdir -p "$OUT"
+printf 'old daemon\n' > "$OUT/spx"
+printf 'old initializer\n' > "$OUT/hardkill.so"
+PAIR=$(cat "$OUT/spx" "$OUT/hardkill.so" | cksum)
+
+# unchanged <name> — the existing pair is intact, no scratch was made and no
+# injected command ran.
+unchanged() {
+    if [ -e "$PWN" ]; then
+        fail "$1: injected command ran"
+        rm -f "$PWN"
+    elif [ -e "$OUT.tmp" ]; then
+        fail "$1: scratch directory created"
+    elif [ "$(cat "$OUT/spx" "$OUT/hardkill.so" | cksum)" != "$PAIR" ]; then
+        fail "$1: existing pair replaced"
+    else
+        pass "$1"
+    fi
+}
+
+# refused <name> <want> <log> <status> — make failed with the expected message.
+refused() {
+    if [ "$4" -eq 0 ]; then
+        fail "$1: make succeeded"
+    elif ! grep -q "$2" "$3"; then
+        fail "$1: wrong refusal: $(tr '\n' ' ' < "$3")"
+    else
+        unchanged "$1"
+    fi
+}
+
+testlink() {
+    make -s -C "$REPO_ROOT" --no-print-directory build-lambda-testlink LAMBDA_TESTLINK_DIR="$OUT" "$@" > "$TMP/log" 2>&1
+}
+
+DIGEST_MSG="LAMBDA_IMAGE_DIGEST must be 64 lowercase hex digits"
+NL='
+'
+for v in '' "\$(shell touch $PWN)" "\$\$(touch $PWN)" "\`touch $PWN\`" "$HEX; touch $PWN" \
+    "$HEX\" -X main.x=\"y" "$HEX -X main.x=y" "$HEX${NL}touch $PWN" \
+    0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF "${HEX%?}" "${HEX}0"; do
+    # GNU make itself expands a command-line $(shell ...) while parsing, for
+    # any target, so that one literal is tested only from the environment.
+    case "$v" in
+    "\$(shell"*) ;;
+    *)
+        status=0
+        testlink LAMBDA_IMAGE_DIGEST="$v" || status=$?
+        refused "command-line digest [$v]" "$DIGEST_MSG" "$TMP/log" "$status"
+        ;;
+    esac
+    status=0
+    LAMBDA_IMAGE_DIGEST="$v" testlink || status=$?
+    refused "environment digest [$v]" "$DIGEST_MSG" "$TMP/log" "$status"
+done
+
+status=0
+env -u LAMBDA_IMAGE_DIGEST make -s -C "$REPO_ROOT" --no-print-directory build-lambda-testlink LAMBDA_TESTLINK_DIR="$OUT" > "$TMP/log" 2>&1 || status=$?
+refused "digest unset" "$DIGEST_MSG" "$TMP/log" "$status"
+
+ARCH_MSG="supports only an x86_64 host building linux/amd64"
+SHIM="$TMP/shim"
+mkdir -p "$SHIM"
+printf '#!/bin/sh\necho aarch64\n' > "$SHIM/uname"
+chmod +x "$SHIM/uname"
+
+status=0
+GOARCH=arm64 testlink LAMBDA_IMAGE_DIGEST="$HEX" || status=$?
+refused "GOARCH=arm64" "$ARCH_MSG" "$TMP/log" "$status"
+status=0
+PATH="$SHIM:$PATH" testlink LAMBDA_IMAGE_DIGEST="$HEX" || status=$?
+refused "aarch64 host" "$ARCH_MSG" "$TMP/log" "$status"
+
+# The image target refuses before building qboot or any agent binary.
+for c in "GOARCH=arm64" "PATH=$SHIM:$PATH"; do
+    status=0
+    env "$c" make -s -C "$REPO_ROOT" --no-print-directory build-lambda-testlink-image > "$TMP/log" 2>&1 || status=$?
+    if [ "$status" -eq 0 ]; then
+        fail "image target [${c%%=*}]: make succeeded"
+    elif ! grep -q "$ARCH_MSG" "$TMP/log" || grep -q "qboot\|go build" "$TMP/log"; then
+        fail "image target [${c%%=*}]: did not refuse first: $(tr '\n' ' ' < "$TMP/log")"
+    else
+        pass "image target [${c%%=*}] refused first"
+    fi
+done
+
+if [ "$fails" -ne 0 ]; then
+    echo "$fails failure(s)"
+    exit 1
+fi

scripts/terraform/latitude-spx/.gitignore

@@ -0,0 +1,10 @@
+.terraform/
+terraform.tfstate
+terraform.tfstate.*
+*.tfplan
+*.auto.tfvars
+crash.log
+terraform.tfvars
+*.pem
+*.log
+.terraform.lock.hcl

scripts/terraform/latitude-spx/README.md

@@ -0,0 +1,137 @@
+# latitude-spx
+
+Builds a Spinifex deployment on latitude.sh bare metal from your laptop with `deploy-latitude.sh`.
+The commands, flags, step markers and state layout follow `vultr-spx`.
+
+**Status: not yet run end to end.**
+The script was written from the plan doc findings (`docs/development/feature/latitude-bm.md`, L1 to L26) and from the provider schema.
+No latitude.sh API call or host run was made while building it, so treat the first `up` as the test.
+One node has been the only shape run live, and only in part (see Unverified). The three-node flow, including the floating pool, has not been run: Ben takes that over.
+
+## What it creates
+
+| Resource | Notes |
+|---|---|
+| Project | `spinifex-<name>`, unless `--project` names an existing one (then it is never deleted) |
+| SSH key | `spinifex-<name>`, account scoped |
+| User data | `spinifex-<name>`, host preparation only (no `{{ }}`, latitude.sh substitutes them) |
+| Servers | `m4-metal-medium`, site `DAL`, Ubuntu 26.04, hourly billing, hostnames `spx-<name>-nodeN` |
+| Elastic IP | one by default (`elastic_ip_count` in `variables.tf`, 1 to 5; set `TF_VAR_elastic_ip_count` to change it). With one node it is a static pool address and the count must stay 1, because a second pool is never tried when the first is full; with three nodes the addresses form the `latitude` floating pool, which Spinifex moves between servers. `nginx-webserver` needs one address and runs on one node; `nginx-alb` needs two public addresses and is a three-node workbook |
+| Virtual network | three nodes only: `spinifex-<name>`, one VLAN assignment per server |
+
+## Requirements
+
+OpenTofu (or Terraform) 1.5 or later, `aws` CLI, `python3`, `curl`, `ssh`, an SSH key pair.
+
+| Variable | When | Meaning |
+|---|---|---|
+| `LATITUDESH_AUTH_TOKEN` | always | the account API token; used by the provider and this script only, never sent to a node |
+| `LATITUDESH_NODE_TOKEN` | `--nodes 3` | a second, different, writable API key, copied to each node (`/etc/spinifex/latitude/api-token`, owned by `spinifex-daemon` with mode 0400, in a root-owned 0711 directory; the other services share the `spinifex` group, so no group may read it; ownership and mode are set on every `up`; a symlink or any other owner there is refused) so the daemon can move Elastic IPs |
+
+The script refuses a node key it can see is read-only (it lists `/auth/api_keys` and matches the key's last five characters). If the key is not among the account's keys, write authority is first proven by the first Elastic IP move.
+
+Exposure: a latitude.sh API key is team-wide. It is not scoped to Elastic IPs, so anyone who reads it from a node can do whatever the key's owner can in the team (the API exposes `read_only` and `allowed_ips` on a key, and no narrower scope). Create the node key with `allowed_ips` set to the nodes' public addresses, and revoke it after `destroy`.
+
+Nodes are reached as `ubuntu` with the deployment's SSH key, and remote commands run through passwordless `sudo`: latitude.sh puts the key on the image's login user and root login is not enabled.
+
+## Usage
+
+```
+export LATITUDESH_AUTH_TOKEN=...        # from the latitude.sh dashboard
+./deploy-latitude.sh up --name demo     # one node
+
+export LATITUDESH_NODE_TOKEN=...        # a second, writable key
+./deploy-latitude.sh up --name demo3 --nodes 3
+./deploy-latitude.sh status --name demo
+./deploy-latitude.sh ssh --name demo node1 'systemctl status spinifex.target'
+./deploy-latitude.sh credentials --name demo
+./deploy-latitude.sh stop node1 --name demo
+./deploy-latitude.sh start node1 --name demo
+./deploy-latitude.sh destroy --name demo
+```
+
+Options: `--name`, `--site` (alias `--region`), `--plan`, `--os`, `--project ID|SLUG`, `--distro TARBALL`, `--channel`, `--spx-region`, `--spx-az`, `--ssh-key`, `--image`, `--data-disk-id`, `--vpc-subnet` (the VLAN's /24, three nodes), `--nodes 1|3`, `--yes`.
+`./deploy-latitude.sh --help` lists them with defaults.
+
+Three nodes need `--distro` with a tarball built from this branch (`make distro-amd64`) until a release carries the latitude provider.
+A released spx rejects `source="latitude"` and its daemon restarts in a loop, so `up --nodes 3` without `--distro` stops in preflight.
+Before the pool is written, each node's `/usr/local/bin/spx` is checked for the `latitude_elastic_ip_ids` key name; spx has no validate subcommand, so this is a string search of the binary, not a run of its config check.
+
+## What `up` does
+
+`terraform` then, per node: `host` (wait for SSH as `ubuntu` and cloud-init, `/dev/kvm`), `disk`, `vlan` (three nodes), `install`, `form`, `start`; then `pool` (one node) or `cluster` (three nodes: `install-node.sh` forms the cluster); three nodes then install the node token on every `up` and add the `latitude` pool (`pool`); then `restart` (three nodes wait for the current daemon to log "floating pool ready" for the pool), `public`, `image` and the AWS profile.
+Each step writes `step.<name>[.nodeN]` in the state directory, and a rerun resumes at the first step without one.
+
+- **Data disk.** `host-data-disk.sh` picks the blank NVMe by content and by-id EUI, never by `nvmeXn1` (L1, L11).
+A candidate is at least 100 GB with no signature, partitions, holders or mounts, and not in the root filesystem's ancestry; with none it stops and lists the disks.
+With several (LON2 has two 1.7 TB and one spare 447 GB blank NVMe next to the root disk) it takes the largest, the lowest by-id path among equals, prints what it chose and the blank disks it left, and never touches the others (`--data-disk-id` chooses another).
+It mounts by UUID with `nofail` and the script records the UUID in `data_uuid.<node>`.
+- **Mount check.** Before anything writes under `/var/lib/spinifex`, and on every run, the mounted filesystem UUID must equal the recorded one.
+The units that write there also get a `RequiresMountsFor=/var/lib/spinifex` drop-in.
+The mount is by UUID in fstab, so renamed disks do not change it, and there is no check at service start.
+- **Firewall.** `setup.sh --firewall on` runs before Spinifex first starts.
+- **One node.** The Elastic IP is a static pool (`gateway_ip = "192.0.2.1"`, the node's next hop as `gateway`, no `prefix_len`) with the IMDS addresses moved off the ones latitude.sh routes.
+- **Three nodes.** The `vlan` step makes `eno2.<vid>` with `ip link` and persists it as systemd-networkd files for that link plus a drop-in on the `eno2` unit.
+It never runs `netplan apply`, refuses a subnet that overlaps the SSH peer or a route, and removes the VLAN again if the public interface's address, default route or the route to the SSH peer differ afterwards.
+`form_cluster` then puts the cluster and Geneve planes on that VLAN with `install-node.sh` (`--user ubuntu`); its output is not kept, as it can hold the join token.
+- **Floating pool (three nodes).** The `latitude` pool names the Elastic IP IDs and the project ID from the Terraform outputs, and each node's `provider_host_id` is its server ID. `spinifex.toml` is edited idempotently and read back. Failover moves an address with one `PATCH /elastic_ips/{id}` and waits for it to be active; latitude.sh has no unassign, so a node that loses an address is not told to release it.
+- **State** is in `~/.spinifex/latitude/<name>/`: Terraform state, `ids` (every `latitudesh_*` object in the state, merged on each apply and before each destroy), `step.*` markers, logs and the data disk UUIDs.
+- **AWS profile** `spinifex-latitude-<name>` is replaced on each `up`, with the CA at `~/.spinifex/latitude-<name>-ca.pem`.
+The secret key is written to `~/.aws/credentials` (0600, other profiles kept, the old file saved beside it) and never appears in a process argument.
+
+## Token handling
+
+`LATITUDESH_AUTH_TOKEN` is read from the environment by the provider and by the script's API calls.
+It is not a Terraform variable, is on no command line (curl reads it from stdin), is not sent to a node, and is written to no file.
+`LATITUDESH_NODE_TOKEN` is checked with curl reading it from stdin and reaches each node on stdin of the install script, so it is in no argument on either side.
+`TF_LOG` is unset by the script.
+The join token that `install-node.sh` creates is shared with Vultr and OCI: its init log is root-only, and `spx admin join` still takes it as `--token` on the joining node (tracked separately).
+
+## Recovery
+
+If SSH is lost once the firewall is armed, use the serial console.
+`up` enables the server's out-of-band connection with the deployment's SSH key and prints the `ssh` command it returns before it arms the firewall, falling back to the Out-of-Band tab in the dashboard.
+Logging in there needs an OS user password, which you set yourself while SSH still works.
+A fresh deployment that cannot be recovered is cheaper to `destroy` and `up` again.
+The VLAN step prints the console command first.
+It refuses a subnet that holds the SSH peer or overlaps an existing route, and removes the VLAN again if the route to the SSH peer or the public interface changes.
+
+## destroy
+
+`destroy` asks you to type the deployment name (`--yes` skips only that), then records every ID in the Terraform state and stops without destroying anything if it cannot.
+It runs `terraform destroy`, fetches every recorded ID by itself (2xx present, 404 gone, anything else fails and keeps the records), and deletes what remains of those.
+Servers, keys, user data, virtual networks and projects whose names match the deployment but that are not recorded are listed by ID and deleted only after you type `delete-untracked` for exactly those IDs, which `--yes` never supplies; an ID that shows up later needs its own confirmation, and without a terminal they are kept and `destroy` exits 1.
+Elastic IPs are touched only by recorded ID.
+Elastic IP release is asynchronous and only works once the address is active or in error, so the sweep retries.
+Because the Elastic IP list ignores pagination, `destroy` ends by asking you to check the dashboard for leftovers and type `checked`.
+An `up` that failed while creating can leave an object nothing recorded, such as an Elastic IP; that dashboard check is the only thing that finds it.
+
+## Unverified
+
+Nothing in the three-node flow has run against real servers. For one node, only the parts the person ran have been exercised, and the script has changed since.
+
+- The OS slug `ubuntu_26_04_x64_lts` (the `latitudesh_operating_system` data source fails the plan if it is wrong).
+- That the deploy key is on `ubuntu` and `sudo -n` works for it, and that `sudo` resets nothing the script needs (the SSH peer address is read before `sudo` for that reason).
+- The power action request (`POST /servers/{id}/actions` with `power_off` and `power_on`).
+- Resolving `--project` as a slug through `GET /projects/{slug}`, and the `in_stock` shape of `GET /plans` used by the stock check, which only warns when it cannot read it.
+- The `GET` and `DELETE` paths for `/user_data/{id}` and `/virtual_networks/{id}`.
+- That the Spinifex API certificate names the node's public address, which the profile check needs.
+- That the private NIC is `eno2`, its tagging and MTU (the script uses 1500), and that the networkd files persist the VLAN across a reboot.
+- `GET /auth/api_keys` and its `token_last_slice` and `read_only` fields, which the node key check relies on; and that a key with `allowed_ips` set to the nodes' addresses still works from them.
+- The Elastic IP move itself: `PATCH /elastic_ips/{id}` with `server_id`, its 202 then `active`, the error codes, and how long a move takes; the client waits up to its move timeout and makes one write per call.
+- That the daemon reads the node token and logs "floating pool ready", then fails over when a node stops (`stop node1`) and the address lands on another node.
+- `install-node.sh` as `--user ubuntu` on latitude.sh servers.
+
+## Not exercised
+
+Any real API call from the three-node flow, `destroy`, `host-data-disk.sh` on a host and the VLAN step on a server.
+Guest launch, public reachability of the Elastic IP, the Terraform workbooks and failover are not part of `up`; prove them by hand.
+`e2e-latitude.sh` and removing the old `install-node.sh` in this directory are not done.
+
+## Tests
+
+`sh node-scripts_test.sh` checks the node token install (install, unchanged, rotation, modes, an older install converging, symlinks and owners refused; run it as root too, with `sudo sh node-scripts_test.sh`, to check that only the daemon's user can read the file) and the readiness check (old success then current failure) with stand-in tools.
+`bash deploy-argv_test.sh` checks that neither API token, nor the five characters used to find the node key, is an argument of any external command in the node token paths, and that the SSH peer address comes from the same connection after sudo's environment reset.
+`scripts/install-node_test.sh` (part of `make preflight`) checks that the join token reaches `spx admin join` only on stdin, so sudo's log never holds it.
+The first two are not part of `make preflight`.
+The Go side: `cd spinifex && GOWORK=off go test ./providers/cloud/latitude/ ./domains/network/external/floating/ ./bootstrap/config/ ./runtime/daemon/`.

scripts/terraform/latitude-spx/cloud-init/user-data.yaml

@@ -0,0 +1,23 @@
+#cloud-config
+# Host preparation only. Spinifex is installed and formed over SSH by deploy-latitude.sh.
+# latitude.sh substitutes double-brace variables in user data, so this file holds none.
+write_files:
+  - path: /etc/cloud/cloud.cfg.d/99-spinifex-network.cfg
+    content: |
+      network: {config: disabled}
+  # The image's netplan lists eno2 with no address and without optional, so boot waits two minutes
+  # for it. --any returns once one link, eno1, is online; it changes the wait, not the network.
+  # UNVERIFIED: the binary path is the Ubuntu one and the drop-in first applies on the next boot.
+  - path: /etc/systemd/system/systemd-networkd-wait-online.service.d/10-spinifex-any.conf
+    content: |
+      [Service]
+      ExecStart=
+      ExecStart=/usr/lib/systemd/systemd-networkd-wait-online --any
+# runcmd carries on past a failing command, so each line stands alone.
+runcmd:
+  - [sh, -c, "command -v ufw >/dev/null && ufw --force disable || true"]
+  - [sh, -c, "systemctl disable --now unattended-upgrades.service apt-daily-upgrade.timer apt-daily.timer || true"]
+  # The image ships empty apt lists and no git, which the workbooks need.
+  - [sh, -c, "apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get install -y -qq git || true"]
+  - [sh, -c, "systemctl daemon-reload || true"]
+  - [sh, -c, "touch /var/lib/cloud/spinifex-host-ready"]

scripts/terraform/latitude-spx/compute.tf

@@ -0,0 +1,70 @@
+locals {
+  hostname_prefix = "spx-${var.deployment_name}-node"
+  project         = var.project != "" ? var.project : latitudesh_project.deploy[0].slug
+  project_id      = var.project != "" ? var.project_id : latitudesh_project.deploy[0].id
+}
+
+# Both lookups fail the plan when a slug does not exist, which is the only check of the OS slug.
+data "latitudesh_operating_system" "os" {
+  slug = var.operating_system
+}
+
+data "latitudesh_plan" "plan" {
+  slug = var.plan
+}
+
+resource "latitudesh_project" "deploy" {
+  count             = var.project == "" ? 1 : 0
+  name              = "spinifex-${var.deployment_name}"
+  description       = "Spinifex deployment ${var.deployment_name}"
+  environment       = "Development"
+  provisioning_type = "on_demand"
+}
+
+# The key is team scoped. The server login user is ubuntu, not root.
+resource "latitudesh_ssh_key" "deploy" {
+  name       = "spinifex-${var.deployment_name}"
+  public_key = trimspace(file(pathexpand(var.ssh_public_key_path)))
+}
+
+# Host preparation only. Latitude substitutes double-brace variables inside user data, so the file
+# must hold none. Spinifex is installed over SSH by deploy-latitude.sh.
+resource "latitudesh_user_data" "host" {
+  description = "spinifex-${var.deployment_name}"
+  content     = filebase64("${path.module}/cloud-init/user-data.yaml")
+}
+
+# billing must be hourly: the default is monthly, which bills upfront with no refund.
+resource "latitudesh_server" "node" {
+  count            = var.node_count
+  project          = local.project
+  hostname         = "${local.hostname_prefix}${count.index + 1}"
+  site             = var.site
+  plan             = data.latitudesh_plan.plan.slug
+  operating_system = data.latitudesh_operating_system.os.slug
+  billing          = "hourly"
+  ssh_keys         = [latitudesh_ssh_key.deploy.id]
+  user_data        = latitudesh_user_data.host.id
+
+  timeouts = {
+    create = "60m"
+  }
+}
+
+# Elastic IPs are bought here and never created or deleted by Spinifex. Each starts on a server, spread
+# over the nodes, and server_id is ignored afterwards so a move by Spinifex is not undone by a later apply.
+resource "latitudesh_elastic_ip" "pool" {
+  count = var.elastic_ip_count
+  # The provider documents ID or slug but posts the value as project_id unresolved: a slug gave 404.
+  project   = local.project_id
+  server_id = latitudesh_server.node[count.index % var.node_count].id
+
+  lifecycle {
+    ignore_changes = [server_id]
+  }
+}
+
+moved {
+  from = latitudesh_elastic_ip.node1
+  to   = latitudesh_elastic_ip.pool[0]
+}

scripts/terraform/latitude-spx/deploy-argv_test.sh

@@ -0,0 +1,228 @@
+#!/usr/bin/env bash
+# Checks that neither API token is ever an argument of an external command in the node token
+# paths of deploy-latitude.sh. External commands are stand-ins that record their arguments and
+# their standard input; the test fails if a token is in the first and proves it is in the second.
+# preflight runs this with sh
+[ -n "${BASH_VERSION:-}" ] || exec bash "$0" "$@"
+set -euo pipefail
+exec </dev/null
+here="$(cd "$(dirname "$0")" && pwd)"
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+mkdir "$work/bin" "$work/home"
+real_python="$(command -v python3)"
+
+AUTH=FAKEAUTHTOKEN9
+NODE=FAKENODETOKEN7
+
+# Every command the script runs outside bash records "name args" and, for the first line of
+# standard input, "name stdin: ...".
+for c in curl ssh scp aws tofu ssh-keygen; do
+    cat > "$work/bin/$c" <<'SH'
+#!/bin/sh
+echo "$(basename "$0") $*" >> "$FAKE_ARGV"
+if [ ! -t 0 ]; then
+    in="$(cat)"
+    [ -z "$in" ] || echo "$(basename "$0") stdin: $in" >> "$FAKE_STDIN"
+fi
+case "$(basename "$0")" in
+    curl) printf '{"data":[{"attributes":{"token_last_slice":"%s","read_only":false}}]}\n200' "$(printf '%s' "$FAKE_NODE" | tail -c 5)" ;;
+    ssh)
+        if [ -n "${FAKE_SSH_EVAL:-}" ]; then
+            # Behave like a login on a node: skip the options and host, run the rest with the
+            # connection variable of this connection, and let sudo reset the environment.
+            while [ "$#" -gt 0 ]; do case "$1" in ubuntu@*) shift; break ;; *) shift ;; esac; done
+            SSH_CONNECTION="$FAKE_SSH_CONNECTION" bash -c "$*"
+        else
+            echo installed
+        fi ;;
+esac
+SH
+    chmod +x "$work/bin/$c"
+done
+cat > "$work/bin/sudo" <<'SH'
+#!/bin/sh
+while [ "$#" -gt 0 ]; do case "$1" in -*) shift ;; *) break ;; esac; done
+exec env -i PATH="$PATH" "$@"
+SH
+chmod +x "$work/bin/sudo"
+cat > "$work/bin/python3" <<SH
+#!/bin/sh
+echo "python3 \$*" >> "\$FAKE_ARGV"
+exec "$real_python" "\$@"
+SH
+chmod +x "$work/bin/python3"
+
+export FAKE_ARGV="$work/argv" FAKE_STDIN="$work/stdin" FAKE_NODE="$NODE" PATH="$work/bin:$PATH" HOME="$work/home"
+: > "$FAKE_ARGV"
+: > "$FAKE_STDIN"
+export LATITUDESH_AUTH_TOKEN="$AUTH" LATITUDESH_NODE_TOKEN="$NODE"
+
+# shellcheck source=deploy-latitude.sh
+source "$here/deploy-latitude.sh"
+
+# shellcheck disable=SC2034 # read by the sourced functions
+NODES=3 IP=192.0.2.10 NODE_NAME=node1
+check_node_token >/dev/null
+install_key >/dev/null 2>&1
+
+fails=0
+for tok in "$AUTH" "$NODE" "${NODE: -5}"; do
+    if grep -q "$tok" "$FAKE_ARGV"; then
+        echo "FAIL token $tok is in a command's arguments:"
+        grep "$tok" "$FAKE_ARGV"
+        fails=$((fails + 1))
+    else
+        echo "ok   $tok is in no argument"
+    fi
+done
+for what in "curl stdin:.*Bearer $NODE" "ssh stdin: $NODE"; do
+    if grep -q "$what" "$FAKE_STDIN"; then
+        echo "ok   the check can see the token where it is sent ($what)"
+    else
+        echo "FAIL the token never reached stdin ($what): the test would pass without checking anything"
+        fails=$((fails + 1))
+    fi
+done
+
+# The peer address comes from the same connection that runs the command, whichever source
+# address that connection has, and survives sudo's environment reset.
+export FAKE_SSH_EVAL=1
+for src in 198.51.100.7 203.0.113.99; do
+    export FAKE_SSH_CONNECTION="$src 51000 192.0.2.10 22"
+    got="$(on 'printf %s "$SSH_PEER"')"
+    if [ "$got" = "$src" ]; then echo "ok   peer $src reaches the command"; else echo "FAIL peer for $src was '$got'"; fails=$((fails + 1)); fi
+done
+
+# A three-node run needs a build that knows the latitude source: a release would be refused by its
+# own config check. The guard needs --distro, and the node is checked before it gets the pool.
+check_result() { if [ "$2" = "$3" ]; then echo "ok   $1"; else echo "FAIL $1: want '$3' got '$2'"; fails=$((fails + 1)); fi; }
+check_result "three nodes without --distro stop" "$( (NODES=3 DISTRO="" require_branch_build) >/dev/null 2>&1 && echo ran || echo stopped)" stopped
+check_result "three nodes with --distro go on" "$( (NODES=3 DISTRO=/tmp/x.tar.gz require_branch_build) >/dev/null 2>&1 && echo ran || echo stopped)" ran
+check_result "one node without --distro goes on" "$( (NODES=1 DISTRO="" require_branch_build) >/dev/null 2>&1 && echo ran || echo stopped)" ran
+check_result "one node with one address goes on" "$( (NODES=1 TF_VAR_elastic_ip_count=1 require_one_address) >/dev/null 2>&1 && echo ran || echo stopped)" ran
+check_result "one node with no setting goes on" "$( (NODES=1 TF_VAR_elastic_ip_count="" require_one_address) >/dev/null 2>&1 && echo ran || echo stopped)" ran
+check_result "one node with two addresses stops" "$( (NODES=1 TF_VAR_elastic_ip_count=2 require_one_address) >/dev/null 2>&1 && echo ran || echo stopped)" stopped
+check_result "three nodes with three addresses go on" "$( (NODES=3 TF_VAR_elastic_ip_count=3 require_one_address) >/dev/null 2>&1 && echo ran || echo stopped)" ran
+printf 'binary with latitude_elastic_ip_ids inside\n' > "$work/spx-new"
+printf 'binary of a release\n' > "$work/spx-old"
+SPX_BIN="$work/spx-new"
+check_result "a build that knows latitude is accepted" "$( (node_knows_latitude) >/dev/null 2>&1 && echo ran || echo stopped)" ran
+# shellcheck disable=SC2034 # read by the sourced functions
+SPX_BIN="$work/spx-old"
+check_result "a release is refused" "$( (node_knows_latitude) >/dev/null 2>&1 && echo ran || echo stopped)" stopped
+# The profile spx writes under sudo is in the ubuntu user's home, so node-side reads name that
+# directory instead of relying on root's HOME.
+mkdir "$work/awsdir"
+printf '[other]\naws_access_key_id = X\n[spinifex]\naws_access_key_id = AK1\naws_secret_access_key = SK1\n[z]\nq = 1\n' > "$work/awsdir/credentials"
+node_ip() { printf 192.0.2.10; }
+# shellcheck disable=SC2034 # read by the sourced functions
+NODE_AWS_DIR="$work/awsdir"
+check_result "credentials come from the node's AWS dir" "$(cmd_credentials | tr '\n' ' ')" "[spinifex] aws_access_key_id = AK1 aws_secret_access_key = SK1 "
+
+# A failed API call logs its status and a documented code, never the response text, which can
+# echo the request's headers.
+mkdir "$work/bin2"
+cat > "$work/bin2/curl" <<'SH'
+#!/bin/sh
+cat > /dev/null
+printf '{"errors":[{"code":"%s","detail":"Authorization: Bearer %s"}]}\n401' "$FAKE_CODE" "$FAKE_LEAK"
+SH
+chmod +x "$work/bin2/curl"
+logged="$(FAKE_CODE=UNAUTHORIZED FAKE_LEAK="$AUTH" PATH="$work/bin2:$PATH" latitude GET /servers 2>&1 || true)"
+check_result "a failed call names its status and code" "$(grep -c 'returned 401 (UNAUTHORIZED)' <<<"$logged" || true)" 1
+check_result "a failed call never logs the token" "$(grep -c "$AUTH" <<<"$logged" || true)" 0
+logged="$(FAKE_CODE="$AUTH" FAKE_LEAK="$AUTH" PATH="$work/bin2:$PATH" latitude GET /servers 2>&1 || true)"
+check_result "an undocumented code is not logged" "$(grep -c "$AUTH" <<<"$logged" || true)" 0
+
+# A recorded ID that now names another deployment's object is not ours to delete.
+# shellcheck disable=SC2034 # read by the sourced functions
+NAME=demo
+latitude() { printf '%s' "$FAKE_LAT"; }
+orig_expected_project_id="$(declare -f expected_project_id)"
+expected_project_id() { echo proj_1; }
+srv() {
+    local frag=',"project":{"id":"proj_1"}'
+    [ "$#" -lt 2 ] || frag="$2"
+    printf '{"data":{"id":"sv_1","attributes":{"hostname":"%s"%s}}}' "$1" "$frag"
+}
+FAKE_LAT="$(srv spx-demo-node2)"
+check_result "a recorded server with our hostname is ours" "$(recorded_identity server sv_1 && echo ours || echo "rc=$?")" ours
+FAKE_LAT="$(srv spx-other-node1)"
+check_result "a recorded server with another hostname is not" "$(recorded_identity server sv_1 && echo ours || echo "rc=$?")" rc=1
+FAKE_LAT="$(srv spx-demo2-node1)"
+check_result "a hostname that only starts like ours is not" "$(recorded_identity server sv_1 && echo ours || echo "rc=$?")" rc=1
+FAKE_LAT="$(srv spx-demo-node1 ',"project":{"id":"proj_other"}')"
+check_result "our hostname in another project is not ours" "$(recorded_identity server sv_1 && echo ours || echo "rc=$?")" rc=1
+FAKE_LAT="$(srv spx-demo-node1 '')"
+check_result "a server with no project is unknown" "$(recorded_identity server sv_1 && echo ours || echo "rc=$?")" rc=2
+FAKE_LAT="$(srv spx-demo-node1 ',"project":{}')"
+check_result "a project with no id is unknown" "$(recorded_identity server sv_1 && echo ours || echo "rc=$?")" rc=2
+FAKE_LAT="$(srv spx-demo-node1 ',"project":null')"
+check_result "a null project is unknown" "$(recorded_identity server sv_1 && echo ours || echo "rc=$?")" rc=2
+expected_project_id() { return 1; }
+FAKE_LAT="$(srv spx-demo-node1)"
+check_result "no known project id is unknown" "$(recorded_identity server sv_1 && echo ours || echo "rc=$?")" rc=2
+expected_project_id() { echo proj_1; }
+FAKE_LAT='not json'
+check_result "an unreadable object is unknown" "$(recorded_identity server sv_1 && echo ours || echo "rc=$?")" rc=2
+KNOWN_IDS="$work/ids"
+printf 'server sv_1\n' > "$KNOWN_IDS"
+lat_exists() { return 0; }
+FAKE_LAT="$(srv spx-other-node1)"
+check_result "destroy stops before Terraform when a recorded ID was reused" "$( (check_recorded_identity) >/dev/null 2>&1 && echo went || echo stopped)" stopped
+FAKE_LAT="$(srv spx-demo-node1 ',"project":{"id":"proj_other"}')"
+check_result "destroy stops when the same hostname is in another project" "$( (check_recorded_identity) >/dev/null 2>&1 && echo went || echo stopped)" stopped
+FAKE_LAT="$(srv spx-demo-node1 '')"
+check_result "destroy stops when the project cannot be read" "$( (check_recorded_identity) >/dev/null 2>&1 && echo went || echo stopped)" stopped
+FAKE_LAT="$(srv spx-demo-node1)"
+check_result "destroy goes on when the recorded server is ours" "$( (check_recorded_identity) >/dev/null 2>&1 && echo went || echo stopped)" went
+leftovers_out="$( (lat_match() { return 0; }; FAKE_LAT="$(srv spx-other-node1)" leftovers) 2>/dev/null || true)"
+check_result "a reused ID is not listed as a leftover to delete" "$(grep -c sv_1 <<<"$leftovers_out" || true)" 0
+
+# After terraform destroy the state's project output is gone; the remembered ID still lets the
+# sweep delete a matching leftover and keep a foreign one.
+eval "$orig_expected_project_id"
+TF_BIN="$work/tofu"
+printf '#!/bin/sh\nif [ -f "%s/gone" ]; then exit 1; fi\nprintf proj_1\n' "$work" > "$TF_BIN"
+chmod +x "$TF_BIN"
+EXPECTED_PROJECT=""
+remember_project_id
+check_result "the project ID is remembered while the state holds it" "$EXPECTED_PROJECT" proj_1
+: > "$work/gone"
+check_result "the state no longer answers after destroy" "$("$TF_BIN" output >/dev/null 2>&1 && echo up || echo gone)" gone
+printf 'server sv_1\nserver sv_2\n' > "$KNOWN_IDS"
+lat_match() { return 1; }
+latitude() { if [ "$2" = /servers/sv_1 ]; then srv spx-demo-node1; else srv spx-other-node1 ',"project":{"id":"proj_other"}'; fi; }
+swept="$(leftovers 2>/dev/null || true)"
+check_result "after destroy a matching leftover is still listed" "$(grep -c 'server sv_1 ' <<<"$swept" || true)" 1
+check_result "after destroy a foreign one is kept out" "$(grep -c 'server sv_2 ' <<<"$swept" || true)" 0
+EXPECTED_PROJECT=""
+swept="$(leftovers 2>/dev/null || true)"
+check_result "without the remembered ID a leftover is unknown, not matched" "$(grep -c 'server sv_1 sv_1 (unknown)' <<<"$swept" || true)" 1
+expected_project_id() { echo proj_1; }
+
+# Cleanup never deletes an object whose ownership could not be read, recorded or not.
+deleted="$work/deleted"
+: > "$deleted"
+latitude() { printf '%s %s\n' "$1" "$2" >> "$deleted"; }
+printf 'server sv_1\nserver sv_2\n' > "$KNOWN_IDS"
+delete_left $'server sv_1 sv_1 (unknown)\nserver sv_2 spx-demo-node2\n' "" >/dev/null 2>&1
+check_result "an unreadable recorded object is not deleted" "$(grep -c sv_1 "$deleted" || true)" 0
+check_result "a verified recorded object is deleted" "$(grep -c 'DELETE .*sv_2' "$deleted" || true)" 1
+
+# Both deployment sizes write the metadata remap.
+cfg="$work/spinifex.toml"
+extract() { sed -n "/^$1()/,/^}/p" "$here/deploy-latitude.sh" | sed -n "/<<'PY'/,/^PY\$/p" | sed '1d;$d' | sed "s|/etc/spinifex/spinifex.toml|$cfg|"; }
+printf '[network]\nexternal_mode = "nat"\n\n[bootstrap]\ny = 1\n' > "$cfg"
+extract configure_pool | python3 -I - 203.0.113.1 203.0.113.254
+check_result "one node gets the metadata remap" "$(grep -c 'imds_host_meta_ip = "169.254.42.254"' "$cfg")" 1
+printf '[network]\nexternal_mode = "nat"\n\n[nodes.node1]\nx = 1\n\n[nodes.node2]\nx = 1\n\n[nodes.node3]\nx = 1\n\n[bootstrap]\ny = 1\n' > "$cfg"
+extract configure_latitude_pool | python3 -I - proj_1 eip_1,eip_2 node1=sv_1,node2=sv_2,node3=sv_3
+check_result "three nodes get the metadata remap" "$(grep -c 'imds_host_dns_ip  = "169.254.42.253"' "$cfg")" 1
+check_result "three nodes get the latitude pool" "$(grep -c 'source                  = "latitude"' "$cfg")" 1
+extract configure_latitude_pool | python3 -I - proj_1 eip_1,eip_2 node1=sv_1,node2=sv_2,node3=sv_3
+check_result "writing the config again changes nothing" "$(grep -c 'imds_host_meta_ip' "$cfg")" 1
+unset FAKE_SSH_EVAL
+
+[ "$fails" -eq 0 ]

scripts/terraform/latitude-spx/host-data-disk.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# host-data-disk.sh — format and mount the blank data disk at /var/lib/spinifex. Run as root ON the host.
+#
+#   host-data-disk.sh [/dev/disk/by-id/nvme-eui.<id>]
+#
+# The disk is chosen by content, never by its nvmeXn1 name, which swaps between boots. A candidate is a
+# whole-disk by-id EUI link whose device is not in the root filesystem's ancestry, has no partitions,
+# holders, swap or mounts, no filesystem signature and no partition table. With none the script stops
+# and lists the disks. With several it takes the largest, and the lowest by-id path among equals, and
+# prints what it chose and the blank disks it left alone; pass the by-id path to choose another.
+# It never reformats: a rerun on a host already done prints the UUID and exits. The last line of stdout
+# is DATA_UUID=<uuid>, which the later install phases need.
+
+set -euo pipefail
+
+MP=/var/lib/spinifex
+LABEL=spinifex-data
+FSTAB_BAK=/etc/fstab.pre-spinifex
+MIN_BYTES="${MIN_DATA_BYTES:-100000000000}"
+WANT="${1:-}"
+
+die() { echo "STOP: $*" >&2; exit 1; }
+[ "$(id -u)" = 0 ] || die "run as root"
+
+# Resume: the mount is already there and is ours.
+if mp_uuid="$(findmnt --mountpoint "$MP" -no UUID 2>/dev/null)" && [ -n "$mp_uuid" ]; then
+    src="$(findmnt --mountpoint "$MP" -no SOURCE)"
+    [ "$(blkid -s LABEL -o value "$src")" = "$LABEL" ] || die "$MP is mounted from $src, which is not labelled $LABEL; not touching it"
+    grep -q "UUID=${mp_uuid}[[:space:]]" /etc/fstab || die "$MP is mounted but /etc/fstab has no UUID=$mp_uuid entry"
+    echo "already done: $MP is mounted from $src (UUID $mp_uuid)"
+    echo "DATA_UUID=$mp_uuid"
+    exit 0
+fi
+if grep -q "$MP" /etc/fstab; then die "/etc/fstab mentions $MP but nothing is mounted there; fix that by hand first"; fi
+[ ! -e "$MP" ] || [ -z "$(ls -A "$MP")" ] || die "$MP exists and is not empty"
+
+root_src="$(findmnt -no SOURCE /)" || die "cannot find the root source"
+root_anc="$(lsblk -s -nro NAME "$root_src")" || die "cannot read the root ancestry"
+[ -n "$root_anc" ] || die "empty root ancestry"
+
+# blank_reason ID prints why the disk is not a candidate and returns 1, or returns 0.
+blank_reason() {
+    local id="$1" dev name size kids hold sw mnt rc w
+    dev="$(readlink -e "$id")" || { echo "link does not resolve"; return 1; }
+    [ -b "$dev" ] || { echo "not a block device"; return 1; }
+    name="$(basename "$dev")"
+    if grep -qx "$name" <<<"$root_anc"; then echo "in the root ancestry"; return 1; fi
+    size="$(blockdev --getsize64 "$id")" || { echo "size unreadable"; return 1; }
+    [ "$size" -ge "$MIN_BYTES" ] || { echo "only $size bytes"; return 1; }
+    kids="$(lsblk -nro NAME "$id")" || { echo "children unreadable"; return 1; }
+    [ "$kids" = "$name" ] || { echo "has children"; return 1; }
+    hold="$(ls -A "/sys/block/$name/holders/")" || { echo "holders unreadable"; return 1; }
+    [ -z "$hold" ] || { echo "has holders"; return 1; }
+    sw="$(swapon --show=NAME --noheadings)" || { echo "swapon failed"; return 1; }
+    if grep -q "$name" <<<"$sw"; then echo "is swap"; return 1; fi
+    mnt="$(lsblk -nro MOUNTPOINTS "$id")" || { echo "mounts unreadable"; return 1; }
+    [ -z "${mnt//[[:space:]]/}" ] || { echo "is mounted"; return 1; }
+    set +e; blkid -p "$id" >/dev/null 2>&1; rc=$?; set -e
+    [ "$rc" -eq 2 ] || { echo "blkid -p says it has a signature (rc $rc)"; return 1; }
+    w="$(wipefs -n "$id")" || { echo "wipefs failed"; return 1; }
+    [ -z "$w" ] || { echo "wipefs finds signatures"; return 1; }
+    return 0
+}
+
+# choose_data_disk ID... prints the largest disk's ID, the lowest path among equal sizes, and says on
+# stderr which it left. The choice depends only on size and path, so every node of one plan agrees.
+choose_data_disk() {
+    local chosen rest
+    chosen="$(for id in "$@"; do printf '%s %s\n' "$(blockdev --getsize64 "$id")" "$id"; done |
+        sort -k1,1nr -k2,2 | head -n1)"
+    chosen="${chosen#* }"
+    if [ "$#" -gt 1 ]; then
+        rest="$(printf '%s\n' "$@" | grep -vxF "$chosen" | sort | tr '\n' ' ')"
+        echo "chose $chosen ($(blockdev --getsize64 "$chosen") bytes), the largest of $# blank disks; left untouched: ${rest% }" >&2
+    fi
+    printf '%s\n' "$chosen"
+}
+
+candidates=()
+shopt -s nullglob
+for id in /dev/disk/by-id/nvme-eui.*; do
+    case "$id" in *-part*) continue ;; esac
+    if [ -n "$WANT" ] && [ "$id" != "$WANT" ]; then continue; fi
+    if why="$(blank_reason "$id")"; then
+        candidates+=("$id")
+    else
+        echo "skip $id: $why"
+    fi
+done
+shopt -u nullglob
+
+if [ "${#candidates[@]}" -eq 0 ]; then
+    lsblk -o NAME,SIZE,TYPE,MODEL,SERIAL,FSTYPE,MOUNTPOINTS >&2 || true
+    die "no blank data disk among the by-id EUI disks"
+fi
+ID="$(choose_data_disk "${candidates[@]}")"
+DEV="$(readlink -e "$ID")"
+echo "CHECKS PASSED: $ID -> $DEV"
+
+mkdir -p "$MP"
+mkfs.ext4 -q -L "$LABEL" "$ID"
+U="$(blkid -p -o value -s UUID "$ID")" || die "blkid UUID failed"
+[ -n "$U" ] || die "no UUID after mkfs"
+[ "$(blkid -p -o value -s TYPE "$ID")" = ext4 ] || die "not ext4 after mkfs"
+
+NEW="$(mktemp /etc/fstab.spinifex.XXXXXX)"
+cp /etc/fstab "$NEW"
+echo "UUID=$U $MP ext4 defaults,nofail,x-systemd.device-timeout=30s 0 2" >> "$NEW"
+findmnt --verify --tab-file "$NEW" || { rm -f "$NEW"; die "staged fstab failed verify, /etc/fstab untouched"; }
+BAK="$FSTAB_BAK.$(date +%s)"
+cp -a /etc/fstab "$BAK"
+trap 'cp -a "$BAK" /etc/fstab; systemctl daemon-reload; echo "ROLLED BACK /etc/fstab from $BAK" >&2' EXIT
+chmod 644 "$NEW"
+mv "$NEW" /etc/fstab
+systemctl daemon-reload
+mount "$MP"
+[ "$(findmnt --mountpoint "$MP" -no UUID)" = "$U" ] || die "wrong UUID at $MP"
+[ "$(findmnt --mountpoint "$MP" -no FSTYPE)" = ext4 ] || die "wrong fstype at $MP"
+[ "$(findmnt --mountpoint "$MP" -no MAJ:MIN | tr -d ' ')" = "$(lsblk -dno MAJ:MIN "$ID" | tr -d ' ')" ] || die "wrong device at $MP"
+trap - EXIT
+findmnt --mountpoint "$MP" -o TARGET,SOURCE,MAJ:MIN,UUID,FSTYPE,OPTIONS
+echo "STORAGE OK"
+echo "DATA_UUID=$U"

scripts/terraform/latitude-spx/network.tf

@@ -0,0 +1,14 @@
+# A private network needs two or more servers, so a single node has none. The VLAN carries the cluster
+# and Geneve traffic; its address is set over SSH, since the VID is only known after apply.
+resource "latitudesh_virtual_network" "lan" {
+  count       = var.node_count > 1 ? 1 : 0
+  project     = local.project_id
+  site        = var.site
+  description = "spinifex-${var.deployment_name}"
+}
+
+resource "latitudesh_vlan_assignment" "node" {
+  count              = var.node_count > 1 ? var.node_count : 0
+  server_id          = latitudesh_server.node[count.index].id
+  virtual_network_id = latitudesh_virtual_network.lan[0].id
+}

scripts/terraform/latitude-spx/node-install-api-token.sh

@@ -0,0 +1,48 @@
+#!/bin/sh
+# Runs as root on a node. Reads the API token on stdin and installs it for the daemon.
+# The directory belongs to root and is not writable by anyone else, so no service can create or
+# swap an entry in it. The file belongs to the daemon's user alone (mode 0400): the other
+# services share the spinifex group, so group access would hand them the team-wide token. The
+# temporary file has an unpredictable name and is created exclusively. A symlink, or an owner
+# other than root or the daemon's user, where the directory or the file should be is refused.
+# Ownership and mode are set on every run, so an older install converges. The file's content is
+# replaced only when the token differs. Prints installed or unchanged.
+set -eu
+dir="${API_TOKEN_DIR:-/etc/spinifex/latitude}"
+root="${API_TOKEN_ROOT-root}"
+rootgroup="${API_TOKEN_ROOT_GROUP-root}"
+user="${API_TOKEN_USER-spinifex-daemon}"
+umask 077
+
+fail() { echo "$*" >&2; exit 1; }
+owner_of() { stat -c %U "$1"; }
+
+[ ! -L "$dir" ] || fail "$dir is a symlink"
+if [ ! -e "$dir" ]; then mkdir -p "$dir"; fi
+[ -d "$dir" ] || fail "$dir is not a directory"
+[ "$(owner_of "$dir")" = "$root" ] || fail "$dir is not owned by $root"
+chown "$root:$rootgroup" "$dir"
+chmod 0711 "$dir"
+
+target="$dir/api-token"
+[ ! -L "$target" ] || fail "$target is a symlink"
+if [ -e "$target" ]; then
+    [ -f "$target" ] || fail "$target is not a regular file"
+    holder="$(owner_of "$target")"
+    [ "$holder" = "$root" ] || [ "$holder" = "$user" ] || fail "$target is owned by $holder"
+fi
+
+tmp="$(mktemp "$dir/.api-token.XXXXXX")"
+trap 'rm -f "$tmp"' EXIT
+cat > "$tmp"
+[ -s "$tmp" ] || fail "empty token on stdin"
+if [ -f "$target" ] && cmp -s "$tmp" "$target"; then
+    chown "$user" "$target"
+    chmod 0400 "$target"
+    echo unchanged
+    exit 0
+fi
+chown "$user" "$tmp"
+chmod 0400 "$tmp"
+mv -f "$tmp" "$target"
+echo installed

scripts/terraform/latitude-spx/node-pool-state.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+# Runs as root on a node with the pool name as $1. Reads only the journal of the daemon's
+# current invocation, so a success logged before a restart cannot hide a failure after it.
+# Prints ready, refused or waiting.
+set -eu
+pool="${1:?pool name}"
+id="$(systemctl show -p InvocationID --value spinifex-daemon)"
+[ -n "$id" ] || { echo waiting; exit 0; }
+log="$(journalctl "_SYSTEMD_INVOCATION_ID=$id" -u spinifex-daemon --no-pager -o cat 2>/dev/null || true)"
+named() { grep -F -e "pool=$pool" -e "\"pool\":\"$pool\""; }
+if printf '%s\n' "$log" | grep -F "refused the pool's first call" | named >/dev/null; then
+    echo refused
+elif printf '%s\n' "$log" | grep -F "floating pool ready" | named >/dev/null; then
+    echo ready
+else
+    echo waiting
+fi

scripts/terraform/latitude-spx/node-scripts_test.sh

@@ -0,0 +1,119 @@
+#!/bin/sh
+# Tests node-install-api-token.sh and node-pool-state.sh with stand-in tools.
+set -eu
+here="$(cd "$(dirname "$0")" && pwd)"
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+fails=0
+check() { if [ "$2" = "$3" ]; then echo "ok   $1"; else echo "FAIL $1: want '$3' got '$2'"; fails=$((fails + 1)); fi; }
+
+# token install: A, A again, then B across a rotation; the file ends as B, owned by the daemon
+# user alone (0400) in a 0711 directory that only root may change
+me="$(id -un)"
+export API_TOKEN_DIR="$work/tok" API_TOKEN_ROOT="$me" API_TOKEN_ROOT_GROUP="$(id -gn)" API_TOKEN_USER="$me"
+install_token() { sh "$here/node-install-api-token.sh"; }
+check "first install" "$(printf 'TOKENA' | install_token)" installed
+check "same token" "$(printf 'TOKENA' | install_token)" unchanged
+check "rotation" "$(printf 'TOKENB' | install_token)" installed
+check "file holds B" "$(cat "$work/tok/api-token")" TOKENB
+check "file mode and owner" "$(stat -c '%U %a' "$work/tok/api-token")" "$me 400"
+check "dir mode and owner" "$(stat -c '%U %a' "$work/tok")" "$me 711"
+check "no temp left after install" "$(ls -A "$work/tok")" api-token
+check "empty refused" "$(printf '' | install_token 2>/dev/null || echo failed)" failed
+check "file kept after refusal" "$(cat "$work/tok/api-token")" TOKENB
+
+# an older install converges on the unchanged path too
+chmod 0640 "$work/tok/api-token"
+chmod 0755 "$work/tok"
+check "unchanged path repairs" "$(printf 'TOKENB' | install_token)" unchanged
+check "mode repaired on unchanged" "$(stat -c %a "$work/tok/api-token")" 400
+check "dir mode repaired on unchanged" "$(stat -c %a "$work/tok")" 711
+
+# who can read it: only the daemon's identity. This needs two real identities, so it runs as root only.
+if [ "$(id -u)" = 0 ]; then
+    chmod 0711 "$work"
+    export API_TOKEN_ROOT=root API_TOKEN_ROOT_GROUP=root API_TOKEN_USER=daemon
+    for mode in installed unchanged; do
+        [ "$mode" = installed ] && rm -f "$work/tok/api-token"
+        check "$mode path" "$(printf 'TOKENB' | install_token)" "$mode"
+        check "daemon reads ($mode)" "$(setpriv --reuid=daemon --regid=daemon --clear-groups cat "$work/tok/api-token")" TOKENB
+        check "another identity in the shared group cannot read ($mode)" \
+            "$(setpriv --reuid=nobody --regid=daemon --clear-groups cat "$work/tok/api-token" 2>/dev/null || echo denied)" denied
+    done
+    export API_TOKEN_ROOT="$me" API_TOKEN_ROOT_GROUP="$(id -gn)" API_TOKEN_USER="$me"
+else
+    echo "skip reading as the daemon and as another service: needs root"
+fi
+
+# a link planted where the file or the directory belongs is refused, and nothing it points at is touched
+echo SENTINEL > "$work/sentinel"
+rm -f "$work/tok/api-token"
+ln -s "$work/sentinel" "$work/tok/api-token"
+check "symlinked file refused" "$(printf 'TOKENC' | sh "$here/node-install-api-token.sh" 2>/dev/null || echo refused)" refused
+check "symlink target untouched" "$(cat "$work/sentinel")" SENTINEL
+ln -s "$work/tok" "$work/tok-link"
+check "symlinked dir refused" "$(printf 'TOKENC' | API_TOKEN_DIR="$work/tok-link" sh "$here/node-install-api-token.sh" 2>/dev/null || echo refused)" refused
+check "dir owned by someone else refused" "$(printf 'TOKENC' | API_TOKEN_ROOT=nobody-such install_token 2>/dev/null || echo refused)" refused
+rm -f "$work/tok/api-token"
+printf 'TOKENB' | install_token >/dev/null
+check "file owned by a stranger refused" "$(printf 'TOKENC' | API_TOKEN_ROOT=$me API_TOKEN_USER=nobody-such install_token 2>/dev/null || echo refused)" refused
+check "no temp left" "$(ls -A "$work/tok")" api-token
+
+# data disk choice: the largest blank disk, the lowest path among equals, the rest left alone
+choose_dir="$work/choose"
+mkdir -p "$choose_dir/bin"
+cat > "$choose_dir/bin/blockdev" <<'SH'
+#!/bin/sh
+# blockdev --getsize64 <id>: the fixture's size for that disk
+cat "$CHOOSE_DIR/size.$(basename "$2")"
+SH
+chmod +x "$choose_dir/bin/blockdev"
+eval "$(sed -n '/^choose_data_disk()/,/^}/p' "$here/host-data-disk.sh")"
+size_of() { printf '%s' "$2" > "$choose_dir/size.$1"; }
+pick() { CHOOSE_DIR="$choose_dir" PATH="$choose_dir/bin:$PATH" choose_data_disk "$@" 2>"$choose_dir/err"; }
+size_of nvme-eui.0b 1700000000000
+size_of nvme-eui.0a 1700000000000
+size_of nvme-eui.09 447000000000
+size_of nvme-eui.0c 1900000000000
+check "largest of three wins" "$(pick /dev/disk/by-id/nvme-eui.09 /dev/disk/by-id/nvme-eui.0b /dev/disk/by-id/nvme-eui.0c)" /dev/disk/by-id/nvme-eui.0c
+check "equal sizes: the lowest path" "$(pick /dev/disk/by-id/nvme-eui.09 /dev/disk/by-id/nvme-eui.0b /dev/disk/by-id/nvme-eui.0a)" /dev/disk/by-id/nvme-eui.0a
+check "order of the list does not matter" "$(pick /dev/disk/by-id/nvme-eui.0b /dev/disk/by-id/nvme-eui.0a /dev/disk/by-id/nvme-eui.09)" /dev/disk/by-id/nvme-eui.0a
+check "what was left is said" "$(grep -c 'left untouched: /dev/disk/by-id/nvme-eui.09 /dev/disk/by-id/nvme-eui.0b' "$choose_dir/err")" 1
+check "one disk is just chosen" "$(pick /dev/disk/by-id/nvme-eui.09)" /dev/disk/by-id/nvme-eui.09
+check "one disk says nothing" "$(wc -c < "$choose_dir/err" | tr -d ' ')" 0
+
+# pool state: the stand-in journal serves only the lines of the invocation asked for
+mkdir "$work/bin"
+cat > "$work/bin/systemctl" <<'SH'
+#!/bin/sh
+cat "$FAKE_DIR/invocation"
+SH
+cat > "$work/bin/journalctl" <<'SH'
+#!/bin/sh
+for a in "$@"; do
+    case "$a" in _SYSTEMD_INVOCATION_ID=*) id="${a#_SYSTEMD_INVOCATION_ID=}" ;; esac
+done
+cat "$FAKE_DIR/journal.$id" 2>/dev/null
+SH
+chmod +x "$work/bin/systemctl" "$work/bin/journalctl"
+export FAKE_DIR="$work" PATH="$work/bin:$PATH"
+state() { sh "$here/node-pool-state.sh" latitude; }
+
+echo old > "$work/invocation"
+echo 'INFO floating pool ready pool=latitude source=latitude' > "$work/journal.old"
+check "current success" "$(state)" ready
+
+echo new > "$work/invocation"
+echo 'ERROR floating: the provider refused the pool'"'"'s first call; public addresses will fail until fixed pool=latitude' > "$work/journal.new"
+check "old success then current failure" "$(state)" refused
+
+echo 'INFO starting' > "$work/journal.new"
+check "current invocation not yet ready" "$(state)" waiting
+
+echo 'INFO floating pool ready pool=other source=latitude' > "$work/journal.new"
+check "another pool does not count" "$(state)" waiting
+
+echo 'INFO floating pool ready pool=latitude source=latitude' > "$work/journal.new"
+check "current success" "$(state)" ready
+
+[ "$fails" -eq 0 ]

scripts/terraform/latitude-spx/outputs.tf

@@ -0,0 +1,56 @@
+output "deployment_name" {
+  value = var.deployment_name
+}
+
+output "site" {
+  value = var.site
+}
+
+output "project" {
+  value = local.project
+}
+
+# provider_host_id is the server ID. public_ip is the server's own /31 address, which SSH and the
+# Spinifex API use; the Elastic IP is separate.
+output "nodes" {
+  value = [for n in latitudesh_server.node : {
+    name             = trimprefix(n.hostname, "spx-${var.deployment_name}-")
+    provider_host_id = n.id
+    public_ip        = n.primary_ipv4
+  }]
+}
+
+# The first address, for a single node's static pool.
+output "elastic_ip" {
+  value = latitudesh_elastic_ip.pool[0].address
+}
+
+# IDs as well as addresses: destroy deletes only these IDs, and the floating pool lists them.
+output "elastic_ips" {
+  value = [for e in latitudesh_elastic_ip.pool : { id = e.id, address = e.address }]
+}
+
+# The VLAN ID of the cluster network; null for one node, which has no private network.
+output "vid" {
+  value = length(latitudesh_virtual_network.lan) == 0 ? null : latitudesh_virtual_network.lan[0].vid
+}
+
+output "ssh_key_id" {
+  value = latitudesh_ssh_key.deploy.id
+}
+
+output "user_data_id" {
+  value = latitudesh_user_data.host.id
+}
+
+output "project_id" {
+  value = local.project_id
+}
+
+output "project_created" {
+  value = length(latitudesh_project.deploy) > 0
+}
+
+output "virtual_network_id" {
+  value = length(latitudesh_virtual_network.lan) == 0 ? null : latitudesh_virtual_network.lan[0].id
+}

scripts/terraform/latitude-spx/provider.tf

@@ -0,0 +1,4 @@
+# The token comes from LATITUDESH_AUTH_TOKEN in the environment, which the provider reads
+# itself (its auth_token argument documents that variable). It is never a variable here, so it
+# is not written to the state or to a tfvars file. The default project is set per resource.
+provider "latitudesh" {}

scripts/terraform/latitude-spx/terraform.tfvars.example

@@ -0,0 +1,5 @@
+deployment_name     = "l1"
+site                = "DAL"
+plan                = "m4-metal-medium"
+node_count          = 1
+ssh_public_key_path = "~/.ssh/id_ed25519.pub"

scripts/terraform/latitude-spx/variables.tf

@@ -0,0 +1,63 @@
+variable "deployment_name" {
+  type        = string
+  description = "Names every resource and the server hostnames, so two deployments in one account never collide."
+  validation {
+    # A hostname is at most 32 characters: "spx-" + name + "-node1".
+    condition     = can(regex("^[a-z0-9][a-z0-9-]{0,15}$", var.deployment_name))
+    error_message = "deployment_name must be 1-16 lowercase letters, digits or hyphens."
+  }
+}
+
+variable "project" {
+  type        = string
+  default     = ""
+  description = "ID or slug of an existing latitude.sh project to deploy into. Empty creates a project spinifex-<deployment_name> and removes it on destroy."
+}
+
+variable "project_id" {
+  type        = string
+  default     = ""
+  description = "ID of the project named by project. The Elastic IP create sends it as project_id without resolving a slug (provider 4.8.0), so it must be an ID. Unused when project is empty."
+}
+
+variable "site" {
+  type        = string
+  default     = "DAL"
+  description = "latitude.sh site slug. Pick one with stock for the plan and Elastic IP support; not SAO."
+}
+
+variable "plan" {
+  type        = string
+  default     = "m4-metal-medium"
+  description = "Server plan slug (the pricing page calls it m4.metal.medium)."
+}
+
+variable "operating_system" {
+  type        = string
+  default     = "ubuntu_26_04_x64_lts"
+  description = "OS slug. UNVERIFIED: the 26.04 slug follows the 24.04 pattern (ubuntu_24_04_x64_lts) and is checked by a data source at plan time."
+}
+
+variable "node_count" {
+  type    = number
+  default = 1
+  validation {
+    condition     = contains([1, 3], var.node_count)
+    error_message = "node_count must be 1 or 3."
+  }
+}
+
+variable "elastic_ip_count" {
+  type        = number
+  default     = 1
+  description = "Elastic IPs to buy, each 4 USD a month. Every one starts on a server and keeps it unless Spinifex moves it. latitude.sh allows 5 per team."
+  validation {
+    condition     = var.elastic_ip_count >= 1 && var.elastic_ip_count <= 5 && floor(var.elastic_ip_count) == var.elastic_ip_count
+    error_message = "elastic_ip_count must be a whole number from 1 to 5."
+  }
+}
+
+variable "ssh_public_key_path" {
+  type    = string
+  default = "~/.ssh/id_ed25519.pub"
+}

scripts/terraform/latitude-spx/versions.tf

@@ -0,0 +1,7 @@
+terraform {
+  required_version = ">= 1.5.0"
+  required_providers {
+    # Pinned exactly: 4.8.0 is the version whose schema these files were written against.
+    latitudesh = { source = "latitudesh/latitudesh", version = "= 4.8.0" }
+  }
+}

spinifex/agents/ecs/agent/agent.go

@@ -12,8 +12,9 @@ import (
 	"strings"
 	"time"
 
+	"github.com/aws/aws-sdk-go-v2/aws"
 	ecsv1 "github.com/mulgadc/spinifex/contracts/ecs/v1"
-	"github.com/mulgadc/spinifex/spinifex/agents/ecs/credentials"
+	"github.com/mulgadc/spinifex/internal/imdscreds"
 	ctrruntime "github.com/mulgadc/spinifex/spinifex/agents/ecs/runtime"
 )
 
@@ -102,7 +103,9 @@ func New(cfg Config) (*Agent, error) {
 		AgentVersion: cfg.AgentVersion,
 	}
 
-	creds := credentials.NewIMDSProvider(imdsClient, cfg.IMDSBase)
+	// The cache refetches only once the real expiry passes, and a failed
+	// refresh is an error rather than an extended expiry.
+	creds := aws.NewCredentialsCache(imdscreds.NewProvider(imdsClient, cfg.IMDSBase))
 	resolver := newLazyECRResolver(creds, cfg.Region, cfg.GatewayURL, cfg.GatewayCA)
 
 	// A dial that fails here is not fatal and not final: the node starts the

spinifex/agents/ecs/agent/config.go

@@ -21,17 +21,14 @@ const (
 
 // Config holds the static settings the agent reads at boot. Cluster identity
 // (account ID, instance ID) is discovered at runtime from IMDS, not configured;
-// only the cluster *name* the instance was launched into is static. AccessKey /
-// SecretKey are legacy seeded creds, optional now that the agent SigV4-signs
-// gateway calls with instance-role credentials from IMDS; the agent never holds
-// a NATS token.
+// only the cluster *name* the instance was launched into is static. The agent
+// SigV4-signs gateway calls with instance-role credentials from IMDS and never
+// holds a NATS token.
 type Config struct {
 	GatewayURL       string
 	GatewayCA        string
 	Region           string
 	ClusterName      string
-	AccessKey        string
-	SecretKey        string
 	IMDSBase         string
 	ContainerdSocket string
 	Heartbeat        time.Duration
@@ -53,8 +50,6 @@ func LoadConfig(envFile string) Config {
 		GatewayCA:        get("ECS_GATEWAY_CA"),
 		Region:           get("ECS_REGION"),
 		ClusterName:      get("ECS_CLUSTER"),
-		AccessKey:        get("ECS_ACCESS_KEY"),
-		SecretKey:        get("ECS_SECRET_KEY"),
 		IMDSBase:         get("ECS_IMDS_BASE"),
 		ContainerdSocket: get("ECS_CONTAINERD_SOCKET"),
 	}

spinifex/agents/ecs/agent/config_test.go

@@ -10,7 +10,7 @@ import (
 func TestLoadConfig_Defaults(t *testing.T) {
 	// Ensure env vars don't leak in from the host.
 	for _, k := range []string{"ECS_GATEWAY_URL", "ECS_GATEWAY_CA", "ECS_REGION",
-		"ECS_CLUSTER", "ECS_ACCESS_KEY", "ECS_SECRET_KEY", "ECS_IMDS_BASE",
+		"ECS_CLUSTER", "ECS_IMDS_BASE",
 		"ECS_CONTAINERD_SOCKET", "ECS_HEARTBEAT_INTERVAL", "ECS_POLL_INTERVAL"} {
 		t.Setenv(k, "")
 	}
@@ -43,7 +43,6 @@ func TestLoadConfig_FileThenEnvOverride(t *testing.T) {
 		t.Fatal(err)
 	}
 	t.Setenv("ECS_GATEWAY_URL", "https://gw.env")
-	t.Setenv("ECS_ACCESS_KEY", "AKIAENV")
 
 	cfg := LoadConfig(envFile)
 	if cfg.GatewayURL != "https://gw.env" {
@@ -55,9 +54,6 @@ func TestLoadConfig_FileThenEnvOverride(t *testing.T) {
 	if cfg.ClusterName != "prod" {
 		t.Errorf("ClusterName = %q, want from file", cfg.ClusterName)
 	}
-	if cfg.AccessKey != "AKIAENV" {
-		t.Errorf("AccessKey = %q, want env", cfg.AccessKey)
-	}
 }
 
 func TestLoadConfig_HeartbeatOverride(t *testing.T) {

spinifex/agents/ecs/agent/controlplane.go

@@ -1,17 +1,17 @@
 package agent
 
 import (
-	"context"
 	"encoding/json"
 	"fmt"
 	"time"
 
+	awsv2 "github.com/aws/aws-sdk-go-v2/aws"
 	"github.com/aws/aws-sdk-go/aws"
 	"github.com/aws/aws-sdk-go/service/ecs"
 
 	ecsv1 "github.com/mulgadc/spinifex/contracts/ecs/v1"
 	"github.com/mulgadc/spinifex/internal/ecsgw"
-	"github.com/mulgadc/spinifex/spinifex/agents/ecs/credentials"
+	"github.com/mulgadc/spinifex/internal/gwsign"
 	ecsdomain "github.com/mulgadc/spinifex/spinifex/domains/ecs"
 )
 
@@ -47,26 +47,14 @@ const pollTimeout = 30 * time.Second
 
 // newGatewayControlPlane builds the SigV4 client signing with the instance-role
 // credentials from IMDS (fetched per call so rotation is transparent) + pinned CA.
-func newGatewayControlPlane(cfg Config, creds credentials.CredentialsProvider) (*gatewayControlPlane, error) {
-	client, err := ecsgw.New(cfg.GatewayURL, cfg.GatewayCA, credentialsFunc(creds), cfg.Region, pollTimeout)
+func newGatewayControlPlane(cfg Config, creds awsv2.CredentialsProvider) (*gatewayControlPlane, error) {
+	client, err := ecsgw.New(cfg.GatewayURL, cfg.GatewayCA, gwsign.New(creds), cfg.Region, pollTimeout)
 	if err != nil {
 		return nil, err
 	}
 	return &gatewayControlPlane{client: client}, nil
 }
 
-// credentialsFunc adapts the agent's IMDS CredentialsProvider to the ecsgw
-// per-call credentials hook.
-func credentialsFunc(p credentials.CredentialsProvider) ecsgw.CredentialsFunc {
-	return func(ctx context.Context) (string, string, string, error) {
-		c, err := p.Retrieve(ctx)
-		if err != nil {
-			return "", "", "", err
-		}
-		return c.AccessKeyID, c.SecretAccessKey, c.SessionToken, nil
-	}
-}
-
 func (g *gatewayControlPlane) Register(id identity) error {
 	in := &ecs.RegisterContainerInstanceInput{
 		Cluster:                  aws.String(id.ClusterName),

spinifex/agents/ecs/agent/controlplane_test.go

@@ -8,17 +8,17 @@ import (
 	"net/http/httptest"
 	"testing"
 
+	"github.com/aws/aws-sdk-go-v2/aws"
 	"github.com/aws/aws-sdk-go/service/ecs"
-	"github.com/mulgadc/spinifex/spinifex/agents/ecs/credentials"
 	ecsdomain "github.com/mulgadc/spinifex/spinifex/domains/ecs"
 )
 
-// fixedCredsProvider is a static credentials.CredentialsProvider for tests
+// fixedCredsProvider is a static aws.CredentialsProvider for tests
 // that only need a valid SigV4 signature, not real IMDS rotation.
 type fixedCredsProvider struct{}
 
-func (fixedCredsProvider) Retrieve(context.Context) (credentials.Credentials, error) {
-	return credentials.Credentials{AccessKeyID: "AKIATEST", SecretAccessKey: "secret"}, nil
+func (fixedCredsProvider) Retrieve(context.Context) (aws.Credentials, error) {
+	return aws.Credentials{AccessKeyID: "AKIATEST", SecretAccessKey: "secret"}, nil
 }
 
 func newTestGatewayControlPlane(t *testing.T, srv *httptest.Server) *gatewayControlPlane {

spinifex/agents/ecs/agent/credendpoint.go

@@ -13,9 +13,9 @@ import (
 	"sync"
 	"time"
 
+	"github.com/aws/aws-sdk-go-v2/aws"
 	"github.com/mulgadc/spinifex/internal/ecrauth"
 	"github.com/mulgadc/spinifex/internal/stsauth"
-	"github.com/mulgadc/spinifex/spinifex/agents/ecs/credentials"
 )
 
 const (
@@ -56,7 +56,7 @@ type credRole struct {
 
 type credEntry struct {
 	roleARN string
-	creds   stsauth.Credentials
+	creds   aws.Credentials
 }
 
 // credEndpoint is the host-netns HTTP server that hands a task its IAM role
@@ -64,7 +64,7 @@ type credEntry struct {
 // mints/caches credentials on demand by assuming the role over the gateway with
 // the agent's instance credentials.
 type credEndpoint struct {
-	provider   credentials.CredentialsProvider
+	provider   aws.CredentialsProvider
 	region     string
 	gatewayURL string
 	caPath     string
@@ -75,7 +75,7 @@ type credEndpoint struct {
 
 	// assume mints fresh credentials for a role; defaults to AssumeRole over the
 	// gateway and is overridable in tests.
-	assume func(ctx context.Context, roleARN, sessionName string) (stsauth.Credentials, error)
+	assume func(ctx context.Context, roleARN, sessionName string) (aws.Credentials, error)
 
 	mu         sync.Mutex
 	roles      map[string]credRole  // credID -> task role
@@ -89,7 +89,7 @@ type credEndpoint struct {
 // newCredEndpoint builds the endpoint. An empty ip/port falls back to the
 // AWS-reserved 169.254.170.2:80; tests pass loopback + an ephemeral port. run
 // adds the link-local address to the dummy interface (real or fake).
-func newCredEndpoint(provider credentials.CredentialsProvider, region, gatewayURL, caPath, ip string, port int, run netCmdRunner) *credEndpoint {
+func newCredEndpoint(provider aws.CredentialsProvider, region, gatewayURL, caPath, ip string, port int, run netCmdRunner) *credEndpoint {
 	if ip == "" {
 		ip = defaultCredEndpointIP
 	}
@@ -165,7 +165,7 @@ func (c *credEndpoint) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		AccessKeyID:     creds.AccessKeyID,
 		SecretAccessKey: creds.SecretAccessKey,
 		Token:           creds.SessionToken,
-		Expiration:      creds.Expiration.UTC().Format(time.RFC3339),
+		Expiration:      creds.Expires.UTC().Format(time.RFC3339),
 	}); err != nil {
 		slog.Warn("ecs-agent: encode credential response", "task", role.taskID, "err", err)
 	}
@@ -176,12 +176,12 @@ var errUnknownCredID = fmt.Errorf("unknown credId")
 
 // fetch returns valid credentials for credID, reusing the cache until within the
 // refresh margin and otherwise assuming the task role over the gateway.
-func (c *credEndpoint) fetch(ctx context.Context, credID string) (stsauth.Credentials, credRole, error) {
+func (c *credEndpoint) fetch(ctx context.Context, credID string) (aws.Credentials, credRole, error) {
 	c.mu.Lock()
 	role, known := c.roles[credID]
 	if !known {
 		c.mu.Unlock()
-		return stsauth.Credentials{}, credRole{}, errUnknownCredID
+		return aws.Credentials{}, credRole{}, errUnknownCredID
 	}
 	if e, ok := c.cache[credID]; ok && e.roleARN == role.roleARN && credValid(e.creds, credRefreshMargin) {
 		c.mu.Unlock()
@@ -191,7 +191,7 @@ func (c *credEndpoint) fetch(ctx context.Context, credID string) (stsauth.Creden
 
 	creds, err := c.assume(ctx, role.roleARN, sessionName(role.taskID))
 	if err != nil {
-		return stsauth.Credentials{}, role, err
+		return aws.Credentials{}, role, err
 	}
 
 	c.mu.Lock()
@@ -204,7 +204,7 @@ func (c *credEndpoint) fetch(ctx context.Context, credID string) (stsauth.Creden
 // roleARN over the gateway — the execution-role path for ECR image pulls. It
 // caches the assumed set and re-assumes within the refresh margin. session scopes
 // the STS session name.
-func (c *credEndpoint) AssumeProvider(roleARN, session string) credentials.CredentialsProvider {
+func (c *credEndpoint) AssumeProvider(roleARN, session string) aws.CredentialsProvider {
 	return &assumeProvider{ep: c, roleARN: roleARN, session: session}
 }
 
@@ -216,39 +216,34 @@ type assumeProvider struct {
 	session string
 
 	mu     sync.Mutex
-	cached stsauth.Credentials
+	cached aws.Credentials
 }
 
-var _ credentials.CredentialsProvider = (*assumeProvider)(nil)
+var _ aws.CredentialsProvider = (*assumeProvider)(nil)
 
-func (p *assumeProvider) Retrieve(ctx context.Context) (credentials.Credentials, error) {
+func (p *assumeProvider) Retrieve(ctx context.Context) (aws.Credentials, error) {
 	p.mu.Lock()
 	defer p.mu.Unlock()
 	if !credValid(p.cached, credRefreshMargin) {
 		creds, err := p.ep.assume(ctx, p.roleARN, p.session)
 		if err != nil {
-			return credentials.Credentials{}, err
+			return aws.Credentials{}, err
 		}
 		p.cached = creds
 	}
-	return credentials.Credentials{
-		AccessKeyID:     p.cached.AccessKeyID,
-		SecretAccessKey: p.cached.SecretAccessKey,
-		SessionToken:    p.cached.SessionToken,
-		Expiration:      p.cached.Expiration,
-	}, nil
+	return p.cached, nil
 }
 
 // assumeOverGateway mints credentials for roleARN by SigV4-signing AssumeRole
 // against the gateway with the agent's instance credentials.
-func (c *credEndpoint) assumeOverGateway(ctx context.Context, roleARN, sessionName string) (stsauth.Credentials, error) {
+func (c *credEndpoint) assumeOverGateway(ctx context.Context, roleARN, sessionName string) (aws.Credentials, error) {
 	instCreds, err := c.provider.Retrieve(ctx)
 	if err != nil {
-		return stsauth.Credentials{}, fmt.Errorf("instance credentials: %w", err)
+		return aws.Credentials{}, fmt.Errorf("instance credentials: %w", err)
 	}
 	client, err := c.client()
 	if err != nil {
-		return stsauth.Credentials{}, err
+		return aws.Credentials{}, err
 	}
 	return stsauth.AssumeRole(c.region, c.gatewayURL, client,
 		instCreds.AccessKeyID, instCreds.SecretAccessKey, instCreds.SessionToken,
@@ -387,14 +382,14 @@ func (c *credEndpoint) delEndpointAddr() {
 }
 
 // credValid reports whether creds are usable now with margin to spare.
-func credValid(c stsauth.Credentials, margin time.Duration) bool {
+func credValid(c aws.Credentials, margin time.Duration) bool {
 	if c.AccessKeyID == "" || c.SecretAccessKey == "" {
 		return false
 	}
-	if c.Expiration.IsZero() {
+	if c.Expires.IsZero() {
 		return true
 	}
-	return time.Now().Add(margin).Before(c.Expiration)
+	return time.Now().Add(margin).Before(c.Expires)
 }
 
 // sessionName derives an AssumeRole RoleSessionName from the task ID, satisfying the

spinifex/agents/ecs/agent/credendpoint_test.go

@@ -9,15 +9,15 @@ import (
 	"testing"
 	"time"
 
-	"github.com/mulgadc/spinifex/internal/stsauth"
+	"github.com/aws/aws-sdk-go-v2/aws"
 )
 
 // newTestCredEndpoint builds an endpoint whose assume seam returns canned creds,
 // counting calls so cache behaviour is observable. run is nil (no iface plumbing).
-func newTestCredEndpoint(creds stsauth.Credentials) (*credEndpoint, *int32) {
+func newTestCredEndpoint(creds aws.Credentials) (*credEndpoint, *int32) {
 	c := newCredEndpoint(nil, "us-east-1", "https://gw", "", "127.0.0.1", 0, nil)
 	var calls int32
-	c.assume = func(ctx context.Context, roleARN, sessionName string) (stsauth.Credentials, error) {
+	c.assume = func(ctx context.Context, roleARN, sessionName string) (aws.Credentials, error) {
 		atomic.AddInt32(&calls, 1)
 		return creds, nil
 	}
@@ -26,8 +26,8 @@ func newTestCredEndpoint(creds stsauth.Credentials) (*credEndpoint, *int32) {
 
 func TestCredEndpoint_ServesRegisteredCredID(t *testing.T) {
 	exp := time.Now().Add(time.Hour).UTC().Truncate(time.Second)
-	c, _ := newTestCredEndpoint(stsauth.Credentials{
-		AccessKeyID: "AKIA", SecretAccessKey: "secret", SessionToken: "tok", Expiration: exp,
+	c, _ := newTestCredEndpoint(aws.Credentials{
+		AccessKeyID: "AKIA", SecretAccessKey: "secret", SessionToken: "tok", Expires: exp,
 	})
 	c.Register("cred-1", "task-1", "arn:aws:iam::111122223333:role/task")
 
@@ -54,11 +54,11 @@ func TestCredEndpoint_ServesRegisteredCredID(t *testing.T) {
 // The STS session name lands in the assumed-role ARN and in STS logs, so it is
 // built from the public task ID and never from the secret credID.
 func TestCredEndpoint_SessionNameIsTaskIDNotCredID(t *testing.T) {
-	c, _ := newTestCredEndpoint(stsauth.Credentials{})
+	c, _ := newTestCredEndpoint(aws.Credentials{})
 	var gotSession string
-	c.assume = func(ctx context.Context, roleARN, session string) (stsauth.Credentials, error) {
+	c.assume = func(ctx context.Context, roleARN, session string) (aws.Credentials, error) {
 		gotSession = session
-		return stsauth.Credentials{AccessKeyID: "AKIA", SecretAccessKey: "secret"}, nil
+		return aws.Credentials{AccessKeyID: "AKIA", SecretAccessKey: "secret"}, nil
 	}
 	c.Register("secret-cred", "task-1", "arn:role")
 	rr := httptest.NewRecorder()
@@ -72,7 +72,7 @@ func TestCredEndpoint_SessionNameIsTaskIDNotCredID(t *testing.T) {
 }
 
 func TestCredEndpoint_UnknownCredIDIs404(t *testing.T) {
-	c, calls := newTestCredEndpoint(stsauth.Credentials{AccessKeyID: "x", SecretAccessKey: "y"})
+	c, calls := newTestCredEndpoint(aws.Credentials{AccessKeyID: "x", SecretAccessKey: "y"})
 	rr := httptest.NewRecorder()
 	c.ServeHTTP(rr, httptest.NewRequest(http.MethodGet, "/v2/credentials/nope", nil))
 	if rr.Code != http.StatusNotFound {
@@ -84,7 +84,7 @@ func TestCredEndpoint_UnknownCredIDIs404(t *testing.T) {
 }
 
 func TestCredEndpoint_WrongMethodIs405(t *testing.T) {
-	c, _ := newTestCredEndpoint(stsauth.Credentials{AccessKeyID: "x", SecretAccessKey: "y"})
+	c, _ := newTestCredEndpoint(aws.Credentials{AccessKeyID: "x", SecretAccessKey: "y"})
 	c.Register("cred-1", "task-1", "arn:role")
 	rr := httptest.NewRecorder()
 	c.ServeHTTP(rr, httptest.NewRequest(http.MethodPost, "/v2/credentials/cred-1", nil))
@@ -94,8 +94,8 @@ func TestCredEndpoint_WrongMethodIs405(t *testing.T) {
 }
 
 func TestCredEndpoint_CachesUntilExpiry(t *testing.T) {
-	c, calls := newTestCredEndpoint(stsauth.Credentials{
-		AccessKeyID: "AKIA", SecretAccessKey: "secret", Expiration: time.Now().Add(time.Hour),
+	c, calls := newTestCredEndpoint(aws.Credentials{
+		AccessKeyID: "AKIA", SecretAccessKey: "secret", Expires: time.Now().Add(time.Hour),
 	})
 	c.Register("cred-1", "task-1", "arn:role")
 	for hit := range 3 {
@@ -112,8 +112,8 @@ func TestCredEndpoint_CachesUntilExpiry(t *testing.T) {
 
 func TestCredEndpoint_RefreshesNearExpiry(t *testing.T) {
 	// Expiry inside the refresh margin -> every hit re-assumes.
-	c, calls := newTestCredEndpoint(stsauth.Credentials{
-		AccessKeyID: "AKIA", SecretAccessKey: "secret", Expiration: time.Now().Add(time.Minute),
+	c, calls := newTestCredEndpoint(aws.Credentials{
+		AccessKeyID: "AKIA", SecretAccessKey: "secret", Expires: time.Now().Add(time.Minute),
 	})
 	c.Register("cred-1", "task-1", "arn:role")
 	for range 2 {
@@ -126,7 +126,7 @@ func TestCredEndpoint_RefreshesNearExpiry(t *testing.T) {
 }
 
 func TestCredEndpoint_DeregisterDropsCredID(t *testing.T) {
-	c, _ := newTestCredEndpoint(stsauth.Credentials{AccessKeyID: "x", SecretAccessKey: "y"})
+	c, _ := newTestCredEndpoint(aws.Credentials{AccessKeyID: "x", SecretAccessKey: "y"})
 	c.Register("cred-1", "task-1", "arn:role")
 	c.Deregister("cred-1")
 	rr := httptest.NewRecorder()
@@ -137,9 +137,9 @@ func TestCredEndpoint_DeregisterDropsCredID(t *testing.T) {
 }
 
 func TestCredEndpoint_AssumeFailureIs502(t *testing.T) {
-	c, _ := newTestCredEndpoint(stsauth.Credentials{})
-	c.assume = func(ctx context.Context, roleARN, sessionName string) (stsauth.Credentials, error) {
-		return stsauth.Credentials{}, context.DeadlineExceeded
+	c, _ := newTestCredEndpoint(aws.Credentials{})
+	c.assume = func(ctx context.Context, roleARN, sessionName string) (aws.Credentials, error) {
+		return aws.Credentials{}, context.DeadlineExceeded
 	}
 	c.Register("cred-1", "task-1", "arn:role")
 	rr := httptest.NewRecorder()
@@ -150,8 +150,8 @@ func TestCredEndpoint_AssumeFailureIs502(t *testing.T) {
 }
 
 func TestCredEndpoint_StartServesOverLoopback(t *testing.T) {
-	c, _ := newTestCredEndpoint(stsauth.Credentials{
-		AccessKeyID: "AKIA", SecretAccessKey: "secret", Expiration: time.Now().Add(time.Hour),
+	c, _ := newTestCredEndpoint(aws.Credentials{
+		AccessKeyID: "AKIA", SecretAccessKey: "secret", Expires: time.Now().Add(time.Hour),
 	})
 	c.Register("cred-1", "task-1", "arn:role")
 	c.port = 0 // bind an ephemeral port instead of privileged 80

spinifex/agents/ecs/agent/credinject_test.go

@@ -5,7 +5,7 @@ import (
 	"net/http/httptest"
 	"testing"
 
-	"github.com/mulgadc/spinifex/internal/stsauth"
+	"github.com/aws/aws-sdk-go-v2/aws"
 
 	ecsv1 "github.com/mulgadc/spinifex/contracts/ecs/v1"
 )
@@ -30,7 +30,7 @@ func TestTaskCredID(t *testing.T) {
 // The task ID is public (it is the task ARN suffix), so naming another task's ID
 // at the credential endpoint must not yield that task's role.
 func TestRegisterTaskCreds_TaskIDDoesNotServeCredentials(t *testing.T) {
-	c, _ := newTestCredEndpoint(stsauth.Credentials{AccessKeyID: "AKIA", SecretAccessKey: "secret"})
+	c, _ := newTestCredEndpoint(aws.Credentials{AccessKeyID: "AKIA", SecretAccessKey: "secret"})
 	a := Agent{cred: c}
 	get := func(id string) int {
 		rr := httptest.NewRecorder()

spinifex/agents/ecs/agent/doc.go

@@ -5,8 +5,7 @@
 // task assignments, runs them through containerd, and reports state back over
 // the gateway.
 //
-// Static config (gateway URL, CA, region, cluster, seeded IAM creds, containerd
-// socket) is read from the cloud-init env file /etc/spinifex-ecs/agent.env
+// Static config (gateway URL, CA, region, cluster, containerd socket) is read from the cloud-init env file /etc/spinifex-ecs/agent.env
 // (KEY=value); real env vars override it. Host identity (account, instance, AZ)
 // comes from IMDS at boot.
 package agent

spinifex/agents/ecs/agent/ecrresolver.go

@@ -7,8 +7,8 @@ import (
 	"strings"
 	"sync"
 
+	"github.com/aws/aws-sdk-go-v2/aws"
 	"github.com/mulgadc/spinifex/internal/ecrauth"
-	"github.com/mulgadc/spinifex/spinifex/agents/ecs/credentials"
 	"github.com/mulgadc/spinifex/spinifex/agents/ecs/runtime"
 )
 
@@ -22,7 +22,7 @@ import (
 // pulled, so the agent can still register + heartbeat on a host with absent or
 // wrong ECR config.
 type ecrResolver struct {
-	creds      credentials.CredentialsProvider
+	creds      aws.CredentialsProvider
 	region     string
 	gatewayURL string
 	caPath     string
@@ -35,13 +35,13 @@ var _ runtime.Resolver = (*ecrResolver)(nil)
 
 // newECRResolver builds a resolver with an injected HTTP client (tests). The
 // client is used as-is and never rebuilt from caPath.
-func newECRResolver(creds credentials.CredentialsProvider, region, gatewayURL string, httpClient *http.Client) *ecrResolver {
+func newECRResolver(creds aws.CredentialsProvider, region, gatewayURL string, httpClient *http.Client) *ecrResolver {
 	return &ecrResolver{creds: creds, region: region, gatewayURL: gatewayURL, httpClient: httpClient}
 }
 
 // newLazyECRResolver builds a resolver that constructs its gateway HTTP client
 // from caPath on first use (production path).
-func newLazyECRResolver(creds credentials.CredentialsProvider, region, gatewayURL, caPath string) *ecrResolver {
+func newLazyECRResolver(creds aws.CredentialsProvider, region, gatewayURL, caPath string) *ecrResolver {
 	return &ecrResolver{creds: creds, region: region, gatewayURL: gatewayURL, caPath: caPath}
 }
 

spinifex/agents/ecs/agent/ecrresolver_test.go

@@ -14,16 +14,16 @@ import (
 	"testing"
 	"time"
 
-	"github.com/mulgadc/spinifex/spinifex/agents/ecs/credentials"
+	"github.com/aws/aws-sdk-go-v2/aws"
 )
 
-// stubCreds is a credentials.CredentialsProvider returning fixed creds or error.
+// stubCreds is a aws.CredentialsProvider returning fixed creds or error.
 type stubCreds struct {
-	c   credentials.Credentials
+	c   aws.Credentials
 	err error
 }
 
-func (s stubCreds) Retrieve(context.Context) (credentials.Credentials, error) {
+func (s stubCreds) Retrieve(context.Context) (aws.Credentials, error) {
 	return s.c, s.err
 }
 
@@ -58,9 +58,9 @@ func trusting(srv *httptest.Server) *http.Client {
 
 func TestECRResolver_Authorize(t *testing.T) {
 	srv := gatewayStub(t, "AWS:jwt", "https://123456789012.dkr.ecr.us-east-1.spinifex.internal", http.StatusOK)
-	creds := stubCreds{c: credentials.Credentials{
+	creds := stubCreds{c: aws.Credentials{
 		AccessKeyID: "AKIA", SecretAccessKey: "secret", SessionToken: "sess",
-		Expiration: time.Now().Add(time.Hour),
+		Expires: time.Now().Add(time.Hour),
 	}}
 	r := newECRResolver(creds, "us-east-1", srv.URL, trusting(srv))
 
@@ -85,7 +85,7 @@ func TestECRResolver_CredsError(t *testing.T) {
 
 func TestECRResolver_GatewayError(t *testing.T) {
 	srv := gatewayStub(t, "", "", http.StatusInternalServerError)
-	creds := stubCreds{c: credentials.Credentials{AccessKeyID: "A", SecretAccessKey: "B"}}
+	creds := stubCreds{c: aws.Credentials{AccessKeyID: "A", SecretAccessKey: "B"}}
 	r := newECRResolver(creds, "us-east-1", srv.URL, trusting(srv))
 	if _, _, _, err := r.Authorize(context.Background(), "123456789012.dkr.ecr.us-east-1.spinifex.internal/app:1"); err == nil {
 		t.Fatal("expected gateway error")
@@ -93,7 +93,7 @@ func TestECRResolver_GatewayError(t *testing.T) {
 }
 
 func TestECRResolver_LazyClient_BadCADeferredToAuthorize(t *testing.T) {
-	creds := stubCreds{c: credentials.Credentials{AccessKeyID: "A", SecretAccessKey: "B"}}
+	creds := stubCreds{c: aws.Credentials{AccessKeyID: "A", SecretAccessKey: "B"}}
 	// Construction with a bogus CA path must not fail — only Authorize does.
 	r := newLazyECRResolver(creds, "us-east-1", "https://gw", filepath.Join(t.TempDir(), "absent.pem"))
 	if _, _, _, err := r.Authorize(context.Background(), "123456789012.dkr.ecr.us-east-1.spinifex.internal/app:1"); err == nil {
@@ -141,9 +141,9 @@ func TestIsECRRef(t *testing.T) {
 // registry, even though it lacks a ".dkr.ecr." name.
 func TestECRResolver_Authorize_BareHostGateway(t *testing.T) {
 	srv := gatewayStub(t, "AWS:jwt", "https://192.168.1.13:9999", http.StatusOK)
-	creds := stubCreds{c: credentials.Credentials{
+	creds := stubCreds{c: aws.Credentials{
 		AccessKeyID: "AKIA", SecretAccessKey: "secret", SessionToken: "sess",
-		Expiration: time.Now().Add(time.Hour),
+		Expires: time.Now().Add(time.Hour),
 	}}
 	r := newECRResolver(creds, "us-east-1", srv.URL, trusting(srv))
 

spinifex/agents/ecs/credentials/imds.go

@@ -1,41 +0,0 @@
-package credentials
-
-import (
-	"context"
-	"net/http"
-
-	"github.com/aws/aws-sdk-go-v2/aws"
-	"github.com/mulgadc/spinifex/internal/imdscreds"
-)
-
-// IMDSProvider fetches instance-role credentials from IMDS via the AWS SDK's
-// EC2 IMDS client and ec2rolecreds provider, cached with aws.CredentialsCache,
-// which refetches once the real expiry passes. A failed refresh is an error
-// here, not an extended expiry. Safe for concurrent use.
-type IMDSProvider struct {
-	cache *aws.CredentialsCache
-}
-
-var _ CredentialsProvider = (*IMDSProvider)(nil)
-
-// NewIMDSProvider builds a provider against the given IMDS base URL (e.g.
-// "http://169.254.169.254/latest"). A nil client uses the SDK IMDS client's
-// default HTTP client.
-func NewIMDSProvider(client *http.Client, base string) *IMDSProvider {
-	provider := imdscreds.NewProvider(client, base)
-	return &IMDSProvider{cache: aws.NewCredentialsCache(provider)}
-}
-
-// Retrieve returns cached credentials when still valid, else fetches fresh ones.
-func (p *IMDSProvider) Retrieve(ctx context.Context) (Credentials, error) {
-	creds, err := p.cache.Retrieve(ctx)
-	if err != nil {
-		return Credentials{}, err
-	}
-	return Credentials{
-		AccessKeyID:     creds.AccessKeyID,
-		SecretAccessKey: creds.SecretAccessKey,
-		SessionToken:    creds.SessionToken,
-		Expiration:      creds.Expires,
-	}, nil
-}

spinifex/agents/ecs/credentials/imds_test.go

@@ -1,164 +0,0 @@
-package credentials
-
-import (
-	"context"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"sync/atomic"
-	"testing"
-	"time"
-)
-
-// imdsStub serves the IMDSv2 token + role + credentials endpoints under the
-// real /latest prefix the SDK IMDS client always requests.
-func imdsStub(t *testing.T, hits *int32, creds map[string]string) *httptest.Server {
-	t.Helper()
-	mux := http.NewServeMux()
-	mux.HandleFunc("/latest/api/token", func(w http.ResponseWriter, r *http.Request) {
-		// Real IMDS echoes the requested TTL back as a response header; the SDK
-		// client parses it from there, not the body.
-		w.Header().Set("X-Aws-Ec2-Metadata-Token-Ttl-Seconds", "21600")
-		_, _ = w.Write([]byte("v2-token"))
-	})
-	mux.HandleFunc("/latest/meta-data/iam/security-credentials/", func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path == "/latest/meta-data/iam/security-credentials/" {
-			_, _ = w.Write([]byte("node-role"))
-			return
-		}
-		if hits != nil {
-			atomic.AddInt32(hits, 1)
-		}
-		_ = json.NewEncoder(w).Encode(creds)
-	})
-	srv := httptest.NewServer(mux)
-	t.Cleanup(srv.Close)
-	return srv
-}
-
-func TestRetrieve_FetchesAndCaches(t *testing.T) {
-	var hits int32
-	// Kept under an hour: ec2rolecreds caps Expires to now+1h.
-	exp := time.Now().Add(30 * time.Minute).UTC().Round(time.Second)
-	srv := imdsStub(t, &hits, map[string]string{
-		"Code":            "Success",
-		"AccessKeyId":     "AKIA",
-		"SecretAccessKey": "secret",
-		"Token":           "session",
-		"Expiration":      exp.Format(time.RFC3339),
-	})
-
-	p := NewIMDSProvider(srv.Client(), srv.URL+"/latest")
-	got, err := p.Retrieve(context.Background())
-	if err != nil {
-		t.Fatalf("Retrieve: %v", err)
-	}
-	if got.AccessKeyID != "AKIA" || !got.Expiration.Equal(exp) {
-		t.Errorf("creds mismatch: %+v", got)
-	}
-
-	// Second call well within validity must not re-hit IMDS.
-	if _, err := p.Retrieve(context.Background()); err != nil {
-		t.Fatalf("Retrieve 2: %v", err)
-	}
-	if hits != 1 {
-		t.Errorf("IMDS credential hits = %d, want 1 (cached)", hits)
-	}
-}
-
-func TestRetrieve_RefetchesWhenExpired(t *testing.T) {
-	var hits int32
-	// Already expired: aws.CredentialsCache refetches once the stored
-	// credentials' real expiry has passed, regardless of ExpiryWindow.
-	srv := imdsStub(t, &hits, map[string]string{
-		"Code":            "Success",
-		"AccessKeyId":     "AKIA",
-		"SecretAccessKey": "secret",
-		"Expiration":      time.Now().Add(-time.Minute).UTC().Format(time.RFC3339),
-	})
-	p := NewIMDSProvider(srv.Client(), srv.URL+"/latest")
-	if _, err := p.Retrieve(context.Background()); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := p.Retrieve(context.Background()); err != nil {
-		t.Fatal(err)
-	}
-	if hits != 2 {
-		t.Errorf("hits = %d, want 2 (expired refetch)", hits)
-	}
-}
-
-// imdsStubFailAfterFirst serves creds on the first credential request and 500s
-// on every one after it, so a test can drive a refresh that fails against a
-// credential the cache has already stored.
-func imdsStubFailAfterFirst(t *testing.T, creds map[string]string) *httptest.Server {
-	t.Helper()
-	var hits atomic.Int32
-	mux := http.NewServeMux()
-	mux.HandleFunc("/latest/api/token", func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("X-Aws-Ec2-Metadata-Token-Ttl-Seconds", "21600")
-		_, _ = w.Write([]byte("v2-token"))
-	})
-	mux.HandleFunc("/latest/meta-data/iam/security-credentials/", func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path == "/latest/meta-data/iam/security-credentials/" {
-			_, _ = w.Write([]byte("node-role"))
-			return
-		}
-		if hits.Add(1) > 1 {
-			w.WriteHeader(http.StatusInternalServerError)
-			return
-		}
-		_ = json.NewEncoder(w).Encode(creds)
-	})
-	srv := httptest.NewServer(mux)
-	t.Cleanup(srv.Close)
-	return srv
-}
-
-// A refresh that fails must surface as an error. Left to itself the SDK's
-// ec2rolecreds implements HandleFailToRefresh, which hands back the same dead
-// key with Expires pushed 5-15 minutes out, so the agent would sign requests
-// with a credential the control plane has already rejected — indefinitely,
-// since every subsequent refresh fails the same way.
-func TestRetrieve_FailedRefreshDoesNotExtendExpiry(t *testing.T) {
-	srv := imdsStubFailAfterFirst(t, map[string]string{
-		"Code":            "Success",
-		"AccessKeyId":     "AKIA",
-		"SecretAccessKey": "secret",
-		"Token":           "session",
-		// Already expired, so the next Retrieve must go back to IMDS.
-		"Expiration": time.Now().Add(-time.Minute).UTC().Format(time.RFC3339),
-	})
-
-	p := NewIMDSProvider(srv.Client(), srv.URL+"/latest")
-	first, err := p.Retrieve(context.Background())
-	if err != nil {
-		t.Fatalf("first Retrieve: %v", err)
-	}
-
-	got, err := p.Retrieve(context.Background())
-	if err == nil {
-		t.Fatalf("refresh failure was reported as success: %+v", got)
-	}
-	if got.Expiration.After(first.Expiration) {
-		t.Errorf("expiry extended on refresh failure: %v -> %v", first.Expiration, got.Expiration)
-	}
-}
-
-func TestRetrieve_CancelledContext(t *testing.T) {
-	srv := imdsStub(t, nil, map[string]string{"Code": "Success", "AccessKeyId": "A", "SecretAccessKey": "B"})
-	p := NewIMDSProvider(srv.Client(), srv.URL+"/latest")
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
-	if _, err := p.Retrieve(ctx); err == nil {
-		t.Fatal("expected error from cancelled context")
-	}
-}
-
-func TestRetrieve_CodeNotSuccessErrors(t *testing.T) {
-	srv := imdsStub(t, nil, map[string]string{"Code": "Failure", "AccessKeyId": "A", "SecretAccessKey": "B"})
-	p := NewIMDSProvider(srv.Client(), srv.URL+"/latest")
-	if _, err := p.Retrieve(context.Background()); err == nil {
-		t.Fatal("expected error when Code != Success")
-	}
-}

spinifex/agents/ecs/credentials/provider.go

@@ -1,24 +0,0 @@
-// Package credentials supplies AWS SigV4 credentials to the ecs-agent. The agent
-// signs gateway calls (ECR GetAuthorizationToken, instance register/heartbeat)
-// with the host's instance-role credentials, fetched from IMDS and cached until
-// near expiry.
-package credentials
-
-import (
-	"context"
-	"time"
-)
-
-// Credentials is a SigV4 credential set with an expiry.
-type Credentials struct {
-	AccessKeyID     string
-	SecretAccessKey string
-	SessionToken    string
-	Expiration      time.Time
-}
-
-// CredentialsProvider yields current credentials, refreshing as needed. Retrieve
-// must be safe for concurrent use.
-type CredentialsProvider interface {
-	Retrieve(ctx context.Context) (Credentials, error)
-}

spinifex/agents/eks/konnectivitycert/cert.go

@@ -80,7 +80,17 @@ func ensureCert(dir, caCertPath, caKeyPath, cn string, dns []string, ips []net.I
 	if err != nil {
 		return "", "", err
 	}
-	certPEM, keyPEM, err := issueLeaf(caCert, caKey, cn, dns, ips)
+	now := time.Now().UTC()
+	certPEM, keyPEM, err := Mint(&x509.Certificate{
+		Subject:               pkix.Name{CommonName: cn},
+		NotBefore:             now.Add(-time.Hour),
+		NotAfter:              now.AddDate(10, 0, 0),
+		KeyUsage:              x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment,
+		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
+		BasicConstraintsValid: true,
+		DNSNames:              dns,
+		IPAddresses:           ips,
+	}, caCert, caKey)
 	if err != nil {
 		return "", "", err
 	}
@@ -181,8 +191,9 @@ func parseECKey(der []byte) (*ecdsa.PrivateKey, error) {
 	return ec, nil
 }
 
-// issueLeaf mints an ECDSA-P256 ServerAuth leaf for cn + SANs, signed by caCert/caKey.
-func issueLeaf(caCert *x509.Certificate, caKey *ecdsa.PrivateKey, cn string, dns []string, ips []net.IP) (certPEM, keyPEM []byte, err error) {
+// Mint generates an ECDSA-P256 key, issues tmpl for it with a random serial and
+// signs it with parentKey, or self-signs when parent is nil. tmpl is not modified.
+func Mint(tmpl, parent *x509.Certificate, parentKey *ecdsa.PrivateKey) (certPEM, keyPEM []byte, err error) {
 	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
 	if err != nil {
 		return nil, nil, fmt.Errorf("generate key: %w", err)
@@ -191,19 +202,12 @@ func issueLeaf(caCert *x509.Certificate, caKey *ecdsa.PrivateKey, cn string, dns
 	if err != nil {
 		return nil, nil, fmt.Errorf("serial: %w", err)
 	}
-	now := time.Now().UTC()
-	tmpl := x509.Certificate{
-		SerialNumber:          serial,
-		Subject:               pkix.Name{CommonName: cn},
-		NotBefore:             now.Add(-time.Hour),
-		NotAfter:              now.AddDate(10, 0, 0),
-		KeyUsage:              x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment,
-		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
-		BasicConstraintsValid: true,
-		DNSNames:              dns,
-		IPAddresses:           ips,
+	t := *tmpl
+	t.SerialNumber = serial
+	if parent == nil {
+		parent, parentKey = &t, priv
 	}
-	der, err := x509.CreateCertificate(rand.Reader, &tmpl, caCert, &priv.PublicKey, caKey)
+	der, err := x509.CreateCertificate(rand.Reader, &t, parent, &priv.PublicKey, parentKey)
 	if err != nil {
 		return nil, nil, fmt.Errorf("create cert: %w", err)
 	}

spinifex/agents/eks/podidentity/certs.go

@@ -1,15 +1,11 @@
 package podidentity
 
 import (
-	"crypto/ecdsa"
-	"crypto/elliptic"
-	"crypto/rand"
 	"crypto/tls"
 	"crypto/x509"
 	"crypto/x509/pkix"
 	"encoding/pem"
 	"fmt"
-	"math/big"
 	"net"
 	"os"
 	"path/filepath"
@@ -83,17 +79,8 @@ func ensureLeaf(certPath, keyPath, caCertPath, caKeyPath string, spec leafSpec)
 	if leafCurrent(certPath, keyPath, ca, spec) {
 		return nil
 	}
-	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		return fmt.Errorf("generate key: %w", err)
-	}
-	serial, err := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
-	if err != nil {
-		return fmt.Errorf("serial: %w", err)
-	}
 	now := time.Now().UTC()
-	tmpl := x509.Certificate{
-		SerialNumber:          serial,
+	certPEM, keyPEM, err := konnectivitycert.Mint(&x509.Certificate{
 		Subject:               pkix.Name{CommonName: spec.cn},
 		NotBefore:             now.Add(-time.Hour),
 		NotAfter:              now.Add(certValidity),
@@ -101,20 +88,15 @@ func ensureLeaf(certPath, keyPath, caCertPath, caKeyPath string, spec leafSpec)
 		ExtKeyUsage:           []x509.ExtKeyUsage{spec.usage},
 		BasicConstraintsValid: true,
 		IPAddresses:           spec.ips,
-	}
-	der, err := x509.CreateCertificate(rand.Reader, &tmpl, ca, &priv.PublicKey, caKey)
+	}, ca, caKey)
 	if err != nil {
-		return fmt.Errorf("create certificate: %w", err)
-	}
-	keyDER, err := x509.MarshalECPrivateKey(priv)
-	if err != nil {
-		return fmt.Errorf("marshal key: %w", err)
-	}
-	// Key first: a cert without its key is never published.
-	if err := writeAtomic(keyPath, pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: keyDER}), 0o600); err != nil {
 		return err
 	}
-	return writeAtomic(certPath, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der}), 0o644)
+	// Key first: a cert without its key is never published.
+	if err := writeAtomic(keyPath, keyPEM, 0o600); err != nil {
+		return err
+	}
+	return writeAtomic(certPath, certPEM, 0o644)
 }
 
 // leafCurrent reports whether the cached pair loads, matches, was signed by ca,

spinifex/agents/eks/tokenwebhook/cert.go

@@ -1,21 +1,17 @@
 package tokenwebhook
 
 import (
-	"crypto/ecdsa"
-	"crypto/elliptic"
-	"crypto/rand"
 	"crypto/tls"
 	"crypto/x509"
 	"crypto/x509/pkix"
 	"encoding/base64"
-	"encoding/pem"
 	"fmt"
-	"math/big"
 	"net"
 	"os"
 	"time"
 
 	"github.com/mulgadc/bluebottle/pkg/tlsconfig"
+	"github.com/mulgadc/spinifex/spinifex/agents/eks/konnectivitycert"
 )
 
 // serverTLSConfig is the webhook's loopback serving TLS config.
@@ -41,7 +37,18 @@ func ensureServingCert(certPath, keyPath string) (tls.Certificate, []byte, error
 		}
 	}
 
-	certPEM, keyPEM, err := generateSelfSigned()
+	now := time.Now().UTC()
+	certPEM, keyPEM, err := konnectivitycert.Mint(&x509.Certificate{
+		Subject:               pkix.Name{CommonName: "eks-token-webhook"},
+		NotBefore:             now.Add(-time.Hour),
+		NotAfter:              now.AddDate(10, 0, 0),
+		KeyUsage:              x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment | x509.KeyUsageCertSign,
+		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
+		BasicConstraintsValid: true,
+		IsCA:                  true,
+		IPAddresses:           []net.IP{net.IPv4(127, 0, 0, 1), net.IPv6loopback},
+		DNSNames:              []string{"localhost"},
+	}, nil, nil)
 	if err != nil {
 		return tls.Certificate{}, nil, err
 	}
@@ -58,41 +65,6 @@ func ensureServingCert(certPath, keyPath string) (tls.Certificate, []byte, error
 	return cert, certPEM, nil
 }
 
-func generateSelfSigned() (certPEM, keyPEM []byte, err error) {
-	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		return nil, nil, fmt.Errorf("generate key: %w", err)
-	}
-	serial, err := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
-	if err != nil {
-		return nil, nil, fmt.Errorf("serial: %w", err)
-	}
-	now := time.Now().UTC()
-	tmpl := x509.Certificate{
-		SerialNumber:          serial,
-		Subject:               pkix.Name{CommonName: "eks-token-webhook"},
-		NotBefore:             now.Add(-time.Hour),
-		NotAfter:              now.AddDate(10, 0, 0),
-		KeyUsage:              x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment | x509.KeyUsageCertSign,
-		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
-		BasicConstraintsValid: true,
-		IsCA:                  true,
-		IPAddresses:           []net.IP{net.IPv4(127, 0, 0, 1), net.IPv6loopback},
-		DNSNames:              []string{"localhost"},
-	}
-	der, err := x509.CreateCertificate(rand.Reader, &tmpl, &tmpl, &priv.PublicKey, priv)
-	if err != nil {
-		return nil, nil, fmt.Errorf("create cert: %w", err)
-	}
-	keyDER, err := x509.MarshalECPrivateKey(priv)
-	if err != nil {
-		return nil, nil, fmt.Errorf("marshal key: %w", err)
-	}
-	certPEM = pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der})
-	keyPEM = pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: keyDER})
-	return certPEM, keyPEM, nil
-}
-
 // writeAPIServerKubeconfig writes the kubeconfig kube-apiserver loads via
 // --authentication-token-webhook-config-file. It points the apiserver at the
 // loopback webhook and trusts its self-signed serving cert as the CA bundle.

spinifex/agents/eks/webhookcert/cert.go

@@ -14,9 +14,6 @@ package webhookcert
 
 import (
 	"context"
-	"crypto/ecdsa"
-	"crypto/elliptic"
-	"crypto/rand"
 	"crypto/x509"
 	"crypto/x509/pkix"
 	"encoding/base64"
@@ -24,11 +21,12 @@ import (
 	"errors"
 	"fmt"
 	"io"
-	"math/big"
 	"os"
 	"path/filepath"
 	"strings"
 	"time"
+
+	"github.com/mulgadc/spinifex/spinifex/agents/eks/konnectivitycert"
 )
 
 // Config names the webhook certificate and where it is cached.
@@ -69,13 +67,25 @@ func ensureCert(dir, cn string, dnsNames []string) (certPEM, keyPEM []byte, err
 
 	if c, cerr := os.ReadFile(certPath); cerr == nil {
 		if k, kerr := os.ReadFile(keyPath); kerr == nil {
-			if _, perr := x509.ParseCertificate(decodeFirst(c)); perr == nil && len(k) > 0 {
-				return c, k, nil
+			if blk, _ := pem.Decode(c); blk != nil && len(k) > 0 {
+				if _, perr := x509.ParseCertificate(blk.Bytes); perr == nil {
+					return c, k, nil
+				}
 			}
 		}
 	}
 
-	certPEM, keyPEM, err = generateSelfSigned(cn, dnsNames)
+	now := time.Now().UTC()
+	certPEM, keyPEM, err = konnectivitycert.Mint(&x509.Certificate{
+		Subject:               pkix.Name{CommonName: cn},
+		NotBefore:             now.Add(-time.Hour),
+		NotAfter:              now.AddDate(10, 0, 0),
+		KeyUsage:              x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment | x509.KeyUsageCertSign,
+		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
+		BasicConstraintsValid: true,
+		IsCA:                  true,
+		DNSNames:              dnsNames,
+	}, nil, nil)
 	if err != nil {
 		return nil, nil, err
 	}
@@ -91,51 +101,6 @@ func ensureCert(dir, cn string, dnsNames []string) (certPEM, keyPEM []byte, err
 	return certPEM, keyPEM, nil
 }
 
-// generateSelfSigned mints an ECDSA-P256 self-signed cert valid as both a CA and
-// a server cert, with the given common name and DNS SANs.
-func generateSelfSigned(cn string, dnsNames []string) (certPEM, keyPEM []byte, err error) {
-	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		return nil, nil, fmt.Errorf("generate key: %w", err)
-	}
-	serial, err := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
-	if err != nil {
-		return nil, nil, fmt.Errorf("serial: %w", err)
-	}
-	now := time.Now().UTC()
-	tmpl := x509.Certificate{
-		SerialNumber:          serial,
-		Subject:               pkix.Name{CommonName: cn},
-		NotBefore:             now.Add(-time.Hour),
-		NotAfter:              now.AddDate(10, 0, 0),
-		KeyUsage:              x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment | x509.KeyUsageCertSign,
-		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
-		BasicConstraintsValid: true,
-		IsCA:                  true,
-		DNSNames:              dnsNames,
-	}
-	der, err := x509.CreateCertificate(rand.Reader, &tmpl, &tmpl, &priv.PublicKey, priv)
-	if err != nil {
-		return nil, nil, fmt.Errorf("create cert: %w", err)
-	}
-	keyDER, err := x509.MarshalECPrivateKey(priv)
-	if err != nil {
-		return nil, nil, fmt.Errorf("marshal key: %w", err)
-	}
-	certPEM = pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der})
-	keyPEM = pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: keyDER})
-	return certPEM, keyPEM, nil
-}
-
-// decodeFirst returns the DER bytes of the first PEM block, or nil.
-func decodeFirst(pemBytes []byte) []byte {
-	blk, _ := pem.Decode(pemBytes)
-	if blk == nil {
-		return nil
-	}
-	return blk.Bytes
-}
-
 func splitCSV(s string) []string {
 	var out []string
 	for p := range strings.SplitSeq(s, ",") {

spinifex/agents/eks/webhookcert/cert_test.go

@@ -2,6 +2,7 @@ package webhookcert
 
 import (
 	"crypto/x509"
+	"encoding/pem"
 	"os"
 	"path/filepath"
 	"testing"
@@ -14,7 +15,11 @@ const (
 
 func parseLeaf(t *testing.T, certPEM []byte) *x509.Certificate {
 	t.Helper()
-	leaf, err := x509.ParseCertificate(decodeFirst(certPEM))
+	blk, _ := pem.Decode(certPEM)
+	if blk == nil {
+		t.Fatal("no PEM block in cert")
+	}
+	leaf, err := x509.ParseCertificate(blk.Bytes)
 	if err != nil {
 		t.Fatalf("parse cert: %v", err)
 	}

spinifex/agents/lambda/agent/agent.go

@@ -12,6 +12,10 @@ import (
 	"github.com/mulgadc/spinifex/spinifex/agents/lambda/runtimeapi"
 )
 
+// resultWriteGrace is how long past the invocation deadline a result may take
+// to reach the host.
+const resultWriteGrace = 2 * time.Second
+
 const (
 	errTypeTimedOut = "Sandbox.Timedout"
 	errTypeUnknown  = "Runtime.Unknown"
@@ -53,6 +57,11 @@ func Run(ctx context.Context, link hostlink.Link, srv *runtimeapi.Server) error
 			Payload:     req.Payload,
 		})
 		timedOut := errors.Is(err, runtimeapi.ErrDeadlineExceeded)
+		if errors.Is(err, runtimeapi.ErrResponseBodyFailed) {
+			// The admitted body was lost: report nothing, so the host's
+			// outcome stays unknown.
+			return err
+		}
 		if err != nil {
 			if ctx.Err() != nil {
 				return cause(ctx, err)
@@ -64,9 +73,15 @@ func Run(ctx context.Context, link hostlink.Link, srv *runtimeapi.Server) error
 			AttemptID:     req.AttemptID,
 			RequestID:     req.RequestID,
 			Payload:       res.Payload,
+			Segments:      res.Segments,
 			FunctionError: res.FunctionError,
 		}
-		if err := link.Complete(ctx, resp); err != nil {
+		// A timed-out invocation writes its result after the deadline, so the
+		// write is bounded from whichever is later, plus the grace.
+		wctx, wcancel := context.WithDeadline(ctx, laterOf(time.UnixMilli(req.DeadlineMs), time.Now()).Add(resultWriteGrace))
+		err = link.Complete(wctx, resp)
+		wcancel()
+		if err != nil {
 			return cause(ctx, err)
 		}
 		if timedOut {
@@ -75,6 +90,13 @@ func Run(ctx context.Context, link hostlink.Link, srv *runtimeapi.Server) error
 	}
 }
 
+func laterOf(a, b time.Time) time.Time {
+	if a.After(b) {
+		return a
+	}
+	return b
+}
+
 func cause(ctx context.Context, err error) error {
 	if ctx.Err() != nil {
 		return context.Cause(ctx)

spinifex/agents/lambda/agent/agent_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"io"
+	"net"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -23,6 +24,7 @@ const api = "/2018-06-01/runtime/"
 type fakeLink struct {
 	reqs []hostlink.Request
 	got  chan hostlink.Response
+	ctxs chan context.Context // when set, the context of each Complete
 }
 
 var _ hostlink.Link = (*fakeLink)(nil)
@@ -37,6 +39,9 @@ func (l *fakeLink) Next(ctx context.Context) (hostlink.Request, error) {
 }
 
 func (l *fakeLink) Complete(ctx context.Context, r hostlink.Response) error {
+	if l.ctxs != nil {
+		l.ctxs <- ctx
+	}
 	l.got <- r
 	return nil
 }
@@ -140,3 +145,58 @@ func TestRunReturnsLinkError(t *testing.T) {
 	err := Run(context.Background(), &errLink{}, runtimeapi.New())
 	require.EqualError(t, err, "link down")
 }
+
+func TestRunBoundsTheResultWriteByTheDeadlinePlusGrace(t *testing.T) {
+	t.Run("on time", func(t *testing.T) {
+		srv := runtimeapi.New()
+		ts := httptest.NewServer(srv.Handler())
+		defer ts.Close()
+		runtime(t, ts.URL, func(string, []byte) (string, string) { return "/response", "ok" })
+		dl := deadline(time.Minute)
+		link := &fakeLink{got: make(chan hostlink.Response, 1), ctxs: make(chan context.Context, 1),
+			reqs: []hostlink.Request{{RequestID: "r", DeadlineMs: dl}}}
+		require.NoError(t, Run(context.Background(), link, srv))
+		d, ok := (<-link.ctxs).Deadline()
+		require.True(t, ok)
+		assert.Equal(t, time.UnixMilli(dl).Add(resultWriteGrace), d)
+	})
+	t.Run("a timed-out result is written after the deadline", func(t *testing.T) {
+		srv := runtimeapi.New() // nothing answers: the invocation expires
+		link := &fakeLink{got: make(chan hostlink.Response, 1), ctxs: make(chan context.Context, 1),
+			reqs: []hostlink.Request{{RequestID: "r", DeadlineMs: deadline(30 * time.Millisecond)}}}
+		require.ErrorIs(t, Run(context.Background(), link, srv), ErrInvocationTimedOut)
+		wctx := <-link.ctxs
+		d, ok := wctx.Deadline()
+		require.True(t, ok)
+		assert.Greater(t, time.Until(d), -resultWriteGrace, "the write deadline is not already past")
+		assert.Equal(t, "Sandbox.Timedout", (<-link.got).FunctionError)
+	})
+}
+
+// A body lost after admission sends the host nothing, so it reports the
+// outcome unknown, whether or not the bootstrap is still alive.
+func TestRunSendsNoResultWhenTheBodyIsLost(t *testing.T) {
+	srv := runtimeapi.New()
+	ts := httptest.NewServer(srv.Handler())
+	defer ts.Close()
+	link := &fakeLink{got: make(chan hostlink.Response, 1), reqs: []hostlink.Request{{RequestID: "r", DeadlineMs: deadline(time.Minute)}}}
+	done := make(chan error, 1)
+	go func() { done <- Run(context.Background(), link, srv) }()
+
+	resp, err := http.Get(ts.URL + api + "invocation/next")
+	require.NoError(t, err)
+	resp.Body.Close()
+	conn, err := net.Dial("tcp", ts.Listener.Addr().String())
+	require.NoError(t, err)
+	_, err = conn.Write([]byte("POST " + api + "invocation/r/response HTTP/1.1\r\nHost: x\r\nContent-Length: 100\r\n\r\npartial"))
+	require.NoError(t, err)
+	conn.Close()
+
+	select {
+	case err := <-done:
+		require.ErrorIs(t, err, runtimeapi.ErrResponseBodyFailed)
+	case <-time.After(10 * time.Second):
+		t.Fatal("Run waited for the invocation deadline")
+	}
+	assert.Empty(t, link.got, "no result may be reported")
+}

spinifex/agents/lambda/agent/agent_testlink_test.go

@@ -0,0 +1,61 @@
+//go:build lambdatestlink
+
+package agent_test
+
+import (
+	"context"
+	"net"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mulgadc/spinifex/spinifex/agents/lambda/agent"
+	"github.com/mulgadc/spinifex/spinifex/agents/lambda/hostlink"
+	"github.com/mulgadc/spinifex/spinifex/agents/lambda/runtimeapi"
+)
+
+// An expired invocation's timeout result is written over a real connection
+// after the deadline, within the grace, and the host decodes it.
+func TestRunWritesTheTimeoutFrameAfterTheDeadline(t *testing.T) {
+	guestConn, hostConn := net.Pipe()
+	t.Cleanup(func() {
+		_ = guestConn.Close()
+		_ = hostConn.Close()
+	})
+	guest := hostlink.NewTestStream(guestConn)
+	host := hostlink.NewTestStream(hostConn)
+
+	dl := time.Now().Add(50 * time.Millisecond)
+	req := hostlink.Request{GrantID: "g", AttemptID: "a", RequestID: "r", DeadlineMs: dl.UnixMilli()}
+	sent := make(chan error, 1)
+	go func() { sent <- host.HostSend(req) }()
+
+	done := make(chan error, 1)
+	go func() { done <- agent.Run(t.Context(), guest, runtimeapi.New()) }()
+	select {
+	case err := <-sent:
+		require.NoError(t, err)
+	case <-time.After(5 * time.Second):
+		t.Fatal("the request was not delivered")
+	}
+
+	ctx, cancel := context.WithTimeout(t.Context(), 5*time.Second)
+	defer cancel()
+	resp, err := host.HostResult(ctx)
+	got := time.Now()
+	require.NoError(t, err)
+	assert.Equal(t, "Sandbox.Timedout", resp.FunctionError)
+	assert.Equal(t, "r", resp.RequestID)
+	assert.Equal(t, "g", resp.GrantID)
+	assert.Equal(t, "a", resp.AttemptID)
+	assert.False(t, got.Before(time.UnixMilli(req.DeadlineMs)), "the result was read before the deadline")
+
+	select {
+	case err := <-done:
+		require.ErrorIs(t, err, agent.ErrInvocationTimedOut)
+	case <-time.After(5 * time.Second):
+		t.Fatal("Run did not return after writing the timeout result")
+	}
+}

spinifex/agents/lambda/hostlink/link.go

@@ -5,6 +5,7 @@ package hostlink
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 )
 
@@ -23,13 +24,31 @@ type Request struct {
 	Payload     []byte `json:"payload"`
 }
 
-// Response is the outcome of a Request. FunctionError is empty on success.
+// Response is the outcome of a Request. FunctionError is empty on success. A
+// non-nil Segments is the payload and takes precedence over Payload; only a
+// streaming carrier can send it, and encoding/json refuses it.
 type Response struct {
-	GrantID       string `json:"grant_id"`
-	AttemptID     string `json:"attempt_id"`
-	RequestID     string `json:"request_id"`
-	Payload       []byte `json:"payload"`
-	FunctionError string `json:"function_error,omitempty"`
+	GrantID       string   `json:"grant_id"`
+	AttemptID     string   `json:"attempt_id"`
+	RequestID     string   `json:"request_id"`
+	Payload       []byte   `json:"payload"`
+	Segments      [][]byte `json:"-"`
+	FunctionError string   `json:"function_error,omitempty"`
+}
+
+// ErrSegmentedNotMarshalable is returned when a segmented payload reaches
+// encoding/json, which would otherwise drop it.
+var ErrSegmentedNotMarshalable = errors.New("hostlink: a segmented payload can only be streamed by a carrier")
+
+type responseAlias Response
+
+// MarshalJSON encodes r as the plain struct, and fails for a segmented
+// payload rather than emit a frame without it.
+func (r Response) MarshalJSON() ([]byte, error) {
+	if r.Segments != nil {
+		return nil, ErrSegmentedNotMarshalable
+	}
+	return json.Marshal(responseAlias(r))
 }
 
 // Link carries invocations from the host to the guest and results back.

spinifex/agents/lambda/hostlink/test_stream.go

@@ -3,13 +3,17 @@
 package hostlink
 
 import (
+	"bufio"
 	"context"
+	"encoding/base64"
 	"encoding/binary"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
-	"sync"
+	"net"
+	"sync/atomic"
+	"time"
 )
 
 // maxFrame bounds one frame: a 6 MiB payload as base64 plus headroom.
@@ -33,9 +37,14 @@ type frame struct {
 // TestStream is a test-only carrier over an io.ReadWriter, framing JSON with
 // a 4-byte big-endian length. It is not the guest protocol.
 type TestStream struct {
-	rw  io.ReadWriter
-	in  chan frame
-	wmu sync.Mutex
+	rw    io.ReadWriter
+	conn  net.Conn // rw when it is a net.Conn; results are written only then
+	in    chan frame
+	wslot chan struct{}
+
+	// closed is set, under the write slot, once the connection was closed
+	// with a result possibly half sent.
+	closed atomic.Bool
 
 	err error // set before in is closed
 }
@@ -44,7 +53,8 @@ var _ Link = (*TestStream)(nil)
 
 // NewTestStream starts reading frames from rw.
 func NewTestStream(rw io.ReadWriter) *TestStream {
-	s := &TestStream{rw: rw, in: make(chan frame)}
+	s := &TestStream{rw: rw, in: make(chan frame), wslot: make(chan struct{}, 1)}
+	s.conn, _ = rw.(net.Conn)
 	go s.readLoop()
 	return s
 }
@@ -92,12 +102,218 @@ func (s *TestStream) Next(ctx context.Context) (Request, error) {
 	}
 }
 
-// Complete implements Link.
-func (s *TestStream) Complete(ctx context.Context, resp Response) error {
+// ErrNoDeadlineTransport is returned by Complete when the stream's transport
+// is not a net.Conn, since a blocked write could then never be interrupted.
+var ErrNoDeadlineTransport = errors.New("hostlink: result needs a net.Conn transport")
+
+// ErrStreamClosed is returned by Complete after a failed write closed the
+// connection.
+var ErrStreamClosed = errors.New("hostlink: stream closed after a failed result write")
+
+// pastDeadline is a write deadline that is always already over.
+var pastDeadline = time.Unix(1, 0)
+
+// acquire takes the write slot or gives up when ctx ends.
+func (s *TestStream) acquire(ctx context.Context) error {
+	select {
+	case s.wslot <- struct{}{}:
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+func (s *TestStream) release() { <-s.wslot }
+
+// Complete implements Link. The result is streamed as the same JSON frame
+// json.Marshal makes for it, without holding a copy of the payload.
+func (s *TestStream) Complete(ctx context.Context, resp Response) (err error) {
+	if s.conn == nil {
+		return ErrNoDeadlineTransport
+	}
+	if s.closed.Load() {
+		return ErrStreamClosed
+	}
 	if err := ctx.Err(); err != nil {
 		return err
 	}
-	return s.write(frame{Type: typeResult, Response: &resp})
+	rf, err := newResultFrame(resp)
+	if err != nil {
+		return err
+	}
+	if rf.size > maxFrame {
+		return ErrFrameTooLarge
+	}
+	if err := s.acquire(ctx); err != nil {
+		return err
+	}
+	// The slot is released last, after the deadline has been cleared.
+	defer s.release()
+	if s.closed.Load() {
+		return ErrStreamClosed
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	// Once any frame byte may be out, the connection is closed before the
+	// slot is released so no later writer can append to a partial frame.
+	closeConn := func() {
+		s.closed.Store(true)
+		_ = s.conn.Close()
+	}
+
+	dl, _ := ctx.Deadline()
+	if err := s.conn.SetWriteDeadline(dl); err != nil {
+		closeConn()
+		return fmt.Errorf("hostlink: set write deadline: %w", err)
+	}
+	stop, watched, watchErr := make(chan struct{}), make(chan struct{}), make(chan error, 1)
+	go func() {
+		defer close(watched)
+		select {
+		case <-ctx.Done():
+			if err := s.conn.SetWriteDeadline(pastDeadline); err != nil {
+				// Closing is what unblocks the pending write.
+				s.closed.Store(true)
+				_ = s.conn.Close()
+				watchErr <- err
+			}
+		case <-stop:
+		}
+	}()
+	cw := &countingWriter{w: s.conn}
+	werr := rf.writeTo(cw)
+	close(stop)
+	<-watched
+	select {
+	case e := <-watchErr:
+		return fmt.Errorf("hostlink: interrupt blocked write: %w", errors.Join(e, werr))
+	default:
+	}
+	if werr == nil && cw.n != int64(4+rf.size) {
+		werr = fmt.Errorf("hostlink: frame wrote %d bytes, expected %d", cw.n, 4+rf.size)
+	}
+	if werr != nil {
+		closeConn()
+		return werr
+	}
+	if cerr := s.conn.SetWriteDeadline(time.Time{}); cerr != nil {
+		closeConn()
+		return fmt.Errorf("hostlink: clear write deadline: %w", errors.Join(cerr, werr))
+	}
+	return nil
+}
+
+// countingWriter writes everything to w, in full, and counts the bytes.
+type countingWriter struct {
+	w io.Writer
+	n int64
+}
+
+func (c *countingWriter) Write(p []byte) (int, error) {
+	done := 0
+	for done < len(p) {
+		n, err := c.w.Write(p[done:])
+		done += n
+		c.n += int64(n)
+		if err != nil {
+			return done, err
+		}
+		if n == 0 {
+			return done, io.ErrShortWrite
+		}
+	}
+	return done, nil
+}
+
+// resultFrame is the result frame in the field order json.Marshal gives
+// frame{Type, Response}, split around the payload value.
+type resultFrame struct {
+	head, tail []byte
+	payload    [][]byte
+	null       bool
+	size       int // JSON length, excluding the 4-byte prefix
+}
+
+func newResultFrame(r Response) (*resultFrame, error) {
+	q := func(v string) ([]byte, error) { return json.Marshal(v) }
+	var parts [3][]byte
+	for i, v := range []string{r.GrantID, r.AttemptID, r.RequestID} {
+		b, err := q(v)
+		if err != nil {
+			return nil, err
+		}
+		parts[i] = b
+	}
+	rf := &resultFrame{}
+	rf.head = append(rf.head, `{"type":"result","response":{"grant_id":`...)
+	rf.head = append(rf.head, parts[0]...)
+	rf.head = append(rf.head, `,"attempt_id":`...)
+	rf.head = append(rf.head, parts[1]...)
+	rf.head = append(rf.head, `,"request_id":`...)
+	rf.head = append(rf.head, parts[2]...)
+	rf.head = append(rf.head, `,"payload":`...)
+	if r.FunctionError != "" {
+		b, err := q(r.FunctionError)
+		if err != nil {
+			return nil, err
+		}
+		rf.tail = append(rf.tail, `,"function_error":`...)
+		rf.tail = append(rf.tail, b...)
+	}
+	rf.tail = append(rf.tail, `}}`...)
+
+	total := 0
+	switch {
+	case r.Segments != nil:
+		rf.payload = r.Segments
+	case r.Payload != nil:
+		rf.payload = [][]byte{r.Payload}
+	default:
+		rf.null = true
+	}
+	for _, seg := range rf.payload {
+		total += len(seg)
+	}
+	rf.size = len(rf.head) + len(rf.tail)
+	if rf.null {
+		rf.size += len("null")
+	} else {
+		// A payload too large for maxFrame is refused before its length matters.
+		if total > maxFrame {
+			rf.size = maxFrame + 1
+			return rf, nil
+		}
+		rf.size += 2 + base64.StdEncoding.EncodedLen(total)
+	}
+	return rf, nil
+}
+
+// writeTo writes the length prefix and the frame, in order, through a small
+// buffer so the payload is never held a second time.
+func (rf *resultFrame) writeTo(w io.Writer) error {
+	bw := bufio.NewWriterSize(w, 32<<10)
+	var hdr [4]byte
+	binary.BigEndian.PutUint32(hdr[:], uint32(rf.size))
+	_, _ = bw.Write(hdr[:])
+	_, _ = bw.Write(rf.head)
+	if rf.null {
+		_, _ = bw.WriteString("null")
+	} else {
+		_ = bw.WriteByte('"')
+		enc := base64.NewEncoder(base64.StdEncoding, bw)
+		for _, seg := range rf.payload {
+			if _, err := enc.Write(seg); err != nil {
+				return err
+			}
+		}
+		if err := enc.Close(); err != nil {
+			return err
+		}
+		_ = bw.WriteByte('"')
+	}
+	_, _ = bw.Write(rf.tail)
+	return bw.Flush()
 }
 
 // HostSend writes an invoke frame, as the host side of the carrier.
@@ -133,8 +349,8 @@ func (s *TestStream) write(f frame) error {
 	buf := make([]byte, 4+len(b))
 	binary.BigEndian.PutUint32(buf, uint32(len(b)))
 	copy(buf[4:], b)
-	s.wmu.Lock()
-	defer s.wmu.Unlock()
+	_ = s.acquire(context.Background())
+	defer s.release()
 	_, err = s.rw.Write(buf)
 	return err
 }

spinifex/agents/lambda/hostlink/test_stream_complete_test.go

@@ -0,0 +1,612 @@
+//go:build lambdatestlink
+
+package hostlink
+
+//test:in-package reaches the unexported write slot, frame types and readFrame to force orderings
+
+import (
+	"bytes"
+	"context"
+	"encoding/binary"
+	"encoding/json"
+	"errors"
+	"io"
+	"net"
+	"os"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/goleak"
+)
+
+// fakeConn is a net.Conn that records what is written and the deadlines set,
+// and can fail or block on demand.
+type fakeConn struct {
+	mu        sync.Mutex
+	buf       bytes.Buffer
+	deadlines []time.Time
+	maxWrite  int
+
+	failDeadline func(n int, t time.Time) error
+	blockWrites  bool
+	started      chan struct{}
+	unblock      chan struct{}
+	closedCh     chan struct{}
+	startOnce    sync.Once
+	unblockOnce  sync.Once
+	closeOnce    sync.Once
+	closes       atomic.Int32
+}
+
+var _ net.Conn = (*fakeConn)(nil)
+
+func newFakeConn() *fakeConn {
+	return &fakeConn{started: make(chan struct{}), unblock: make(chan struct{}), closedCh: make(chan struct{})}
+}
+
+func (c *fakeConn) Read([]byte) (int, error) { <-c.closedCh; return 0, io.EOF }
+
+func (c *fakeConn) Write(p []byte) (int, error) {
+	if c.blockWrites {
+		c.startOnce.Do(func() { close(c.started) })
+		select {
+		case <-c.unblock:
+			return 0, os.ErrDeadlineExceeded
+		case <-c.closedCh:
+			return 0, net.ErrClosed
+		}
+	}
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.maxWrite = max(c.maxWrite, len(p))
+	return c.buf.Write(p)
+}
+
+func (c *fakeConn) Close() error {
+	c.closes.Add(1)
+	c.closeOnce.Do(func() { close(c.closedCh) })
+	return nil
+}
+
+func (c *fakeConn) SetWriteDeadline(t time.Time) error {
+	c.mu.Lock()
+	c.deadlines = append(c.deadlines, t)
+	n := len(c.deadlines)
+	c.mu.Unlock()
+	if c.failDeadline != nil {
+		if err := c.failDeadline(n, t); err != nil {
+			return err
+		}
+	}
+	if !t.IsZero() && !t.After(time.Now()) {
+		c.unblockOnce.Do(func() { close(c.unblock) })
+	}
+	return nil
+}
+
+func (c *fakeConn) LocalAddr() net.Addr             { return nil }
+func (c *fakeConn) RemoteAddr() net.Addr            { return nil }
+func (c *fakeConn) SetDeadline(time.Time) error     { return nil }
+func (c *fakeConn) SetReadDeadline(time.Time) error { return nil }
+
+func (c *fakeConn) written() []byte {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return bytes.Clone(c.buf.Bytes())
+}
+
+func (c *fakeConn) deadlineLog() []time.Time {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return append([]time.Time(nil), c.deadlines...)
+}
+
+// await bounds a receive so a regression fails promptly instead of hanging.
+func await[T any](t *testing.T, ch <-chan T) T {
+	t.Helper()
+	select {
+	case v := <-ch:
+		return v
+	case <-time.After(15 * time.Second):
+		t.Fatal("timed out waiting on a channel")
+		panic("unreachable")
+	}
+}
+
+// pattern returns n deterministic bytes.
+func pattern(n int) []byte {
+	b := make([]byte, n)
+	for i := range b {
+		b[i] = byte(i*7 + i/251)
+	}
+	return b
+}
+
+func split(b []byte, seg int) [][]byte {
+	out := [][]byte{}
+	for len(b) > 0 {
+		n := min(seg, len(b))
+		out = append(out, b[:n])
+		b = b[n:]
+	}
+	return out
+}
+
+func segmented(b []byte, n int) [][]byte { return split(b, n) }
+
+func joined(r Response) []byte {
+	if r.Segments != nil {
+		return append([]byte{}, bytes.Join(r.Segments, nil)...)
+	}
+	return r.Payload
+}
+
+// assertTodaysFrame checks the written bytes are exactly the length prefix
+// and the json.Marshal of the frame, and that readFrame decodes it.
+func assertTodaysFrame(t *testing.T, got []byte, r Response) {
+	t.Helper()
+	plain := r
+	plain.Segments = nil
+	plain.Payload = joined(r)
+	want, err := json.Marshal(frame{Type: typeResult, Response: &plain})
+	require.NoError(t, err)
+	require.GreaterOrEqual(t, len(got), 4)
+	assert.Equal(t, uint32(len(got)-4), binary.BigEndian.Uint32(got[:4]), "length prefix must match the bytes after it")
+	if !assert.True(t, bytes.Equal(want, got[4:]), "frame differs from json.Marshal (%d vs %d bytes)", len(want), len(got)-4) {
+		return
+	}
+	f, err := readFrame(bytes.NewReader(got))
+	require.NoError(t, err)
+	var wf frame
+	require.NoError(t, json.Unmarshal(want, &wf))
+	assert.Equal(t, *wf.Response, *f.Response)
+}
+
+func complete(t *testing.T, r Response) []byte {
+	t.Helper()
+	c := newFakeConn()
+	defer c.Close()
+	require.NoError(t, NewTestStream(c).Complete(context.Background(), r))
+	return c.written()
+}
+
+func TestCompleteMatchesJSONMarshal(t *testing.T) {
+	meta := Response{GrantID: "g-1", AttemptID: "a-1", RequestID: "r-1"}
+	t.Run("6 MiB from one buffer and from many segments", func(t *testing.T) {
+		p := pattern(6 << 20)
+		one := meta
+		one.Payload = p
+		assertTodaysFrame(t, complete(t, one), one)
+		many := meta
+		many.Segments = segmented(p, 256<<10)
+		assertTodaysFrame(t, complete(t, many), many)
+		odd := meta
+		odd.Segments = segmented(p, 256<<10+1)
+		odd.FunctionError = "Unhandled"
+		assertTodaysFrame(t, complete(t, odd), odd)
+	})
+	t.Run("segment lengths against totals of each length mod 3", func(t *testing.T) {
+		for _, seg := range []int{1, 2, 3, 4, 5, 256<<10 + 1} {
+			totals := []int{0, 1, 2, 3, 4, 5, 6, 7, 64, 65, 66}
+			if seg > 5 {
+				totals = append(totals, seg-1, seg, seg+1, 2*seg+1, 2*seg+2)
+			}
+			for _, total := range totals {
+				r := meta
+				r.Segments = segmented(pattern(total), seg)
+				assertTodaysFrame(t, complete(t, r), r)
+			}
+		}
+	})
+	t.Run("nil and empty payloads", func(t *testing.T) {
+		nilp := meta
+		got := complete(t, nilp)
+		assert.Contains(t, string(got[4:]), `"payload":null`)
+		assertTodaysFrame(t, got, nilp)
+
+		empty := meta
+		empty.Payload = []byte{}
+		got = complete(t, empty)
+		assert.Contains(t, string(got[4:]), `"payload":""`)
+		assertTodaysFrame(t, got, empty)
+
+		noSegs := meta
+		noSegs.Segments = [][]byte{}
+		assertTodaysFrame(t, complete(t, noSegs), noSegs)
+	})
+	t.Run("metadata is escaped as json.Marshal escapes it", func(t *testing.T) {
+		for _, s := range []string{
+			`quo"te`, `back\slash`, "ctl\x00\x01\x1f\n\t\r", "naïve 日本語 😀", "<script>&amp;</script>",
+			`","payload":"x"`, `{"type":"invoke"}`, `"payload":`, "bad\xffutf8", ``,
+		} {
+			r := Response{GrantID: s, AttemptID: s + "a", RequestID: "r" + s, Payload: []byte("p"), FunctionError: s}
+			assertTodaysFrame(t, complete(t, r), r)
+			r.FunctionError = ""
+			r.Segments = [][]byte{[]byte("a"), []byte("bc")}
+			assertTodaysFrame(t, complete(t, r), r)
+		}
+	})
+	t.Run("a payload landing exactly on maxFrame", func(t *testing.T) {
+		for pad := range 4 {
+			r := Response{GrantID: "g", AttemptID: "a", RequestID: strings.Repeat("r", 1+pad)}
+			rf, err := newResultFrame(r)
+			require.NoError(t, err)
+			room := maxFrame - rf.size + 2
+			if room%4 != 0 {
+				continue
+			}
+			r.Payload = pattern(room / 4 * 3)
+			rf, err = newResultFrame(r)
+			require.NoError(t, err)
+			require.Equal(t, maxFrame, rf.size)
+			assertTodaysFrame(t, complete(t, r), r)
+			return
+		}
+		t.Fatal("no request id length lands on maxFrame")
+	})
+}
+
+func TestCompleteRefusesOverMaxFrameBeforeWriting(t *testing.T) {
+	c := newFakeConn()
+	defer c.Close()
+	s := NewTestStream(c)
+	err := s.Complete(context.Background(), Response{Segments: segmented(make([]byte, maxFrame), 1<<20)})
+	require.ErrorIs(t, err, ErrFrameTooLarge)
+	assert.Empty(t, c.written())
+	assert.Empty(t, c.deadlineLog(), "nothing is touched before the size check")
+}
+
+// plainRW has no deadline support at all.
+type plainRW struct {
+	io.Reader
+	wrote atomic.Int32
+}
+
+func (p *plainRW) Write(b []byte) (int, error) { p.wrote.Add(1); return len(b), nil }
+
+// deadlineRW has SetWriteDeadline but is not a net.Conn.
+type deadlineRW struct{ plainRW }
+
+func (*deadlineRW) SetWriteDeadline(time.Time) error { return nil }
+
+func TestCompleteRefusesNonNetConn(t *testing.T) {
+	p := &plainRW{Reader: strings.NewReader("")}
+	d := &deadlineRW{plainRW{Reader: strings.NewReader("")}}
+	for name, tc := range map[string]struct {
+		rw    io.ReadWriter
+		wrote *atomic.Int32
+	}{
+		"plain":                 {p, &p.wrote},
+		"with SetWriteDeadline": {d, &d.wrote},
+	} {
+		t.Run(name, func(t *testing.T) {
+			s := NewTestStream(tc.rw)
+			err := s.Complete(context.Background(), Response{Payload: []byte{1}})
+			require.ErrorIs(t, err, ErrNoDeadlineTransport)
+			assert.Zero(t, tc.wrote.Load(), "no byte may be written")
+		})
+	}
+}
+
+// sigCtx reports the first time something selects on its Done channel.
+type sigCtx struct {
+	context.Context
+	waiting chan struct{}
+	once    sync.Once
+}
+
+func (c *sigCtx) Done() <-chan struct{} {
+	c.once.Do(func() { close(c.waiting) })
+	return c.Context.Done()
+}
+
+func TestCompleteCancelledWhileAnotherWriteHoldsTheSlot(t *testing.T) {
+	defer goleak.VerifyNone(t, goleak.IgnoreCurrent())
+	c := newFakeConn()
+	s := NewTestStream(c)
+	require.NoError(t, s.acquire(context.Background())) // another writer holds the slot
+
+	base, cancel := context.WithCancel(context.Background())
+	ctx := &sigCtx{Context: base, waiting: make(chan struct{})}
+	done := make(chan error, 1)
+	go func() { done <- s.Complete(ctx, Response{Payload: []byte("x")}) }()
+	await(t, ctx.waiting)
+	cancel()
+	require.ErrorIs(t, await(t, done), context.Canceled)
+	assert.Empty(t, c.written(), "the peer receives no bytes")
+	assert.Empty(t, c.deadlineLog())
+
+	s.release()
+	require.NoError(t, s.Complete(context.Background(), Response{Payload: []byte("x")}), "the slot is still usable")
+	c.Close()
+}
+
+func TestCompletePreCancelledReleasesSlot(t *testing.T) {
+	c := newFakeConn()
+	defer c.Close()
+	s := NewTestStream(c)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	require.ErrorIs(t, s.Complete(ctx, Response{Payload: []byte("x")}), context.Canceled)
+	assert.Empty(t, c.written())
+	assert.Zero(t, len(s.wslot), "slot released")
+}
+
+func TestCompleteInitialDeadlineFailureClosesAndWritesNothing(t *testing.T) {
+	c := newFakeConn()
+	c.failDeadline = func(int, time.Time) error { return errors.New("no deadlines") }
+	s := NewTestStream(c)
+	err := s.Complete(context.Background(), Response{Payload: []byte("x")})
+	require.ErrorContains(t, err, "set write deadline")
+	assert.Equal(t, int32(1), c.closes.Load())
+	assert.Empty(t, c.written())
+	assert.Zero(t, len(s.wslot))
+}
+
+func TestCompleteInterruptFailureClosesAndReportsLinkError(t *testing.T) {
+	defer goleak.VerifyNone(t, goleak.IgnoreCurrent())
+	c := newFakeConn()
+	c.blockWrites = true
+	c.failDeadline = func(_ int, t time.Time) error {
+		if !t.IsZero() && t.Before(time.Now()) {
+			return errors.New("cannot interrupt")
+		}
+		return nil
+	}
+	s := NewTestStream(c)
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { done <- s.Complete(ctx, Response{Payload: []byte("x")}) }()
+	await(t, c.started)
+	cancel()
+	var err error
+	select {
+	case err = <-done:
+	case <-time.After(5 * time.Second):
+		c.Close()
+		t.Fatal("Complete stayed blocked: the watcher did not close the connection")
+	}
+	require.ErrorContains(t, err, "interrupt blocked write")
+	assert.Equal(t, int32(1), c.closes.Load())
+	assert.Zero(t, len(s.wslot))
+}
+
+func TestCompleteClearFailureAfterWriteClosesButFrameWasSent(t *testing.T) {
+	c := newFakeConn()
+	c.failDeadline = func(n int, _ time.Time) error {
+		if n == 2 {
+			return errors.New("cannot clear")
+		}
+		return nil
+	}
+	s := NewTestStream(c)
+	r := Response{GrantID: "g", AttemptID: "a", RequestID: "r", Payload: []byte("done")}
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+	err := s.Complete(ctx, r)
+	require.ErrorContains(t, err, "clear write deadline")
+	assert.Equal(t, int32(1), c.closes.Load())
+	// The host already holds a complete valid frame and may accept it.
+	assertTodaysFrame(t, c.written(), r)
+}
+
+func TestCompleteReleasesSlotOnlyAfterDeadlineCleared(t *testing.T) {
+	c := newFakeConn()
+	clearing, proceed := make(chan struct{}), make(chan struct{})
+	c.failDeadline = func(n int, t time.Time) error {
+		if n == 2 { // writer A clearing its deadline
+			close(clearing)
+			<-proceed
+		}
+		return nil
+	}
+	s := NewTestStream(c)
+	ctxA, cancelA := context.WithTimeout(context.Background(), time.Minute)
+	defer cancelA()
+	aDone := make(chan error, 1)
+	go func() { aDone <- s.Complete(ctxA, Response{Payload: []byte("a")}) }()
+	await(t, clearing)
+
+	base, cancelB := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancelB()
+	ctxB := &sigCtx{Context: base, waiting: make(chan struct{})}
+	bDone := make(chan error, 1)
+	go func() { bDone <- s.Complete(ctxB, Response{Payload: []byte("b")}) }()
+	await(t, ctxB.waiting)
+	assert.Len(t, c.deadlineLog(), 2, "B has set no deadline while A is still cleaning up")
+
+	close(proceed)
+	require.NoError(t, await(t, aDone))
+	require.NoError(t, await(t, bDone))
+	log := c.deadlineLog()
+	require.Len(t, log, 4)
+	assert.False(t, log[0].IsZero())
+	assert.True(t, log[1].IsZero(), "A clears first")
+	assert.False(t, log[2].IsZero())
+	assert.True(t, log[3].IsZero())
+	c.Close()
+}
+
+func TestCompleteStopsAtDeadlineWhenPeerNeverReads(t *testing.T) {
+	g, h := net.Pipe()
+	defer h.Close()
+	s := NewTestStream(g)
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+	err := s.Complete(ctx, Response{GrantID: "g", Payload: []byte("x")})
+	require.Error(t, err)
+	assert.ErrorIs(t, err, os.ErrDeadlineExceeded)
+	assert.Zero(t, len(s.wslot))
+
+	// The host never received a frame, so it has nothing to accept.
+	host := NewTestStream(h)
+	g.Close()
+	_, err = host.HostResult(context.Background())
+	require.Error(t, err)
+}
+
+func TestCompleteCancelInterruptsBlockedWrite(t *testing.T) {
+	defer goleak.VerifyNone(t, goleak.IgnoreCurrent())
+	c := newFakeConn()
+	c.blockWrites = true
+	s := NewTestStream(c)
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { done <- s.Complete(ctx, Response{Payload: []byte("x")}) }()
+	await(t, c.started)
+	cancel()
+	require.ErrorIs(t, await(t, done), os.ErrDeadlineExceeded)
+	assert.Equal(t, int32(1), c.closes.Load(), "a frame may be half sent, so the connection is closed")
+	assert.ErrorIs(t, s.Complete(context.Background(), Response{Payload: []byte("x")}), ErrStreamClosed)
+}
+
+func TestCompleteCancelAfterWriteDoesNotTouchConn(t *testing.T) {
+	defer goleak.VerifyNone(t, goleak.IgnoreCurrent())
+	c := newFakeConn()
+	s := NewTestStream(c)
+	ctx, cancel := context.WithCancel(context.Background())
+	require.NoError(t, s.Complete(ctx, Response{Payload: []byte("x")}))
+	before := len(c.deadlineLog())
+	cancel()
+	assert.Len(t, c.deadlineLog(), before, "no watcher is left to move the deadline")
+	assert.Zero(t, c.closes.Load())
+	c.Close()
+}
+
+func TestCompleteWritesNeverInterleave(t *testing.T) {
+	c := newFakeConn()
+	defer c.Close()
+	s := NewTestStream(c)
+	const n = 16
+	var wg sync.WaitGroup
+	for i := range n {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			if i%2 == 0 {
+				assert.NoError(t, s.Complete(context.Background(), Response{GrantID: "g", Segments: segmented(pattern(100000+i), 7001)}))
+			} else {
+				assert.NoError(t, s.HostSend(Request{GrantID: "g", Payload: pattern(100000 + i)}))
+			}
+		}()
+	}
+	wg.Wait()
+	r := bytes.NewReader(c.written())
+	var results, invokes int
+	for r.Len() > 0 {
+		f, err := readFrame(r)
+		require.NoError(t, err)
+		switch f.Type {
+		case typeResult:
+			results++
+		case typeInvoke:
+			invokes++
+		}
+	}
+	assert.Equal(t, n/2, results)
+	assert.Equal(t, n/2, invokes)
+}
+
+// discardConn drops writes so a benchmark does not hold the frame.
+type discardConn struct{ *fakeConn }
+
+func (discardConn) Write(p []byte) (int, error) { return len(p), nil }
+
+func TestCompleteMakesNoPayloadSizedAllocation(t *testing.T) {
+	r := Response{GrantID: "g", AttemptID: "a", RequestID: "r", Segments: segmented(pattern(6<<20), 256<<10)}
+	c := newFakeConn()
+	defer c.Close()
+	require.NoError(t, NewTestStream(c).Complete(context.Background(), r))
+	assert.Less(t, c.maxWrite, 64<<10, "no single write is payload sized")
+
+	d := discardConn{newFakeConn()}
+	defer d.Close()
+	bs := NewTestStream(d)
+	br := testing.Benchmark(func(b *testing.B) {
+		b.ReportAllocs()
+		for range b.N {
+			if err := bs.Complete(context.Background(), r); err != nil {
+				b.Fatal(err)
+			}
+		}
+	})
+	assert.Less(t, br.AllocedBytesPerOp(), int64(1<<20), "writing a 6 MiB result")
+}
+
+func TestResponseJSONCompatibility(t *testing.T) {
+	plain := Response{GrantID: "g", AttemptID: "a", RequestID: "r", Payload: []byte("p<&>"), FunctionError: "Unhandled"}
+
+	t.Run("nil segments encode as the plain struct", func(t *testing.T) {
+		got, err := json.Marshal(plain)
+		require.NoError(t, err)
+		want := `{"grant_id":"g","attempt_id":"a","request_id":"r","payload":"cDwmPg==","function_error":"Unhandled"}`
+		assert.Equal(t, want, string(got))
+		inFrame, err := json.Marshal(frame{Type: typeResult, Response: &plain})
+		require.NoError(t, err)
+		assert.Equal(t, `{"type":"result","response":`+want+`}`, string(inFrame))
+		nilPayload, err := json.Marshal(Response{GrantID: "g"})
+		require.NoError(t, err)
+		assert.Equal(t, `{"grant_id":"g","attempt_id":"","request_id":"","payload":null}`, string(nilPayload))
+	})
+	t.Run("a legacy frame decodes as before", func(t *testing.T) {
+		legacy, err := json.Marshal(frame{Type: typeResult, Response: &plain})
+		require.NoError(t, err)
+		var f frame
+		require.NoError(t, json.Unmarshal(legacy, &f))
+		assert.Equal(t, plain, *f.Response)
+	})
+	t.Run("unknown fields including segments are ignored", func(t *testing.T) {
+		var f frame
+		in := `{"type":"result","extra":1,"response":{"grant_id":"g","segments":{"x":1},"unknown":[1],"payload":"cA=="}}`
+		require.NoError(t, json.Unmarshal([]byte(in), &f))
+		assert.Equal(t, Response{GrantID: "g", Payload: []byte("p")}, *f.Response)
+	})
+	t.Run("a segmented payload cannot be marshalled", func(t *testing.T) {
+		r := Response{GrantID: "g", Segments: segmented([]byte("data"), 2)}
+		_, err := json.Marshal(r)
+		require.ErrorIs(t, err, ErrSegmentedNotMarshalable)
+		_, err = json.Marshal(frame{Type: typeResult, Response: &r})
+		require.ErrorIs(t, err, ErrSegmentedNotMarshalable)
+		_, err = json.Marshal(Response{GrantID: "g", Segments: [][]byte{}})
+		require.ErrorIs(t, err, ErrSegmentedNotMarshalable)
+	})
+}
+
+// partialConn accepts n bytes of a write and then fails.
+type partialConn struct {
+	*fakeConn
+	budget int
+}
+
+func (p *partialConn) Write(b []byte) (int, error) {
+	if p.budget < len(b) {
+		n := p.budget
+		p.budget = 0
+		p.fakeConn.Write(b[:n])
+		return n, errors.New("link broke")
+	}
+	p.budget -= len(b)
+	return p.fakeConn.Write(b)
+}
+
+func TestCompleteAfterPartialWriteSendsNothingMore(t *testing.T) {
+	pc := &partialConn{fakeConn: newFakeConn(), budget: 20}
+	s := NewTestStream(pc)
+	err := s.Complete(context.Background(), Response{GrantID: "g", Payload: pattern(100)})
+	require.ErrorContains(t, err, "link broke")
+	assert.Equal(t, int32(1), pc.closes.Load(), "closed while the slot was held")
+	assert.Zero(t, len(s.wslot))
+	partial := len(pc.written())
+	assert.Less(t, partial, 4+100, "the host holds an incomplete frame")
+
+	pc.budget = 1 << 20
+	require.ErrorIs(t, s.Complete(context.Background(), Response{GrantID: "g2", Payload: []byte("again")}), ErrStreamClosed)
+	assert.Len(t, pc.written(), partial, "the peer receives no further bytes")
+	_, err = readFrame(bytes.NewReader(pc.written()))
+	assert.Error(t, err, "the host has no valid frame to accept")
+}

spinifex/agents/lambda/runtimeapi/server.go

@@ -6,6 +6,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"io"
 	"net/http"
 	"strconv"
@@ -42,6 +43,9 @@ var (
 	ErrDeadlineExceeded = errors.New("runtimeapi: invocation deadline exceeded")
 	// ErrInvalidInvocation is returned by Invoke for an invocation with no request ID.
 	ErrInvalidInvocation = errors.New("runtimeapi: invocation has no request id")
+	// ErrResponseBodyFailed is returned by Invoke when a response or error
+	// body that was admitted could not be read in full. No result exists.
+	ErrResponseBodyFailed = errors.New("runtimeapi: admitted response body was not received")
 )
 
 // Invocation is one event handed to the runtime.
@@ -54,9 +58,11 @@ type Invocation struct {
 }
 
 // Result is what the runtime answered. FunctionError is empty on success and
-// otherwise the error type.
+// otherwise the error type. A non-nil Segments is the payload, in order, and
+// takes precedence over Payload.
 type Result struct {
 	Payload       []byte
+	Segments      [][]byte
 	FunctionError string
 }
 
@@ -66,10 +72,25 @@ type InitError struct {
 	Body []byte
 }
 
+type flightState int
+
+const (
+	stWaiting flightState = iota
+	stRunning
+	stReceiving
+	stCompleted
+	stExited
+)
+
+type outcome struct {
+	res Result
+	err error
+}
+
 type flight struct {
 	inv   Invocation
-	taken bool
-	done  chan Result
+	state flightState
+	done  chan outcome
 }
 
 // Server implements the Runtime API for a single in-flight invocation.
@@ -78,6 +99,11 @@ type Server struct {
 	cur  *flight
 	wake chan struct{}
 
+	// exited records that the bootstrap process has ended; settled that the
+	// last flight has its result, so a later exit no longer matters.
+	exited  bool
+	settled bool
+
 	initOnce sync.Once
 	initDone chan struct{}
 	initErr  InitError
@@ -107,12 +133,16 @@ func (s *Server) Invoke(ctx context.Context, inv Invocation) (Result, error) {
 	if inv.RequestID == "" {
 		return Result{}, ErrInvalidInvocation
 	}
-	f := &flight{inv: inv, done: make(chan Result, 1)}
+	f := &flight{inv: inv, done: make(chan outcome, 1)}
 	s.mu.Lock()
 	if s.cur != nil {
 		s.mu.Unlock()
 		return Result{}, ErrBusy
 	}
+	if s.exited {
+		f.state = stExited
+	}
+	s.settled = false
 	s.cur = f
 	s.mu.Unlock()
 	select {
@@ -124,8 +154,8 @@ func (s *Server) Invoke(ctx context.Context, inv Invocation) (Result, error) {
 	defer timer.Stop()
 	var cause error
 	select {
-	case res := <-f.done:
-		return res, nil
+	case out := <-f.done:
+		return out.res, out.err
 	case <-timer.C:
 		cause = ErrDeadlineExceeded
 	case <-ctx.Done():
@@ -140,7 +170,27 @@ func (s *Server) Invoke(ctx context.Context, inv Invocation) (Result, error) {
 	}
 	s.mu.Unlock()
 	// Completed while we were giving up; the result is already queued.
-	return <-f.done, nil
+	out := <-f.done
+	return out.res, out.err
+}
+
+// BootstrapExited records that the runtime process has ended and reports
+// whether the caller should cancel the invocation. Before the response is
+// admitted it should; afterwards the result stands.
+func (s *Server) BootstrapExited() bool {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.exited = true
+	f := s.cur
+	switch {
+	case f == nil:
+		return !s.settled
+	case f.state < stReceiving:
+		f.state = stExited
+		return true
+	default:
+		return false
+	}
 }
 
 // Handler returns the Runtime API routes.
@@ -157,8 +207,8 @@ func (s *Server) next(w http.ResponseWriter, r *http.Request) {
 	for {
 		s.mu.Lock()
 		f := s.cur
-		if f != nil && !f.taken {
-			f.taken = true
+		if f != nil && f.state == stWaiting {
+			f.state = stRunning
 			s.mu.Unlock()
 			h := w.Header()
 			h.Set(headerRequestID, f.inv.RequestID)
@@ -179,58 +229,149 @@ func (s *Server) next(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
-// claimable reports whether id names the delivered, uncompleted invocation.
-func (s *Server) claimable(id string) bool {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	return s.cur != nil && s.cur.taken && s.cur.inv.RequestID == id
-}
-
-// complete finishes the invocation named id, reporting whether it was live.
-func (s *Server) complete(id string, res Result) bool {
+// admit claims the single response slot of the invocation named id, so only
+// one POST per invocation is ever read. It returns nil if id is not the
+// delivered, unclaimed invocation of a runtime that is still running.
+func (s *Server) admit(id string) *flight {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	f := s.cur
-	if f == nil || !f.taken || f.inv.RequestID != id {
+	if f == nil || f.state != stRunning || f.inv.RequestID != id {
+		return nil
+	}
+	f.state = stReceiving
+	return f
+}
+
+// complete records res for an admitted flight, reporting whether the
+// invocation was still waiting for it.
+func (s *Server) complete(f *flight, res Result) bool {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.cur != f {
 		return false
 	}
 	s.cur = nil
-	f.done <- res
+	s.settled = true
+	f.state = stCompleted
+	f.done <- outcome{res: res}
 	return true
 }
 
+// readFailed ends an admitted flight whose body was lost. The outcome is
+// published before the flight is detached, so Invoke never waits on it.
+func (s *Server) readFailed(f *flight, err error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.cur != f {
+		return
+	}
+	s.cur = nil
+	s.settled = true
+	f.state = stCompleted
+	f.done <- outcome{err: fmt.Errorf("%w: %w", ErrResponseBodyFailed, err)}
+}
+
 func (s *Server) response(w http.ResponseWriter, r *http.Request) {
 	id := r.PathValue("id")
-	if !s.claimable(id) {
+	f := s.admit(id)
+	if f == nil {
 		invalidID(w, id)
 		return
 	}
-	body, err := io.ReadAll(io.LimitReader(r.Body, MaxResponseBytes+1))
+	s.finishResponse(w, r, f)
+}
+
+// segmentBytes is the largest piece an undeclared-length body is read into.
+const segmentBytes = 256 << 10
+
+// finishResponse reads the admitted response body and completes f.
+func (s *Server) finishResponse(w http.ResponseWriter, r *http.Request, f *flight) {
+	var res Result
+	var oversize bool
+	var err error
+	switch cl := r.ContentLength; {
+	case cl > MaxResponseBytes:
+		oversize, err = discardToCap(r.Body)
+	case cl >= 0:
+		res.Payload = make([]byte, cl)
+		_, err = io.ReadFull(r.Body, res.Payload)
+	default:
+		res.Segments, oversize, err = readSegments(r.Body)
+	}
 	if err != nil {
+		s.readFailed(f, err)
 		writeError(w, http.StatusBadRequest, errTypeInvalidRequest, "read body: "+err.Error())
 		return
 	}
-	if len(body) > MaxResponseBytes {
+	if oversize {
 		msg := "Response payload size exceeded maximum allowed payload size (" + strconv.Itoa(MaxResponseBytes) + " bytes)."
-		s.complete(id, Result{Payload: ErrorBody(msg, ErrTypeResponseTooLarge), FunctionError: ErrTypeResponseTooLarge})
+		s.complete(f, Result{Payload: ErrorBody(msg, ErrTypeResponseTooLarge), FunctionError: ErrTypeUnhandled})
 		writeError(w, http.StatusRequestEntityTooLarge, errTypeTooLarge, msg)
 		return
 	}
-	if !s.complete(id, Result{Payload: body}) {
-		invalidID(w, id)
+	if !s.complete(f, res) {
+		invalidID(w, f.inv.RequestID)
 		return
 	}
 	writeStatus(w)
 }
 
+// discardToCap counts body through a small buffer. It reports oversize once
+// byte MaxResponseBytes+1 arrives and an error if the body ends first.
+func discardToCap(body io.Reader) (bool, error) {
+	n, err := io.CopyN(io.Discard, body, MaxResponseBytes+1)
+	if n == MaxResponseBytes+1 {
+		return true, nil
+	}
+	if err == nil || errors.Is(err, io.EOF) {
+		err = io.ErrUnexpectedEOF
+	}
+	return false, err
+}
+
+// readSegments reads body into segments of at most segmentBytes, never
+// concatenating them. It reports oversize and drops them at byte
+// MaxResponseBytes+1.
+func readSegments(body io.Reader) ([][]byte, bool, error) {
+	segs := [][]byte{}
+	total := 0
+	for {
+		n := min(segmentBytes, MaxResponseBytes+1-total)
+		seg := make([]byte, n)
+		got := 0
+		var err error
+		for got < n && err == nil {
+			var c int
+			c, err = body.Read(seg[got:])
+			got += c
+		}
+		total += got
+		if total > MaxResponseBytes {
+			return nil, true, nil
+		}
+		if got > 0 {
+			segs = append(segs, seg[:got])
+		}
+		if errors.Is(err, io.EOF) {
+			return segs, false, nil
+		}
+		if err != nil {
+			return nil, false, err
+		}
+	}
+}
+
 func (s *Server) invocationError(w http.ResponseWriter, r *http.Request) {
 	id := r.PathValue("id")
-	if !s.claimable(id) {
+	f := s.admit(id)
+	if f == nil {
 		invalidID(w, id)
 		return
 	}
 	body, err := io.ReadAll(io.LimitReader(r.Body, MaxResponseBytes))
 	if err != nil {
+		s.readFailed(f, err)
 		writeError(w, http.StatusBadRequest, errTypeInvalidRequest, "read body: "+err.Error())
 		return
 	}
@@ -238,7 +379,7 @@ func (s *Server) invocationError(w http.ResponseWriter, r *http.Request) {
 	if errType == "" {
 		errType = ErrTypeUnhandled
 	}
-	if !s.complete(id, Result{Payload: body, FunctionError: errType}) {
+	if !s.complete(f, Result{Payload: body, FunctionError: errType}) {
 		invalidID(w, id)
 		return
 	}

spinifex/agents/lambda/runtimeapi/server_admission_test.go

@@ -0,0 +1,488 @@
+package runtimeapi
+
+//test:in-package drives the unexported admit and exit transitions to force both orders
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/goleak"
+)
+
+// await bounds a receive so a regression fails promptly instead of hanging.
+func await[T any](t *testing.T, ch <-chan T) T {
+	t.Helper()
+	select {
+	case v := <-ch:
+		return v
+	case <-time.After(15 * time.Second):
+		t.Fatal("timed out waiting on a channel")
+		panic("unreachable")
+	}
+}
+
+// arm puts a delivered, unclaimed flight in place without any HTTP traffic.
+func arm(s *Server, id string) *flight {
+	f := &flight{inv: inv(id, time.Minute), state: stRunning, done: make(chan outcome, 1)}
+	s.mu.Lock()
+	s.cur = f
+	s.mu.Unlock()
+	return f
+}
+
+func postTo(s *Server, kind, id string, body io.Reader, length int64) *httptest.ResponseRecorder {
+	r := httptest.NewRequest(http.MethodPost, base+"invocation/"+id+"/"+kind, body)
+	r.ContentLength = length
+	r.SetPathValue("id", id)
+	rec := httptest.NewRecorder()
+	if kind == "response" {
+		s.response(rec, r)
+	} else {
+		s.invocationError(rec, r)
+	}
+	return rec
+}
+
+// patterned yields n bytes of a repeating pattern without holding them.
+type patterned struct{ n, off int }
+
+func (p *patterned) Read(b []byte) (int, error) {
+	if p.off >= p.n {
+		return 0, io.EOF
+	}
+	c := min(len(b), p.n-p.off)
+	for i := range c {
+		b[i] = byte((p.off + i) % 251)
+	}
+	p.off += c
+	return c, nil
+}
+
+func pattern(n int) []byte {
+	b := make([]byte, n)
+	_, _ = io.ReadFull(&patterned{n: n}, b)
+	return b
+}
+
+func concat(r Result) []byte {
+	if r.Segments == nil {
+		return r.Payload
+	}
+	return bytes.Join(r.Segments, nil)
+}
+
+// counting records whether the handler read the body at all.
+type counting struct{ reads atomic.Int32 }
+
+func (c *counting) Read([]byte) (int, error) { c.reads.Add(1); return 0, io.EOF }
+
+// gated blocks its first Read until released and reports that it started.
+type gated struct {
+	started chan struct{}
+	release chan struct{}
+	rest    io.Reader
+	once    atomic.Bool
+}
+
+func (g *gated) Read(b []byte) (int, error) {
+	if g.once.CompareAndSwap(false, true) {
+		close(g.started)
+		<-g.release
+	}
+	return g.rest.Read(b)
+}
+
+func TestOnlyOnePostPerInvocationIsRead(t *testing.T) {
+	for _, first := range []string{"response", "error"} {
+		for _, second := range []string{"response", "error"} {
+			t.Run(first+"_then_"+second, func(t *testing.T) {
+				s := New()
+				f := arm(s, "req-1")
+				g := &gated{started: make(chan struct{}), release: make(chan struct{}), rest: bytes.NewReader([]byte("body"))}
+				firstDone := make(chan *httptest.ResponseRecorder, 1)
+				go func() { firstDone <- postTo(s, first, "req-1", g, 4) }()
+				await(t, g.started)
+
+				c := &counting{}
+				rec := postTo(s, second, "req-1", c, 4)
+				assert.Equal(t, http.StatusBadRequest, rec.Code)
+				assert.Equal(t, "InvalidRequestID", errType(t, rec.Body.Bytes()))
+				assert.Zero(t, c.reads.Load(), "the refused POST's body was read")
+				assert.Empty(t, f.done, "nothing completes while the admitted body is still arriving")
+
+				close(g.release)
+				assert.Equal(t, http.StatusAccepted, (await(t, firstDone)).Code)
+				assert.Equal(t, "body", string(concat((await(t, f.done)).res)))
+			})
+		}
+	}
+}
+
+func TestDeclaredOversizeCompletesWithoutPayloadBuffer(t *testing.T) {
+	s := New()
+	f := arm(s, "req-1")
+	n := MaxResponseBytes + 10
+	rec := postTo(s, "response", "req-1", &patterned{n: n}, int64(n))
+	assert.Equal(t, http.StatusRequestEntityTooLarge, rec.Code)
+	res := (await(t, f.done)).res
+	assert.Equal(t, ErrTypeUnhandled, res.FunctionError)
+	assert.Equal(t, ErrTypeResponseTooLarge, errType(t, res.Payload))
+
+	br := testing.Benchmark(func(b *testing.B) {
+		b.ReportAllocs()
+		for range b.N {
+			s := New()
+			f := arm(s, "req-1")
+			postTo(s, "response", "req-1", &patterned{n: n}, int64(n))
+			await(t, f.done)
+		}
+	})
+	assert.Less(t, br.AllocedBytesPerOp(), int64(256<<10), "an oversize body must not be buffered")
+}
+
+func TestDeclaredOversizeCutShortIsUnknown(t *testing.T) {
+	s := New()
+	f := arm(s, "req-1")
+	rec := postTo(s, "response", "req-1", &patterned{n: MaxResponseBytes}, MaxResponseBytes+10)
+	assert.Equal(t, http.StatusBadRequest, rec.Code)
+	assert.ErrorIs(t, (await(t, f.done)).err, ErrResponseBodyFailed, "no result is made from a partial body")
+
+	rec = postTo(s, "response", "req-1", &patterned{n: 1}, 1)
+	assert.Equal(t, "InvalidRequestID", errType(t, rec.Body.Bytes()), "the slot stays consumed")
+}
+
+func TestKnownLengthWithinCapAllocatesOnce(t *testing.T) {
+	s := New()
+	f := arm(s, "req-1")
+	rec := postTo(s, "response", "req-1", &patterned{n: MaxResponseBytes}, MaxResponseBytes)
+	assert.Equal(t, http.StatusAccepted, rec.Code)
+	res := (await(t, f.done)).res
+	assert.Nil(t, res.Segments)
+	assert.Equal(t, pattern(MaxResponseBytes), res.Payload)
+
+	s = New()
+	f = arm(s, "req-1")
+	rec = postTo(s, "response", "req-1", &patterned{n: 100}, 200)
+	assert.Equal(t, http.StatusBadRequest, rec.Code, "a body ending short of its length is truncated")
+	out := await(t, f.done)
+	assert.ErrorIs(t, out.err, ErrResponseBodyFailed)
+	assert.Empty(t, out.res.Payload)
+}
+
+func TestChunkedBodyCap(t *testing.T) {
+	t.Run("exactly the cap is accepted in order", func(t *testing.T) {
+		s := New()
+		f := arm(s, "req-1")
+		rec := postTo(s, "response", "req-1", &patterned{n: MaxResponseBytes}, -1)
+		assert.Equal(t, http.StatusAccepted, rec.Code)
+		res := (await(t, f.done)).res
+		assert.Empty(t, res.FunctionError)
+		require.NotNil(t, res.Segments)
+		for _, seg := range res.Segments {
+			assert.LessOrEqual(t, len(seg), segmentBytes)
+		}
+		assert.Equal(t, pattern(MaxResponseBytes), concat(res))
+	})
+	t.Run("one byte over completes as too large", func(t *testing.T) {
+		s := New()
+		f := arm(s, "req-1")
+		rec := postTo(s, "response", "req-1", &patterned{n: MaxResponseBytes + 1}, -1)
+		assert.Equal(t, http.StatusRequestEntityTooLarge, rec.Code)
+		res := (await(t, f.done)).res
+		assert.Equal(t, ErrTypeResponseTooLarge, errType(t, res.Payload))
+	})
+	t.Run("empty body is an empty non-nil payload", func(t *testing.T) {
+		s := New()
+		f := arm(s, "req-1")
+		postTo(s, "response", "req-1", &patterned{}, -1)
+		res := (await(t, f.done)).res
+		require.NotNil(t, res.Segments)
+		assert.Empty(t, concat(res))
+	})
+	t.Run("peak allocation stays within the cap plus one segment", func(t *testing.T) {
+		for _, n := range []int{MaxResponseBytes, MaxResponseBytes + 1} {
+			br := testing.Benchmark(func(b *testing.B) {
+				b.ReportAllocs()
+				for range b.N {
+					s := New()
+					f := arm(s, "req-1")
+					postTo(s, "response", "req-1", &patterned{n: n}, -1)
+					await(t, f.done)
+				}
+			})
+			assert.Less(t, br.AllocedBytesPerOp(), int64(MaxResponseBytes+segmentBytes+64<<10), "body of %d bytes", n)
+		}
+	})
+}
+
+func TestErrorPostOverCapKeepsTruncatedPayload(t *testing.T) {
+	s := New()
+	f := arm(s, "req-1")
+	n := MaxResponseBytes + 100
+	rec := postTo(s, "error", "req-1", &patterned{n: n}, int64(n))
+	assert.Equal(t, http.StatusAccepted, rec.Code)
+	res := (await(t, f.done)).res
+	assert.Equal(t, ErrTypeUnhandled, res.FunctionError)
+	assert.Equal(t, pattern(MaxResponseBytes), res.Payload)
+}
+
+func TestBootstrapExitBeforeAdmissionCancels(t *testing.T) {
+	t.Run("before the flight exists", func(t *testing.T) {
+		s := New()
+		assert.True(t, s.BootstrapExited())
+		ctx := t.Context()
+		go func() { _, _ = s.Invoke(ctx, inv("req-1", time.Minute)) }()
+		require.Eventually(t, func() bool {
+			s.mu.Lock()
+			defer s.mu.Unlock()
+			return s.cur != nil && s.cur.state == stExited
+		}, time.Second, time.Millisecond, "the flight is created already exited")
+	})
+	t.Run("before next", func(t *testing.T) {
+		s := New()
+		f := arm(s, "req-1")
+		f.state = stWaiting
+		assert.True(t, s.BootstrapExited())
+		assert.Equal(t, stExited, f.state)
+	})
+	t.Run("after next", func(t *testing.T) {
+		s := New()
+		f := arm(s, "req-1")
+		assert.True(t, s.BootstrapExited())
+		assert.Equal(t, stExited, f.state)
+	})
+}
+
+func TestExitWinsTheRace(t *testing.T) {
+	s := New()
+	f := arm(s, "req-1")
+	require.True(t, s.BootstrapExited())
+
+	c := &counting{}
+	rec := postTo(s, "response", "req-1", c, 4)
+	assert.Equal(t, http.StatusBadRequest, rec.Code)
+	assert.Equal(t, "InvalidRequestID", errType(t, rec.Body.Bytes()))
+	assert.Zero(t, c.reads.Load())
+	assert.Empty(t, f.done)
+}
+
+func TestAdmissionWinsTheRace(t *testing.T) {
+	s := New()
+	f := arm(s, "req-1")
+	adm := s.admit("req-1")
+	require.NotNil(t, adm)
+	assert.False(t, s.BootstrapExited(), "an admitted response is not cancelled by the exit")
+
+	r := httptest.NewRequest(http.MethodPost, "/", bytes.NewReader([]byte("late body")))
+	rec := httptest.NewRecorder()
+	s.finishResponse(rec, r, adm)
+	assert.Equal(t, http.StatusAccepted, rec.Code)
+	assert.Equal(t, "late body", string((await(t, f.done)).res.Payload))
+	assert.False(t, s.BootstrapExited(), "a recorded result stands")
+}
+
+func TestExitedAfterResultIsIgnored(t *testing.T) {
+	s := New()
+	f := arm(s, "req-1")
+	postTo(s, "response", "req-1", bytes.NewReader([]byte("ok")), 2)
+	await(t, f.done)
+	assert.False(t, s.BootstrapExited())
+}
+
+// failing yields some bytes and then a read error, as a reset connection does.
+type failing struct{ left int }
+
+func (f *failing) Read(b []byte) (int, error) {
+	if f.left == 0 {
+		return 0, io.ErrClosedPipe
+	}
+	n := min(len(b), f.left)
+	f.left -= n
+	return n, nil
+}
+
+// invokeReady runs Invoke on a real flight that the runtime has taken.
+func invokeReady(t *testing.T, s *Server, ctx context.Context) <-chan invokeOut {
+	t.Helper()
+	out := make(chan invokeOut, 1)
+	go func() {
+		res, err := s.Invoke(ctx, inv("req-1", time.Minute))
+		out <- invokeOut{res, err}
+	}()
+	require.Eventually(t, func() bool {
+		s.mu.Lock()
+		defer s.mu.Unlock()
+		if s.cur != nil && s.cur.state == stWaiting {
+			s.cur.state = stRunning
+		}
+		return s.cur != nil && s.cur.state == stRunning
+	}, time.Second, time.Millisecond)
+	return out
+}
+
+func TestLiveBootstrapTruncatedBodyEndsInvokeAtOnce(t *testing.T) {
+	defer goleak.VerifyNone(t, goleak.IgnoreCurrent())
+	s := New()
+	out := invokeReady(t, s, context.Background()) // a minute-long deadline
+	adm := s.admit("req-1")
+	require.NotNil(t, adm)
+	s.finishResponse(httptest.NewRecorder(), httptest.NewRequest(http.MethodPost, "/", &failing{left: 3}), adm)
+	select {
+	case got := <-out:
+		require.ErrorIs(t, got.err, ErrResponseBodyFailed)
+		assert.Empty(t, got.res.Payload)
+		assert.Empty(t, got.res.FunctionError)
+	case <-time.After(5 * time.Second):
+		t.Fatal("Invoke waited for its deadline")
+	}
+}
+
+func TestIncompleteBodyNeverStrandsInvoke(t *testing.T) {
+	// A body that fails after admission loses the result. The flight must end
+	// with an explicit outcome whichever of the read failure, the bootstrap
+	// exit and the invocation ending comes first.
+	steps := map[string]func(s *Server, adm *flight, cancel context.CancelFunc){
+		"read fails": func(s *Server, adm *flight, _ context.CancelFunc) {
+			s.finishResponse(httptest.NewRecorder(), httptest.NewRequest(http.MethodPost, "/", &failing{left: 3}), adm)
+		},
+		"bootstrap exits":      func(s *Server, _ *flight, _ context.CancelFunc) { s.BootstrapExited() },
+		"invocation cancelled": func(_ *Server, _ *flight, cancel context.CancelFunc) { cancel() },
+	}
+	orders := [][]string{
+		{"read fails", "bootstrap exits", "invocation cancelled"},
+		{"bootstrap exits", "read fails", "invocation cancelled"},
+		{"invocation cancelled", "read fails", "bootstrap exits"},
+		{"invocation cancelled", "bootstrap exits", "read fails"},
+		{"read fails", "invocation cancelled", "bootstrap exits"},
+		{"bootstrap exits", "invocation cancelled", "read fails"},
+	}
+	for _, order := range orders {
+		t.Run(order[0]+"_"+order[1]+"_"+order[2], func(t *testing.T) {
+			defer goleak.VerifyNone(t, goleak.IgnoreCurrent())
+			s := New()
+			ctx, cancel := context.WithCancel(context.Background())
+			defer cancel()
+			out := invokeReady(t, s, ctx)
+			adm := s.admit("req-1")
+			require.NotNil(t, adm)
+			// Whichever of the read failure and the cancellation comes first
+			// decides the outcome; the exit changes nothing once admitted.
+			want := ErrResponseBodyFailed
+			for _, step := range order {
+				if step == "invocation cancelled" {
+					want = context.Canceled
+				}
+				if step != "bootstrap exits" {
+					break
+				}
+			}
+			var got invokeOut
+			returned := false
+			for _, step := range order {
+				steps[step](s, adm, cancel)
+				if step == "invocation cancelled" {
+					// Settle the cancellation before the next transition.
+					select {
+					case got = <-out:
+						returned = true
+					case <-time.After(5 * time.Second):
+						t.Fatal("Invoke did not return after cancel")
+					}
+				}
+			}
+			if !returned {
+				select {
+				case got = <-out:
+				case <-time.After(5 * time.Second):
+					t.Fatal("Invoke did not return")
+				}
+			}
+			require.ErrorIs(t, got.err, want)
+			assert.Empty(t, got.res.Payload)
+			assert.Empty(t, got.res.FunctionError)
+			s.mu.Lock()
+			defer s.mu.Unlock()
+			assert.Nil(t, s.cur, "the flight must be detached")
+		})
+	}
+}
+
+func TestIncompleteBodyAndDeadlineInBothOrders(t *testing.T) {
+	t.Run("deadline first", func(t *testing.T) {
+		defer goleak.VerifyNone(t, goleak.IgnoreCurrent())
+		s := New()
+		out := make(chan invokeOut, 1)
+		go func() {
+			res, err := s.Invoke(context.Background(), inv("req-1", 20*time.Millisecond))
+			out <- invokeOut{res, err}
+		}()
+		require.Eventually(t, func() bool {
+			s.mu.Lock()
+			defer s.mu.Unlock()
+			if s.cur != nil && s.cur.state == stWaiting {
+				s.cur.state = stRunning
+			}
+			return s.cur != nil
+		}, time.Second, time.Millisecond)
+		adm := s.admit("req-1")
+		require.NotNil(t, adm)
+		select {
+		case got := <-out:
+			require.ErrorIs(t, got.err, ErrDeadlineExceeded)
+		case <-time.After(5 * time.Second):
+			t.Fatal("Invoke did not time out")
+		}
+		s.finishResponse(httptest.NewRecorder(), httptest.NewRequest(http.MethodPost, "/", &failing{left: 1}), adm)
+		assert.Empty(t, adm.done, "a late failure publishes nothing")
+	})
+	t.Run("body failure first", func(t *testing.T) {
+		defer goleak.VerifyNone(t, goleak.IgnoreCurrent())
+		s := New()
+		out := invokeReady(t, s, context.Background())
+		adm := s.admit("req-1")
+		require.NotNil(t, adm)
+		s.finishResponse(httptest.NewRecorder(), httptest.NewRequest(http.MethodPost, "/", &failing{left: 1}), adm)
+		require.ErrorIs(t, (await(t, out)).err, ErrResponseBodyFailed)
+	})
+}
+
+// The reply a bootstrap sees to an oversize body is recorded here, not
+// claimed to match AWS.
+func TestOversizeBootstrapVisibleReply(t *testing.T) {
+	cases := map[string]struct {
+		length int64
+		size   int
+	}{
+		"declared length": {MaxResponseBytes + 2, MaxResponseBytes + 2},
+		"chunked":         {-1, MaxResponseBytes + 2},
+	}
+	for name, tc := range cases {
+		t.Run(name, func(t *testing.T) {
+			s, ts := start(t)
+			out := invokeAsync(s, inv("req-1", 10*time.Second))
+			get(t, ts.URL+base+"invocation/next")
+			req, err := http.NewRequest(http.MethodPost, ts.URL+base+"invocation/req-1/response", io.NopCloser(&patterned{n: tc.size}))
+			require.NoError(t, err)
+			req.ContentLength = tc.length
+			resp, err := http.DefaultClient.Do(req)
+			if err != nil {
+				t.Logf("bootstrap-visible: transport error: %v", err)
+			} else {
+				defer resp.Body.Close()
+				t.Logf("bootstrap-visible: status %d", resp.StatusCode)
+				assert.Equal(t, http.StatusRequestEntityTooLarge, resp.StatusCode)
+			}
+			got := await(t, out)
+			require.NoError(t, got.err)
+			assert.Equal(t, ErrTypeResponseTooLarge, errType(t, got.res.Payload))
+		})
+	}
+}

spinifex/agents/lambda/runtimeapi/server_test.go

@@ -170,7 +170,7 @@ func TestOversizeResponse(t *testing.T) {
 
 	got := <-out
 	require.NoError(t, got.err)
-	assert.Equal(t, "Function.ResponseSizeTooLarge", got.res.FunctionError)
+	assert.Equal(t, "Unhandled", got.res.FunctionError)
 	assert.Equal(t, "Function.ResponseSizeTooLarge", errType(t, got.res.Payload))
 }
 

spinifex/agents/rds/agent/parameters.go

@@ -4,11 +4,13 @@ import (
 	"bytes"
 	"context"
 	"fmt"
+	"math"
 	"os"
 	"path/filepath"
 	"sync"
 	"time"
 
+	"github.com/mulgadc/bluebottle/pkg/safecast"
 	rdsinstance "github.com/mulgadc/spinifex/spinifex/domains/rds/instance"
 )
 
@@ -106,12 +108,29 @@ func (s parameterStore) chownToEngine(path string) error {
 	if err != nil {
 		return err
 	}
-	if err := os.Chown(path, int(credential.Uid), int(credential.Gid)); err != nil {
+	uid, err := ownerID(credential.Uid)
+	if err != nil {
+		return fmt.Errorf("uid of %s: %w", s.osUser, err)
+	}
+	gid, err := ownerID(credential.Gid)
+	if err != nil {
+		return fmt.Errorf("gid of %s: %w", s.osUser, err)
+	}
+	if err := os.Chown(path, uid, gid); err != nil {
 		return fmt.Errorf("hand %s to %s: %w", path, s.osUser, err)
 	}
 	return nil
 }
 
+// Rejects rather than saturates: a clamped ID would hand the file to another
+// account while the engine still runs as the real one.
+func ownerID(id uint32) (int, error) {
+	if uint64(id) > math.MaxInt {
+		return 0, fmt.Errorf("%d does not fit an int", id)
+	}
+	return safecast.Uint64ToInt(uint64(id)), nil
+}
+
 // Snapshots the installed set as the rollback target, but only once the engine
 // is running all of it. A set still pending a restart has not been shown to
 // serve, so promoting it would point the rollback at a config about to fail.

spinifex/bootstrap/config/config.go

@@ -111,7 +111,7 @@ type AWSConfig struct {
 // ExternalPool defines a range of routable IPs that Spinifex manages for public subnets.
 type ExternalPool struct {
 	Name       string   `mapstructure:"name"`        // Pool identifier (e.g., "wan", "dc1-primary")
-	Source     string   `mapstructure:"source"`      // IP source: "static" (default), "dhcp", "oci", "exoscale" or "vultr"
+	Source     string   `mapstructure:"source"`      // IP source: "static" (default), "dhcp", "oci", "exoscale", "vultr" or "latitude"
 	BindBridge string   `mapstructure:"bind_bridge"` // Linux bridge for DHCP DORA (source=dhcp only)
 	DHCPMAC    string   `mapstructure:"dhcp_mac"`    // DHCP client MAC strategy: "derived" (default) or "interface" (source=dhcp only)
 	RangeStart string   `mapstructure:"range_start"` // First IP in range (static source only)
@@ -155,6 +155,17 @@ type ExternalPool struct {
 	VultrRegion  string `mapstructure:"vultr_region"`   // Vultr region ID, e.g. "ord"; never derived from the Spinifex region
 	VultrKeyFile string `mapstructure:"vultr_key_file"` // API key file (optional; see vultr.DefaultKeyFile)
 	LabelPrefix  string `mapstructure:"label_prefix"`   // Marks this deployment's addresses, e.g. "spinifex-prod"
+
+	// Latitude names the project, token file and fixed set of Elastic IPs
+	// (source=latitude only). Each node's server ID is provider_host_id on the node.
+	LatitudeProjectID    string   `mapstructure:"latitude_project_id"`     // latitude.sh project ID the Elastic IPs belong to
+	LatitudeKeyFile      string   `mapstructure:"latitude_key_file"`       // API token file (optional; see latitude.DefaultKeyFile)
+	LatitudeElasticIPIDs []string `mapstructure:"latitude_elastic_ip_ids"` // Elastic IP IDs the pool hands out
+}
+
+// hasLatitudeKeys reports whether any latitude_* key is set.
+func (p ExternalPool) hasLatitudeKeys() bool {
+	return p.LatitudeProjectID != "" || p.LatitudeKeyFile != "" || len(p.LatitudeElasticIPIDs) > 0
 }
 
 // hasVultrKeys reports whether any vultr_* key, or the label prefix only a
@@ -251,7 +262,7 @@ type Config struct {
 
 	// ProviderHostID is this node's instance ID at its cloud provider, which a
 	// floating public address is attached to. Required on every node when a
-	// source="vultr" pool exists.
+	// source="vultr" or source="latitude" pool exists.
 	ProviderHostID string `json:"ProviderHostID,omitempty" mapstructure:"provider_host_id"`
 
 	Daemon      DaemonConfig      `json:"Daemon" mapstructure:"daemon"`
@@ -807,6 +818,53 @@ func validateVultrPool(cc *ClusterConfig, p ExternalPool) error {
 	return nil
 }
 
+// MaxLatitudeElasticIPs bounds a latitude pool: latitude.sh allows five Elastic IPs per team, and
+// every allocation reads each configured address from the API.
+const MaxLatitudeElasticIPs = 5
+
+// validateLatitudePool checks a source="latitude" pool. The Elastic IPs are
+// bought ahead of time and named here, the API picks nothing, so the range,
+// gateway and label keys mean nothing, and every node must name its server.
+func validateLatitudePool(cc *ClusterConfig, p ExternalPool) error {
+	if p.LatitudeProjectID == "" || len(p.LatitudeElasticIPIDs) == 0 {
+		return fmt.Errorf("config: [[network.external_pools]] %q: source=\"latitude\" requires latitude_project_id and latitude_elastic_ip_ids", p.Name)
+	}
+	if len(p.LatitudeElasticIPIDs) > MaxLatitudeElasticIPs {
+		return fmt.Errorf("config: [[network.external_pools]] %q: latitude_elastic_ip_ids lists %d addresses, at most %d are allowed", p.Name, len(p.LatitudeElasticIPIDs), MaxLatitudeElasticIPs)
+	}
+	seen := map[string]struct{}{}
+	for _, id := range p.LatitudeElasticIPIDs {
+		if id == "" {
+			return fmt.Errorf("config: [[network.external_pools]] %q: latitude_elastic_ip_ids has an empty entry", p.Name)
+		}
+		if _, dup := seen[id]; dup {
+			return fmt.Errorf("config: [[network.external_pools]] %q: latitude_elastic_ip_ids lists %q twice", p.Name, id)
+		}
+		seen[id] = struct{}{}
+	}
+	if p.LatitudeKeyFile != "" && !filepath.IsAbs(p.LatitudeKeyFile) {
+		return fmt.Errorf("config: [[network.external_pools]] %q: latitude_key_file must be an absolute path, got %q", p.Name, p.LatitudeKeyFile)
+	}
+	if p.BindBridge != "" || p.DHCPMAC != "" {
+		return fmt.Errorf("config: [[network.external_pools]] %q: bind_bridge/dhcp_mac are only valid with source=\"dhcp\"", p.Name)
+	}
+	if p.RangeStart != "" || p.RangeEnd != "" || p.Gateway != "" || p.GatewayIP != "" {
+		return fmt.Errorf("config: [[network.external_pools]] %q: range_start/range_end/gateway/gateway_ip not allowed with source=\"latitude\" (the Elastic IPs are listed by ID)", p.Name)
+	}
+	if p.GwLrpRangeStart != "" || p.GwLrpRangeEnd != "" {
+		return fmt.Errorf("config: [[network.external_pools]] %q: gw_lrp_range_start/gw_lrp_range_end not allowed with source=\"latitude\" (a gateway address per VPC would use up the Elastic IP limit)", p.Name)
+	}
+	if cc.Network.ExternalMode != "nat" {
+		return fmt.Errorf("config: [[network.external_pools]] %q: source=\"latitude\" requires [network] external_mode = \"nat\" (routed); a routed Elastic IP is delivered to the server's own MAC", p.Name)
+	}
+	for name, n := range cc.Nodes {
+		if n.ProviderHostID == "" {
+			return fmt.Errorf("config: [nodes.%s] provider_host_id is required with a source=\"latitude\" pool (%q): it is the latitude.sh server ID the node's Elastic IPs move to", name, p.Name)
+		}
+	}
+	return nil
+}
+
 // validateSingleEBSProvider refuses nodes whose explicit [nodes.<name>.ebs]
 // providers differ. A peer stanza without one is unknown, not the default: the
 // generated config omits it, and the cluster's KV lock is the authoritative check.
@@ -879,6 +937,9 @@ func validateClusterConfig(cc *ClusterConfig) error {
 		end   netip.Addr
 	}
 	var ranges []poolRange
+	// latitudeIDs maps each Elastic IP ID to the pool naming it. Every pool keeps its own
+	// record of what it handed out, so an ID in two pools would be given to two guests.
+	latitudeIDs := map[string]string{}
 	for _, p := range cc.Network.ExternalPools {
 		if p.Source != "oci" && (p.OCICompartmentID != "" || p.OCIVNICID != "" || p.OCIVNICIface != "" || p.OCISubnetID != "" || p.OCIPublicIPPool != "" || p.OCIConfigFile != "" || p.OCIConfigProfile != "") {
 			return fmt.Errorf("config: [[network.external_pools]] %q: oci_* keys are only valid with source=\"oci\"", p.Name)
@@ -886,6 +947,9 @@ func validateClusterConfig(cc *ClusterConfig) error {
 		if p.Source != "exoscale" && p.hasExoscaleKeys() {
 			return fmt.Errorf("config: [[network.external_pools]] %q: exoscale_* keys are only valid with source=\"exoscale\"", p.Name)
 		}
+		if p.Source != "latitude" && p.hasLatitudeKeys() {
+			return fmt.Errorf("config: [[network.external_pools]] %q: latitude_* keys are only valid with source=\"latitude\"", p.Name)
+		}
 		if p.Source != "vultr" && p.hasVultrKeys() {
 			return fmt.Errorf("config: [[network.external_pools]] %q: vultr_* and label_prefix keys are only valid with source=\"vultr\"", p.Name)
 		}
@@ -985,8 +1049,19 @@ func validateClusterConfig(cc *ClusterConfig) error {
 				return err
 			}
 			continue
+		case "latitude":
+			if err := validateLatitudePool(cc, p); err != nil {
+				return err
+			}
+			for _, id := range p.LatitudeElasticIPIDs {
+				if other, dup := latitudeIDs[id]; dup {
+					return fmt.Errorf("config: [[network.external_pools]] %q: Elastic IP %q is also named by pool %q; each Elastic IP may belong to one pool", p.Name, id, other)
+				}
+				latitudeIDs[id] = p.Name
+			}
+			continue
 		default:
-			return fmt.Errorf("config: [[network.external_pools]] %q: source=%q unsupported; use \"static\", \"dhcp\", \"oci\", \"exoscale\" or \"vultr\"", p.Name, p.Source)
+			return fmt.Errorf("config: [[network.external_pools]] %q: source=%q unsupported; use \"static\", \"dhcp\", \"oci\", \"exoscale\", \"vultr\" or \"latitude\"", p.Name, p.Source)
 		}
 		if p.RangeStart == "" || p.RangeEnd == "" {
 			continue

spinifex/bootstrap/config/config_test.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/spf13/viper"
@@ -1550,6 +1551,83 @@ func TestLoadConfig_NetworkPoolVultrRejections(t *testing.T) {
 	}
 }
 
+const latitudePoolBase = `
+source = "latitude"
+latitude_project_id = "proj_1"
+latitude_elastic_ip_ids = ["eip_1", "eip_2"]
+`
+
+func TestLoadConfig_NetworkPoolLatitudeSourceAccepted(t *testing.T) {
+	cfg, err := loadVultrPool(t, "nat", latitudePoolBase+"latitude_key_file = \"/etc/spinifex/latitude/api-token\"\n",
+		[2]string{"sv_a", "sv_b"})
+	require.NoError(t, err)
+	p := cfg.Network.ExternalPools[0]
+	assert.Equal(t, "latitude", p.Source)
+	assert.Equal(t, "proj_1", p.LatitudeProjectID)
+	assert.Equal(t, []string{"eip_1", "eip_2"}, p.LatitudeElasticIPIDs)
+	assert.Equal(t, "/etc/spinifex/latitude/api-token", p.LatitudeKeyFile)
+	assert.Equal(t, "sv_a", cfg.Nodes["n1"].ProviderHostID)
+}
+
+func latitudeIDs(n int) string {
+	ids := make([]string, n)
+	for i := range ids {
+		ids[i] = fmt.Sprintf("%q", fmt.Sprintf("eip_%d", i))
+	}
+	return "source = \"latitude\"\nlatitude_project_id = \"p\"\nlatitude_elastic_ip_ids = [" + strings.Join(ids, ", ") + "]\n"
+}
+
+func TestLoadConfig_NetworkPoolLatitudeSetIsCapped(t *testing.T) {
+	cfg, err := loadVultrPool(t, "nat", latitudeIDs(MaxLatitudeElasticIPs), [2]string{"a", "b"})
+	require.NoError(t, err)
+	assert.Len(t, cfg.Network.ExternalPools[0].LatitudeElasticIPIDs, MaxLatitudeElasticIPs)
+
+	_, err = loadVultrPool(t, "nat", latitudeIDs(MaxLatitudeElasticIPs+1), [2]string{"a", "b"})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "at most 5 are allowed")
+}
+
+func TestLoadConfig_NetworkPoolLatitudeRejections(t *testing.T) {
+	both := [2]string{"a", "b"}
+	cases := []struct {
+		name, mode, body string
+		nodes            [2]string
+		want             string
+	}{
+		{"pool mode", "pool", latitudePoolBase, both, `requires [network] external_mode = "nat"`},
+		{"no project", "nat", "source = \"latitude\"\nlatitude_elastic_ip_ids = [\"e\"]\n", both, "requires latitude_project_id and latitude_elastic_ip_ids"},
+		{"no ids", "nat", "source = \"latitude\"\nlatitude_project_id = \"p\"\n", both, "requires latitude_project_id and latitude_elastic_ip_ids"},
+		{"duplicate id", "nat", "source = \"latitude\"\nlatitude_project_id = \"p\"\nlatitude_elastic_ip_ids = [\"e\", \"e\"]\n", both, "twice"},
+		{"empty id", "nat", "source = \"latitude\"\nlatitude_project_id = \"p\"\nlatitude_elastic_ip_ids = [\"\"]\n", both, "empty entry"},
+		{"relative key file", "nat", latitudePoolBase + "latitude_key_file = \"token\"\n", both, "absolute path"},
+		{"label prefix", "nat", latitudePoolBase + "label_prefix = \"x\"\n", both, "only valid with source=\"vultr\""},
+		{"range", "nat", latitudePoolBase + "range_start = \"1.2.3.4\"\nrange_end = \"1.2.3.4\"\n", both, "listed by ID"},
+		{"a node without its server id", "nat", latitudePoolBase, [2]string{"a", ""}, "[nodes.n2] provider_host_id is required"},
+		{"latitude keys on static", "nat", "latitude_project_id = \"p\"\n", both, `only valid with source="latitude"`},
+		{"vultr keys on latitude", "nat", latitudePoolBase + "vultr_region = \"ord\"\n", both, `only valid with source="vultr"`},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := loadVultrPool(t, tc.mode, tc.body, tc.nodes)
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), tc.want)
+		})
+	}
+}
+
+func TestLoadConfig_NetworkPoolLatitudeIDInTwoPoolsIsRejected(t *testing.T) {
+	resetViper(t)
+	body := "node = \"n1\"\n\n[network]\nexternal_mode = \"nat\"\n\n" +
+		"[[network.external_pools]]\nname = \"a\"\nsource = \"latitude\"\nlatitude_project_id = \"p\"\nlatitude_elastic_ip_ids = [\"e1\", \"e2\"]\n\n" +
+		"[[network.external_pools]]\nname = \"b\"\nsource = \"latitude\"\nlatitude_project_id = \"p\"\nlatitude_elastic_ip_ids = [\"e3\", \"e2\"]\n\n" +
+		"[nodes.n1]\nregion = \"us-east-1\"\nprovider_host_id = \"sv_1\"\n"
+	path := filepath.Join(t.TempDir(), "spinifex.toml")
+	require.NoError(t, os.WriteFile(path, []byte(body), 0600))
+	_, err := LoadConfig(path)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), `"e2" is also named by pool "a"`)
+}
+
 func TestLoadConfig_NorthstarNameservers(t *testing.T) {
 	load := func(t *testing.T, block string) (*ClusterConfig, error) {
 		t.Helper()