Skip to content

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

TypeScript

fix(minikube): document orphaned lock recovery

Alfredo Lopez61bf98e3fe2f
diff --git a/docs/testing/minikube-t2-runbook.md b/docs/testing/minikube-t2-runbook.md
index bc5105b46..0d7211e35 100644
--- a/docs/testing/minikube-t2-runbook.md
+++ b/docs/testing/minikube-t2-runbook.md
@@ -67,6 +67,18 @@ The pre-gate marker must contain the current worktree identifier, exact `HEAD`,
cluster fingerprint, and image coordinate. A mismatch stops with a stable
error code instead of allowing a mixed-commit run.
+### Orphaned lock recovery
+
+If `PROFILE_BUSY` reports that the lock has no valid owner PID, first verify
+that no T2 process owns the profile. After that check, remove only the exact
+profile lock directory and retry the same command:
+
+```bash
+rm -rf -- "$T2_LOCK_ROOT/<profile>.lock"
+```
+
+Never remove a lock with a live owner, and never remove the whole lock root.
+
## Preconditions and secrets
The runner checks required namespaces, Services, Secret names, ConfigMap names,
diff --git a/scripts/minikube/t2-common.sh b/scripts/minikube/t2-common.sh
index 5c4b1bfc0..58fe01d9a 100755
--- a/scripts/minikube/t2-common.sh
+++ b/scripts/minikube/t2-common.sh
@@ -531,7 +531,7 @@ t2_lock_acquire() {
local existing_pid
existing_pid="$(sed -n 's/^PID=//p' "$T2_LOCK_DIR/owner.env" 2>/dev/null | head -1 || true)"
if [[ ! "$existing_pid" =~ ^[0-9]+$ ]]; then
- T2_NEXT_COMMAND='inspect the profile lock owner metadata and retry only after the lock is released'
+ T2_NEXT_COMMAND='verify no T2 process owns the lock, then follow the orphaned-lock recovery steps in docs/testing/minikube-t2-runbook.md'
t2_fail PROFILE_BUSY "profile $T2_PROFILE has a lock without a valid owner PID"
fi
if [ -n "$existing_pid" ] && kill -0 "$existing_pid" >/dev/null 2>&1; then
diff --git a/scripts/tests/test-minikube-t2-contract.sh b/scripts/tests/test-minikube-t2-contract.sh
index f6e1ae32d..ee2fe2662 100755
--- a/scripts/tests/test-minikube-t2-contract.sh
+++ b/scripts/tests/test-minikube-t2-contract.sh
@@ -116,6 +116,7 @@ if T2_LOCK_ROOT="$tmp/locks" MINIKUBE_PROFILE=empty-profile T2_CONTEXT=empty-pro
exit 1
fi
grep -Fq 'PROFILE_BUSY' "$tmp/empty.err"
+grep -Fq 'orphaned' "$tmp/empty.err"
redaction_file="$tmp/t1-redaction.log"
redaction_secret='super-secret'