Skip to content

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

TypeScript

fix(branch-profile): refuse missing profile metadata with its only safe next step

Alfredo Lopezca48e0869649
diff --git a/.cursor/rules/minikube-t0-t1-t2.mdc b/.cursor/rules/minikube-t0-t1-t2.mdc
index 33730e776..b4fc90c9e 100644
--- a/.cursor/rules/minikube-t0-t1-t2.mdc
+++ b/.cursor/rules/minikube-t0-t1-t2.mdc
@@ -118,9 +118,9 @@ runner. `run_if_changed` dirs: `packages/workflow-runtime-core`,
list. `npm ci` the named dir **and every remaining** package that lacks
`node_modules/.bin/vitest`, then re-enter `make minikube-t2` on the same
HEAD/profile. `PROFILE_METADATA_MISSING` surfaces as
-`PROFILE_OWNERSHIP_MISMATCH`: resolve via this worktree's
-`scripts/minikube-profiles/branch.mk`,
-never invent ports. Do not edit tracked files while `make minikube-t2`
+`PROFILE_OWNERSHIP_MISMATCH`: restore `profile.env` or stop and ask
+(`scripts/minikube-profiles/branch.mk` never regenerates metadata for an
+existing profile directory), never invent ports. Do not edit tracked files while `make minikube-t2`
is running: T0 fixtures fail with `fixture mutated the host checkout
working tree`, and T2 refuses a dirty tree (`DEVELOPMENT_SCOPE_REQUIRED`).
diff --git a/.cursor/skills/minikube-t0-t1-t2/reference.md b/.cursor/skills/minikube-t0-t1-t2/reference.md
index 69344352e..9dbf1e249 100644
--- a/.cursor/skills/minikube-t0-t1-t2/reference.md
+++ b/.cursor/skills/minikube-t0-t1-t2/reference.md
@@ -129,9 +129,11 @@ Forbidden: new profile, PVC reset, `docker desktop restart`, `docker run`
probes, treating Error 127 as GFS/`PROFILE_UNHEALTHY`.
`PROFILE_METADATA_MISSING` (unreadable `profile.env` / ports) is raised as
-`PROFILE_OWNERSHIP_MISMATCH`. Resolve or generate metadata via this
-worktree's `scripts/minikube-profiles/branch.mk` (`branch-profile-start`).
-Never invent ports or `ls`/`cat` `~/.cache/clerum/minikube-profiles/`.
+`PROFILE_OWNERSHIP_MISMATCH`. `branch-profile-start` only creates metadata
+when the profile directory does not exist; it never regenerates metadata for
+an existing directory, derived or adopted, and the helper refuses with
+`PROFILE_METADATA_MISSING`. Restore `profile.env` from a backup or stop and
+ask. Never invent ports or `ls`/`cat` `~/.cache/clerum/minikube-profiles/`.
## Stable failure codes
@@ -140,7 +142,7 @@ Never invent ports or `ls`/`cat` `~/.cache/clerum/minikube-profiles/`.
| `LOCAL_DEPENDENCY_MISSING` | Node/package-local dependencies, Python, Docker, kubectl, Minikube, or another required local tool is unavailable. T1 preflight (`packages=2`) only checks `control-api` and `gfs-controller` for host `vitest`+`pg`. | Repair the named local prerequisite (`npm ci` in that package). Then `npm ci` every remaining pre-gate package in the Host npm section before re-entering T2. The preflight never auto-installs and never covers `external-rest-api` / `rpc-proxy` / `mcp-host` / … |
| `minikube-pre-gate-sync` Error 127 / `sh: vitest: command not found` | Host `npm test` in a `run_if_changed` package after planner PASS and Ready deployments. **Not** a T2 stable code. | `npm ci` the named dir **and every remaining** pre-gate package, then `make minikube-t2` on the same HEAD/profile. Not GFS, not a new profile. |
| `UNSUPPORTED_T1_CONCURRENCY` | A caller attempted more than one T1 worker. | Remove the override or set `VITEST_MAX_WORKERS=1`; T1 role/fixture mutation is serial by contract. |
-| `PROFILE_OWNERSHIP_MISMATCH` | Profile metadata, context, worktree, or branch does not match this lane. Includes wrapped `PROFILE_METADATA_MISSING` (unreadable `profile.env` / ports). | Resolve through this worktree's `scripts/minikube-profiles/branch.mk` helper (`branch-profile-start` when metadata is missing). Never invent ports, adopt a foreign profile, or `ls`/`cat` `~/.cache/clerum/minikube-profiles/`. |
+| `PROFILE_OWNERSHIP_MISMATCH` | Profile metadata, context, worktree, or branch does not match this lane. Includes wrapped `PROFILE_METADATA_MISSING` (unreadable `profile.env` / ports). | Resolve through this worktree's `scripts/minikube-profiles/branch.mk` helper. When metadata is missing for an existing profile directory, restore `profile.env` or stop and ask: `branch-profile-start` creates metadata only for a directory that does not exist. Never invent ports, adopt a foreign profile, or `ls`/`cat` `~/.cache/clerum/minikube-profiles/`. |
| `PROFILE_LOCK_REQUIRED` | A mutating child did not inherit the exact parent lease. | Invoke the public Make target/orchestrator; do not fabricate or bypass its lock token. |
| `DOCKER_ENDPOINT_REQUIRED` / `DOCKER_ENDPOINT_UNSAFE` / `DOCKER_ENDPOINT_MISMATCH` | Docker did not resolve exactly one approved local endpoint, or isolation selected a different endpoint. | Select a local Docker Desktop/rootless context or set an explicit local `DOCKER_HOST`; do not weaken the endpoint check. |
| `DOCKER_CONFIG_REQUIRED` / `REGISTRY_AUTH_REQUIRED` | A Docker operation lacks its empty task-local config, or a private pull lacks an explicit readable auth config. | Use the canonical Make/orchestrator path; for a genuinely private source, pass only the intended config directory through `MINIKUBE_DOCKER_AUTH_CONFIG`. |
diff --git a/scripts/minikube-profiles/branch-profile.sh b/scripts/minikube-profiles/branch-profile.sh
index e17153e23..fc6b51fcc 100755
--- a/scripts/minikube-profiles/branch-profile.sh
+++ b/scripts/minikube-profiles/branch-profile.sh
@@ -268,6 +268,14 @@ resolve_profile() {
apply_resolution "${output}"
return 0
fi
+ # Missing metadata for an existing profile directory has one safe next step.
+ # branch-profile-start only creates metadata when the directory does not
+ # exist, so pointing at it here would send the operator into this refusal
+ # again, or, without the explicit selection, into a brand-new profile.
+ if [[ "${output}" == *PROFILE_METADATA_MISSING:* ]]; then
+ printf '%s\n' "${output}" >&2
+ die "PROFILE_METADATA_MISSING: profile metadata for ${EXPLICIT_PROFILE:-this branch} is missing or unreadable; restore profile.env from a backup or stop and ask. branch-profile-start only creates metadata when the profile directory does not exist and never regenerates it for an existing one"
+ fi
if [[ -n "${EXPLICIT_PROFILE}" || ${status} -ne 3 || "${output}" != *PROFILE_NOT_FOUND:* ]]; then
printf '%s\n' "${output}" >&2
die 'profile ownership resolution failed closed'
diff --git a/scripts/minikube/t2-common.sh b/scripts/minikube/t2-common.sh
index 5b3bb32db..79e049a08 100755
--- a/scripts/minikube/t2-common.sh
+++ b/scripts/minikube/t2-common.sh
@@ -290,7 +290,7 @@ t2_profile_scope() {
"$T2_PROJECT_DIR" "$T2_BRANCH" "$T2_PROFILE"; then
case "$PROFILE_OWNER_ERROR_CODE" in
PROFILE_METADATA_MISSING)
- T2_NEXT_COMMAND='resolve or generate profile.env with the branch profile helper, then retry' ;;
+ T2_NEXT_COMMAND='restore profile.env from a backup or stop and ask; the branch profile helper never regenerates metadata for an existing profile directory' ;;
PROFILE_PORTS_MISSING)
T2_NEXT_COMMAND='restore the persisted profile-owned ports.env; never regenerate adopted ports' ;;
PROFILE_PORTS_INVALID)
diff --git a/scripts/tests/test-branch-profile-lifecycle.sh b/scripts/tests/test-branch-profile-lifecycle.sh
index 5c4838af9..956bf4ea8 100755
--- a/scripts/tests/test-branch-profile-lifecycle.sh
+++ b/scripts/tests/test-branch-profile-lifecycle.sh
@@ -400,6 +400,35 @@ assert_log_lacks 'minikube' 'an owned profile outside clerum-* must not reach mi
assert_log_lacks 'kubectl' 'an owned profile outside clerum-* must not reach kubectl'
rm -rf "${cache_root:?}/my-aks-shared"
+# A profile directory without profile.env is PROFILE_METADATA_MISSING, for an
+# explicitly adopted profile and for the derived branch profile alike. Nothing
+# regenerates that metadata (branch-profile-start only creates it when the
+# directory does not exist), so the refusal must name the code and the only
+# safe next step, and must not reach minikube or kubectl.
+mv "${cache_root}/${adopted}/profile.env" "${tmp}/adopted-profile.env"
+reset_state
+bp adopted-metadata-missing start "MINIKUBE_PROFILE=${adopted}"
+assert_rc 1 'start of an adopted profile without profile.env'
+assert_output_has "PROFILE_METADATA_MISSING: profile metadata for ${adopted} is missing or unreadable" \
+ 'the refusal of an adopted profile without profile.env names the code'
+assert_output_has 'never regenerates it for an existing one' \
+ 'the refusal of an adopted profile without profile.env does not point at branch-profile-start'
+assert_log_lacks 'minikube' 'an adopted profile without profile.env must not reach minikube'
+assert_log_lacks 'kubectl' 'an adopted profile without profile.env must not reach kubectl'
+mv "${tmp}/adopted-profile.env" "${cache_root}/${adopted}/profile.env"
+
+mv "${profile_dir}/profile.env" "${tmp}/branch-profile.env"
+reset_state
+bp derived-metadata-missing start
+assert_rc 1 'start of the branch profile without profile.env'
+assert_output_has "PROFILE_METADATA_MISSING: profile metadata for this branch is missing or unreadable" \
+ 'the refusal of the branch profile without profile.env names the code'
+assert_output_has 'never regenerates it for an existing one' \
+ 'the refusal of the branch profile without profile.env does not point at branch-profile-start'
+assert_log_lacks 'minikube' 'a branch profile without profile.env must not reach minikube'
+assert_log_lacks 'kubectl' 'a branch profile without profile.env must not reach kubectl'
+mv "${tmp}/branch-profile.env" "${profile_dir}/profile.env"
+
# A profile the resolver derives on its own (no explicit selection) must still
# carry the hashed suffix. With the branch profile set aside, the adopted
# profile is the only persisted record for this worktree and branch.