Use canonical HEXCLAVE_* env vars across all GitHub Actions

Rename every STACK_*-prefixed env var to HEXCLAVE_* in the workflow files
(the legacy names still work via dual-read, but canonical is clearer and
avoids dual-read conflict checks firing on differing committed defaults).

- secrets.STACK_FREESTYLE_REAL_API_KEY is a repo secret, left unchanged; only
  the env-var key it's assigned to (HEXCLAVE_FREESTYLE_API_KEY) is renamed.
- HEXCLAVE_EMULATOR_HOME (qemu-emulator-build) is read directly via process.env
  in the CLI, not the dual-read helper, so emulator-paths.ts now reads
  HEXCLAVE_EMULATOR_HOME with a STACK_EMULATOR_HOME fallback.
- Also drop the explanatory comment added for the local-emulator flag.

.github/workflows/db-migration-backwards-compatibility.yaml

@@ -54,8 +54,8 @@ jobs:
     runs-on: ubicloud-standard-8
     env:
       NODE_ENV: test
-      STACK_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
-      STACK_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:8128/stackframe"
+      HEXCLAVE_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
+      HEXCLAVE_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:8128/stackframe"
 
     steps:
       # First, checkout the current branch to get its migrations
@@ -255,8 +255,8 @@ jobs:
     runs-on: ubicloud-standard-8
     env:
       NODE_ENV: test
-      STACK_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
-      STACK_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:8128/stackframe"
+      HEXCLAVE_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
+      HEXCLAVE_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:8128/stackframe"
 
     steps:
       # First, checkout the base branch to get its migrations

.github/workflows/e2e-api-tests-local-emulator.yaml

@@ -17,16 +17,11 @@ jobs:
     runs-on: ubicloud-standard-8
     env:
       NODE_ENV: test
-      # Use the canonical HEXCLAVE_ name: the dashboard commits a differing
-      # NEXT_PUBLIC_HEXCLAVE_IS_LOCAL_EMULATOR=false in .env.development, and the
-      # dual-read conflict check throws if both spellings are set to different
-      # values. Setting the canonical name here overrides that committed default
-      # (process.env wins over dotenv) without leaving a conflicting STACK_ twin.
       NEXT_PUBLIC_HEXCLAVE_IS_LOCAL_EMULATOR: "true"
-      STACK_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
-      STACK_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:8128/stackframe"
-      STACK_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
-      STACK_EXTERNAL_DB_SYNC_DIRECT: "false"
+      HEXCLAVE_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
+      HEXCLAVE_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:8128/stackframe"
+      HEXCLAVE_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
+      HEXCLAVE_EXTERNAL_DB_SYNC_DIRECT: "false"
 
     strategy:
       matrix:

.github/workflows/e2e-api-tests.yaml

@@ -17,10 +17,10 @@ jobs:
     runs-on: ubicloud-standard-8
     env:
       NODE_ENV: test
-      STACK_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
-      STACK_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:8128/stackframe"
-      STACK_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
-      STACK_EXTERNAL_DB_SYNC_DIRECT: "false"
+      HEXCLAVE_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
+      HEXCLAVE_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:8128/stackframe"
+      HEXCLAVE_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
+      HEXCLAVE_EXTERNAL_DB_SYNC_DIRECT: "false"
 
     strategy:
       matrix:
@@ -59,7 +59,7 @@ jobs:
       - name: Override Freestyle API key for prod mode
         if: matrix.freestyle-mode == 'prod'
         run: |
-          echo "STACK_FREESTYLE_API_KEY=${{ secrets.STACK_FREESTYLE_REAL_API_KEY }}" >> apps/backend/.env.test.local
+          echo "HEXCLAVE_FREESTYLE_API_KEY=${{ secrets.STACK_FREESTYLE_REAL_API_KEY }}" >> apps/backend/.env.test.local
 
       - name: Create .env.test.local file for apps/dashboard
         run: cp apps/dashboard/.env.development apps/dashboard/.env.test.local

.github/workflows/e2e-custom-base-port-api-tests.yaml

@@ -16,11 +16,11 @@ jobs:
     runs-on: ubicloud-standard-8
     env:
       NODE_ENV: test
-      STACK_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
-      STACK_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:6728/stackframe"
+      HEXCLAVE_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
+      HEXCLAVE_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:6728/stackframe"
       NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX: "67"
-      STACK_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
-      STACK_EXTERNAL_DB_SYNC_DIRECT: "false"
+      HEXCLAVE_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
+      HEXCLAVE_EXTERNAL_DB_SYNC_DIRECT: "false"
 
     strategy:
       matrix:

.github/workflows/e2e-fallback-tests.yaml

@@ -19,14 +19,14 @@ jobs:
     runs-on: ubicloud-standard-8
     env:
       NODE_ENV: test
-      STACK_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
-      STACK_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:8128/stackframe"
-      STACK_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
-      STACK_EXTERNAL_DB_SYNC_DIRECT: "false"
+      HEXCLAVE_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
+      HEXCLAVE_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:8128/stackframe"
+      HEXCLAVE_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
+      HEXCLAVE_EXTERNAL_DB_SYNC_DIRECT: "false"
       # SDK reads this as the primary URL, discovers hardcoded fallback to port 8110
-      NEXT_PUBLIC_STACK_API_URL: "http://localhost:8102"
+      NEXT_PUBLIC_HEXCLAVE_API_URL: "http://localhost:8102"
       # Tells js-helpers to omit explicit baseUrl so the SDK exercises fallback logic
-      STACK_TEST_SDK_FALLBACK: "true"
+      HEXCLAVE_TEST_SDK_FALLBACK: "true"
 
     strategy:
       matrix:

.github/workflows/qemu-emulator-build.yaml

@@ -26,12 +26,12 @@ env:
   EMULATOR_IMAGE_DIR: ${{ github.workspace }}/docker/local-emulator/qemu/images
   EMULATOR_RUN_DIR: ${{ github.workspace }}/docker/local-emulator/qemu/run
   # The stack-cli ignores EMULATOR_IMAGE_DIR/RUN_DIR and derives its own paths
-  # from STACK_EMULATOR_HOME. Point it at the same workspace so `emulator
+  # from HEXCLAVE_EMULATOR_HOME. Point it at the same workspace so `emulator
   # start` finds the freshly-built qcow2 from build-image.sh and cold-boots
   # it, instead of auto-pulling from a prior release. CI doesn't capture a
   # savevm (EMULATOR_CAPTURE_SAVEVM defaults to 0); users capture locally
   # on first `stack emulator pull`.
-  STACK_EMULATOR_HOME: ${{ github.workspace }}/docker/local-emulator/qemu
+  HEXCLAVE_EMULATOR_HOME: ${{ github.workspace }}/docker/local-emulator/qemu
 
 jobs:
   build:
@@ -265,11 +265,11 @@ jobs:
           name: qemu-emulator-${{ matrix.arch }}
           path: ${{ github.workspace }}/.stack-emulator-images/
 
-      - name: Place qcow2 into STACK_EMULATOR_HOME layout
+      - name: Place qcow2 into HEXCLAVE_EMULATOR_HOME layout
         run: |
-          mkdir -p "$STACK_EMULATOR_HOME/images"
-          cp "${{ github.workspace }}/.stack-emulator-images/stack-emulator-${{ matrix.arch }}.qcow2" "$STACK_EMULATOR_HOME/images/"
-          ls -lh "$STACK_EMULATOR_HOME/images/"
+          mkdir -p "$HEXCLAVE_EMULATOR_HOME/images"
+          cp "${{ github.workspace }}/.stack-emulator-images/stack-emulator-${{ matrix.arch }}.qcow2" "$HEXCLAVE_EMULATOR_HOME/images/"
+          ls -lh "$HEXCLAVE_EMULATOR_HOME/images/"
 
       # No savevm.zst artifact (users capture locally via `emulator pull`),
       # so `emulator start` cold-boots the qcow2. Budget accordingly.
@@ -300,7 +300,7 @@ jobs:
 
       - name: Print serial log on failure
         if: failure()
-        run: tail -100 "$STACK_EMULATOR_HOME/run/vm/serial.log" 2>/dev/null || true
+        run: tail -100 "$HEXCLAVE_EMULATOR_HOME/run/vm/serial.log" 2>/dev/null || true
 
   publish:
     name: Publish to GitHub Releases

.github/workflows/setup-tests-with-custom-base-port.yaml

@@ -20,8 +20,8 @@ jobs:
     runs-on: ubicloud-standard-16
     env:
       NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX: "69"
-      STACK_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
-      STACK_EXTERNAL_DB_SYNC_DIRECT: "false"
+      HEXCLAVE_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
+      HEXCLAVE_EXTERNAL_DB_SYNC_DIRECT: "false"
 
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

.github/workflows/setup-tests.yaml

@@ -19,8 +19,8 @@ jobs:
     if: ${{ (github.head_ref || github.ref_name) == 'dev' }}
     runs-on: ubicloud-standard-16
     env:
-      STACK_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
-      STACK_EXTERNAL_DB_SYNC_DIRECT: "false"
+      HEXCLAVE_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
+      HEXCLAVE_EXTERNAL_DB_SYNC_DIRECT: "false"
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 

packages/cli/src/lib/emulator-paths.ts

@@ -26,7 +26,7 @@ export function envPortFirstSet(names: [string, ...string[]], fallback: number):
 }
 
 export function emulatorHome(): string {
-  return process.env.STACK_EMULATOR_HOME ?? join(homedir(), ".hexclave", "emulator");
+  return process.env.HEXCLAVE_EMULATOR_HOME ?? process.env.STACK_EMULATOR_HOME ?? join(homedir(), ".hexclave", "emulator");
 }
 
 export function emulatorRunDir(): string {