Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(minikube): close review gaps in the bootstrap link follow-up

Jose Ramirez8cbfc68ee8ea
diff --git a/AGENTS.md b/AGENTS.md
index 0004a84f1..399a57170 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -86,14 +86,15 @@ profile metadata, logs, and evidence belong under the ignored
## Desktop Electron installation invariant
-Node 24 ships npm 11, which blocks dependency lifecycle scripts unless they
-are explicitly approved. The Desktop app's pinned Electron package is approved
-in `desktop-app/package.json` because its `postinstall` downloads the Electron
-runtime used by Desktop tests and the local T2 gate. Desktop validation must
-use Node 24 (the CI/runtime contract); Node 26 is not a supported validation
-runtime for this dependency. Do not install `desktop-app` with
-`--ignore-scripts`, and do not count a Desktop test/build result until these
-checks succeed from `desktop-app`:
+Electron's `postinstall` downloads the runtime used by Desktop tests and the
+local T2 gate. When that script does not run, `npm ci` still exits 0 and the
+missing runtime only surfaces later as a test failure that looks like a product
+bug. Nothing in `package.json` can force the script to run, so the invariant is
+enforced by verification rather than by configuration: `npm run verify:electron`
+resolves `require('electron')` and fails when the runtime is absent. Desktop
+validation must use Node 24, which is the CI and runtime contract. Do not
+install `desktop-app` with `--ignore-scripts`, and do not count a Desktop
+test/build result until these checks succeed from `desktop-app`:
```bash
node --version # must report v24.x
@@ -103,8 +104,8 @@ npm run verify:electron
If it fails with `Electron failed to install correctly`, the dependency install
is incomplete, not a product failure. Stop the gate, switch to Node 24, remove
only the generated `desktop-app/node_modules/electron` directory, rerun `npm
-ci` with lifecycle scripts enabled, and rerun the checks. Do not add broad
-script approvals, set `ELECTRON_SKIP_BINARY_DOWNLOAD`, point
+ci` with lifecycle scripts enabled, and rerun the checks. Do not set
+`ELECTRON_SKIP_BINARY_DOWNLOAD`, point
`ELECTRON_OVERRIDE_DIST_PATH` at an unverified binary, or report green evidence
from a missing runtime. A verified local cache may be used only when its
version and checksum are recorded in the run evidence.
diff --git a/CLAUDE.md b/CLAUDE.md
index 0214cfd47..aca92b458 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -31,14 +31,14 @@ DSNs, private URLs, or raw request/response bodies.
## Desktop Electron runtime
-Node 24 uses npm 11, whose install-script approval model can leave Electron
-without its downloaded runtime while `npm ci` still exits successfully. The
-pinned Electron package is explicitly approved in `desktop-app/package.json`.
-Desktop validation must use Node 24 (Node 26 is not a supported validation
-runtime), run `npm ci` without `--ignore-scripts`, and verify
-`npm run verify:electron` confirms that `require('electron')` resolves to an
-executable before any test/build result is counted. If the check reports `Electron failed to install correctly`, switch to
-Node 24, repair the generated dependency directory, and rerun the install;
-never bypass the postinstall with `ELECTRON_SKIP_BINARY_DOWNLOAD`, use an
+A skipped Electron `postinstall` leaves the runtime undownloaded while `npm ci`
+still exits successfully, so the failure surfaces later as a test error that
+looks like a product bug. No `package.json` field prevents this; the guard is
+`npm run verify:electron`, which fails when `require('electron')` does not
+resolve to an executable. Desktop validation must use Node 24, run `npm ci`
+without `--ignore-scripts`, and pass that check before any test/build result is
+counted. If the check reports `Electron failed to install correctly`, switch to
+Node 24, repair the generated dependency directory, and rerun the install.
+Never bypass the postinstall with `ELECTRON_SKIP_BINARY_DOWNLOAD`, use an
unverified override, or treat the resulting test failure as a product
regression.
diff --git a/desktop-app/package.json b/desktop-app/package.json
index 13435a381..b11d21ddf 100644
--- a/desktop-app/package.json
+++ b/desktop-app/package.json
@@ -86,8 +86,5 @@
"@tootallnate/once": "^3.0.1",
"tmp": "^0.2.4",
"tar": "7.5.19"
- },
- "allowScripts": {
}
}
diff --git a/desktop-app/scripts/verify-electron-runtime.mjs b/desktop-app/scripts/verify-electron-runtime.mjs
index 8e51fd565..861b9e187 100644
--- a/desktop-app/scripts/verify-electron-runtime.mjs
+++ b/desktop-app/scripts/verify-electron-runtime.mjs
@@ -1,6 +1,29 @@
-import electronPath from 'electron'
import fs from 'node:fs'
+// Desktop validation is the one place the Node major is contractual: the
+// Electron postinstall and the prebuilt runtime are matched to Node 24, and CI
+// pins node-version 24. The quickstart prereq check only enforces a >= 24
+// floor, so assert the exact major here instead of blocking the whole install.
+// This runs before Electron is imported: a static import hoists above the check
+// and would report ERR_MODULE_NOT_FOUND on a wrong runtime instead of saying so.
+const nodeMajor = Number.parseInt(process.versions.node.split('.')[0], 10)
+if (nodeMajor !== 24) {
+ throw new Error(
+ `Desktop validation requires Node 24.x; found v${process.versions.node}. ` +
+ 'Switch to Node 24 and rerun npm ci with lifecycle scripts enabled.'
+ )
+}
+
+let electronPath
+try {
+ electronPath = (await import('electron')).default
+} catch (cause) {
+ throw new Error(
+ 'Electron is not installed; run npm ci with lifecycle scripts enabled (never --ignore-scripts)',
+ { cause }
+ )
+}
+
const runtimePath = typeof electronPath === 'string' ? electronPath : ''
if (!runtimePath) {
throw new Error('Electron runtime path is unavailable; run npm ci with lifecycle scripts enabled')
diff --git a/docs/get-started/minikube.md b/docs/get-started/minikube.md
index 2e90b86db..01d14e82c 100644
--- a/docs/get-started/minikube.md
+++ b/docs/get-started/minikube.md
@@ -10,7 +10,7 @@ single LLM key you set in `.env`.
## Prerequisites
Docker Desktop with **≥10 GB RAM / 6 CPUs** · `minikube` v1.30+ · `kubectl` ·
-`python3` · Node.js 24.x · `git` · `make` · `ruby` (renders the control-api DB
+`python3` · Node.js 24+ · `git` · `make` · `ruby` (renders the control-api DB
migration overlay; ships with macOS, `apt-get install ruby` on Debian/Ubuntu).
Run `make prereqs` (alias `make doctor`) to check every one of these at once —
diff --git a/scripts/check-prereqs.sh b/scripts/check-prereqs.sh
index adff1b4fd..bfddc8c2b 100755
--- a/scripts/check-prereqs.sh
+++ b/scripts/check-prereqs.sh
@@ -91,19 +91,27 @@ else
MISSING=$((MISSING + 1))
fi
-# ── Node.js 24.x (Desktop/Electron validation contract) ───────────────
+# ── Node.js (>= 24; Desktop/Electron validation wants 24.x) ───────────
+# The platform itself runs in containers, so the quickstart only needs a
+# floor here. Pinning the whole install to 24.x would lock out newer runtimes
+# for a Desktop-only concern. Desktop validation is where 24.x is contractual:
+# CI pins node-version 24 and desktop-app/scripts/verify-electron-runtime.mjs
+# enforces it before any Desktop test/build result counts.
if command -v node >/dev/null 2>&1; then
NODE_VER="$(node --version | sed 's/^v//')"
NODE_MAJOR="${NODE_VER%%.*}"
- if [ "$NODE_MAJOR" = "24" ]; then
+ if version_ge "$NODE_VER" "24.0.0"; then
ok "node v${NODE_VER}"
+ if [ "$NODE_MAJOR" != "24" ]; then
+ warn "node v${NODE_VER} runs the quickstart, but Desktop/Electron validation requires 24.x"
+ fi
else
- err "node v${NODE_VER} (need 24.x for Desktop/Electron validation)"
+ err "node v${NODE_VER} (need >= 24)"
hint "brew install node@24" "curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt-get install -y nodejs"
MISSING=$((MISSING + 1))
fi
else
- err "node not found (need 24.x for Desktop/Electron validation)"
+ err "node not found (need >= 24)"
hint "brew install node@24" "curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt-get install -y nodejs"
MISSING=$((MISSING + 1))
fi
diff --git a/scripts/e2e/seed-e2e-data.sh b/scripts/e2e/seed-e2e-data.sh
index 7c58eb124..1afa9fee8 100755
--- a/scripts/e2e/seed-e2e-data.sh
+++ b/scripts/e2e/seed-e2e-data.sh
@@ -538,7 +538,13 @@ verify_minimal_operator_bootstrap() {
link_admin_id="$(echo "$ADMIN_GET_BODY" | jq -r --arg username "$ADMIN_USERNAME" --arg email "$ADMIN_EMAIL" \
'.admins[] | select(.username == $username and ((.email // "") | ascii_downcase) == $email) | .gfsOperatorLink.controlAdminId // empty')"
if ! clerum_initial_setup_link_matches "$status" "$source" "$desktop_user_id" "$link_admin_id" "$admin_id"; then
- die "Minimal bootstrap is incomplete: expected one active initial_setup Desktop link for '$ADMIN_EMAIL' (status=$status source=$source desktopUserId=${desktop_user_id:-missing} controlAdminId=${link_admin_id:-missing}); refusing ordinary-user fallback"
+ # Recovery is only possible by rebuilding the control DB. control-api
+ # stamps last_login_at on every successful admin login and
+ # setupInitialAdminCredentials only matches a bootstrap row whose
+ # last_login_at is still NULL, so once a cluster has logged in without
+ # consuming setup the initial_setup link can never be created on that
+ # database. Say so instead of leaving the operator with a bare refusal.
+ die "Minimal bootstrap is incomplete: expected one active initial_setup Desktop link for '$ADMIN_EMAIL' (status=$status source=$source desktopUserId=${desktop_user_id:-missing} controlAdminId=${link_admin_id:-missing}); refusing ordinary-user fallback. This cluster consumed or bypassed /admin/auth/setup without creating the link, and it cannot be created on the existing database. Rebuild the control DB to recover: re-run 'make minikube-setup' without REUSE_DB/--keep-db (the default rebuilds the DB), passing CONTROL_DB_RESET_PVC_UID when the setup script asks for it."
fi
ok "Initial admin '$ADMIN_USERNAME' has active initial_setup Desktop operator link (desktopUserId=${desktop_user_id:0:8}…)"
}
diff --git a/scripts/minikube/full-setup.sh b/scripts/minikube/full-setup.sh
index 858526e4a..1baa901d1 100755
--- a/scripts/minikube/full-setup.sh
+++ b/scripts/minikube/full-setup.sh
@@ -1470,9 +1470,13 @@ else
# from it on every fresh DB. If this step fails under the default
# (minimal) profile, that publicly-known credential is still live — a
# green summary would ship an install that is both unusable and insecure.
- # Abort instead; setup is idempotent, so re-running after the underlying
- # issue is fixed recovers cleanly.
- err "Test user seed failed under SEED_PROFILE=minimal — aborting. The bootstrap admin password may still be the publicly-known default (see generate-keys.sh) until this step succeeds. Fix the error above and re-run setup."
+ # Abort instead. Setup is idempotent, so re-running after the underlying
+ # issue is fixed recovers cleanly for every failure except a missing
+ # initial_setup link on a reused database: control-api stamps
+ # last_login_at on each admin login and setup only matches a bootstrap
+ # row whose last_login_at is NULL, so that one needs a DB rebuild. The
+ # seeder prints the exact recovery command for that case.
+ err "Test user seed failed under SEED_PROFILE=minimal, aborting. The bootstrap admin password may still be the publicly-known default (see generate-keys.sh) until this step succeeds. Fix the error above and re-run setup. If the seeder reported a missing initial_setup Desktop link, re-run without REUSE_DB/--keep-db so the control DB is rebuilt."
exit 1
else
warn "Test user seed encountered errors — check output above"
diff --git a/scripts/tests/test-minikube-full-setup.sh b/scripts/tests/test-minikube-full-setup.sh
index 5b5d83865..50af50d78 100755
--- a/scripts/tests/test-minikube-full-setup.sh
+++ b/scripts/tests/test-minikube-full-setup.sh
@@ -520,17 +520,47 @@ assert_bootstrap_seed_deferral_rejects_non_local_or_e2e_modes() {
assert_minimal_seed_is_setup_first_and_link_fail_closed() {
local seed="$REPO_ROOT/scripts/e2e/seed-e2e-data.sh"
- local minimal_block
- minimal_block="$(sed -n '/^if \[ "\$SEED_PROFILE" = "minimal" \]; then$/,/^else$/p' "$seed")"
- if printf '%s\n' "$minimal_block" | grep -Fq 'perform_initial_setup' && \
- printf '%s\n' "$minimal_block" | grep -Fq 'login_admin_only' && \
- printf '%s\n' "$minimal_block" | grep -Fq 'verify_minimal_operator_bootstrap' && \
- grep -Fq 'clerum_initial_setup_link_matches' "$seed" && \
- grep -Fq 'refusing ordinary-user fallback' "$seed"; then
- pass "minimal seed consumes setup before login and fails closed without an active initial_setup link"
- else
- fail "minimal seed does not prove setup-first ordering and fail-closed link verification"
+ local dispatch verify_body setup_line login_line verify_line
+
+ # Bound the dispatch and the verifier exactly. A range that ends at the first
+ # bare `else` runs past every nested block and swallows most of the file, so
+ # presence greps alone still pass when the ordering is reversed or the
+ # fail-closed abort is downgraded to a warning.
+ dispatch="$(awk '/^# ─── Step 1: Bootstrap before login/,/^fi$/' "$seed")"
+ verify_body="$(awk '/^verify_minimal_operator_bootstrap\(\) \{$/,/^\}$/' "$seed")"
+
+ setup_line="$(printf '%s\n' "$dispatch" | grep -n '^ perform_initial_setup$' | head -1 | cut -d: -f1)"
+ login_line="$(printf '%s\n' "$dispatch" | grep -n 'login_admin_only' | head -1 | cut -d: -f1)"
+ verify_line="$(printf '%s\n' "$dispatch" | grep -n '^ verify_minimal_operator_bootstrap$' | head -1 | cut -d: -f1)"
+
+ if [ -z "$setup_line" ] || [ -z "$login_line" ] || [ -z "$verify_line" ]; then
+ fail "minimal seed dispatch must call setup, the login fallback and link verification"
+ return
+ fi
+ # control-api marks last_login_at on every successful admin login, and
+ # setupInitialAdminCredentials only matches a bootstrap row whose
+ # last_login_at is still NULL. Logging in first destroys setup eligibility
+ # permanently, so this ordering is the whole point of the minimal path.
+ if [ "$setup_line" -ge "$login_line" ]; then
+ fail "minimal seed logs in at line $login_line before consuming setup at line $setup_line; login sets last_login_at and permanently disqualifies /admin/auth/setup"
+ return
+ fi
+ if [ "$verify_line" -le "$login_line" ]; then
+ fail "minimal seed must verify the initial_setup link after the login fallback, not before it"
+ return
+ fi
+ if ! printf '%s\n' "$verify_body" | grep -Fq 'if ! clerum_initial_setup_link_matches '; then
+ fail "minimal link verification does not gate on the shared initial_setup link contract"
+ return
+ fi
+ # The missing-link branch must abort. Downgrading it to a log leaves the
+ # install running as an ordinary unlinked member, which is the exact
+ # regression this assertion exists to catch.
+ if ! printf '%s\n' "$verify_body" | grep -Eq '^ *die "Minimal bootstrap is incomplete'; then
+ fail "minimal link verification does not abort when the initial_setup link is absent"
+ return
fi
+ pass "minimal seed consumes setup before login and aborts without an active initial_setup link"
}
assert_minimal_bootstrap_contract_runs_on_system_bash() {