chore(ci): retry lstk interception and pin the lstk CLI version

.github/workflows/run-samples.yml

@@ -179,12 +179,25 @@ jobs:
         # Required by run-samples.sh to proxy Azure CLI calls to the emulator
         # via `lstk az` (replaces the deprecated azlocal wrapper).
         # https://github.com/localstack/lstk
+        #
+        # Pinned, like every action in this workflow: an unpinned install means an upstream
+        # release lands in every run at once, with no commit to point at when things break.
+        # Bump deliberately.
+        env:
+          # 0.19.0, not the current 0.20.0. Since 0.20.0 was published (2026-07-30 11:10) every
+          # sample run has failed at `lstk az start-interception` with "LocalStack Azure Emulator
+          # is not running" - 6 runs across 4 unrelated branches, while the emulator was up and
+          # answering its health endpoint. Detection fails on roughly 80% of fresh runners, is
+          # decided before the first call (retries never recover it), and reproduces on neither
+          # arch locally. Every run on 0.19.0 was green.
+          # Revert to the latest release once the detection regression is fixed upstream.
+          LSTK_VERSION: "0.19.0"
         run: |
           MAX_RETRIES=3
           DELAY=15
           for i in $(seq 1 $MAX_RETRIES); do
             echo "Attempt $i/$MAX_RETRIES..."
-            npm install -g @localstack/lstk && break
+            npm install -g "@localstack/lstk@${LSTK_VERSION}" && break
             if [ "$i" -eq "$MAX_RETRIES" ]; then
               echo "All $MAX_RETRIES attempts failed"
               exit 1

run-samples.sh

@@ -134,7 +134,35 @@ fi
 
 if command -v lstk >/dev/null 2>&1; then
   echo "[DEBUG] Starting lstk az interception..."
-  lstk az start-interception
+  # lstk's emulator detection can report a running emulator as absent - `lstk status` has been
+  # observed answering "LocalStack AWS Emulator is not running" against a live emulator, and CI
+  # runs have failed here with "LocalStack Azure Emulator is not running" while the container was
+  # up and `localstack wait` had already returned. Retry before giving up.
+  #
+  # Deliberately still fatal after the last attempt: without interception the az CLI targets real
+  # Azure, so continuing would send this suite's commands to the cloud. The diagnostics below run
+  # only on the final failure, so the next occurrence is debuggable from the log alone.
+  INTERCEPTION_ATTEMPTS=5
+  for attempt in $(seq 1 "$INTERCEPTION_ATTEMPTS"); do
+    if lstk az start-interception; then
+      break
+    fi
+    if [ "$attempt" -eq "$INTERCEPTION_ATTEMPTS" ]; then
+      echo "[ERROR] lstk could not attach to the emulator after $INTERCEPTION_ATTEMPTS attempts."
+      echo "[ERROR] --- lstk version ---"
+      lstk --version 2>&1 || true
+      echo "[ERROR] --- container ---"
+      docker ps -a --filter name=localstack-main --format '{{.Names}} | {{.Image}} | {{.Status}}' || true
+      echo "[ERROR] --- emulator health ---"
+      curl -s --max-time 10 http://127.0.0.1:4566/_localstack/health || true
+      echo ""
+      echo "[ERROR] --- lstk log ---"
+      tail -30 "${XDG_CONFIG_HOME:-$HOME/.config}/lstk/lstk.log" 2>/dev/null || true
+      exit 1
+    fi
+    echo "[DEBUG] interception attempt $attempt failed; retrying in $((attempt * 5))s..."
+    sleep $((attempt * 5))
+  done
   # With interception active, the standard az CLI targets the emulator directly.
   # The `lstk az` proxy is intentionally not used below: it requires a one-time
   # Azure CLI integration setup that is not available on headless CI runners.