create-egregore 0.21.0-runtime-mvp.2 → 0.21.0-runtime-mvp.4

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.21.0-runtime-mvp.2
+// egregore-launcher-version: 0.21.0-runtime-mvp.4
 //
 // egregore — launch and browse Egregore instances from your terminal.
 // Installed by create-egregore. Reads ~/.egregore/instances.json.
@@ -35,7 +35,7 @@ const crypto = require("node:crypto");
 const { spawnSync, spawn } = require("node:child_process");
 const readline = require("node:readline");
 
-const VERSION = "0.21.0-runtime-mvp.2";
+const VERSION = "0.21.0-runtime-mvp.4";
 const REGISTRY = path.join(os.homedir(), ".egregore", "instances.json");
 const DEFAULT_FILE = path.join(os.homedir(), ".egregore", "default");
 const UPDATE_CACHE_FILE = path.join(os.homedir(), ".egregore", "update-check.json");
@@ -2505,6 +2505,40 @@ function upgradeStatusAsync(inst, cb) {
   } catch { cb(null); }
 }
 
+// Local retrieval health for the settings surface. Package-update state,
+// Runtime activation state, and retrieval health are three different truths;
+// the settings row must not let one stand in for another. Repair-needed means
+// readiness names a concrete repair command (e.g. the embedding model is
+// missing while stored vectors are intact).
+function retrievalHealthAsync(inst, cb) {
+  const script = path.join(inst.path, "bin", "search.sh");
+  if (!fs.existsSync(script)) return cb(null);
+  let buf = "";
+  try {
+    const child = spawn("bash", [script, "readiness", "--json"], {
+      cwd: inst.path,
+      stdio: ["ignore", "pipe", "ignore"],
+      env: { ...process.env },
+    });
+    child.stdout.on("data", (d) => { buf += d; });
+    child.on("close", () => {
+      try {
+        const report = JSON.parse(buf);
+        const items = Array.isArray(report.items) ? report.items : [];
+        const byKey = Object.fromEntries(items.map((item) => [item.key, item]));
+        const repair = items.some((item) => /repair: bin\/search\.sh/.test(item.detail || ""));
+        cb({
+          repair,
+          searchStage: byKey.search?.stage || "unknown",
+          embeddingsDetail: byKey.embeddings?.detail || "",
+          semanticDetail: byKey.semantic?.detail || "",
+        });
+      } catch { cb(null); }
+    });
+    child.on("error", () => cb(null));
+  } catch { cb(null); }
+}
+
 // Exact candidate resolution: the runtime-mvp dist-tag only, validated
 // against the prerelease scheme — never latest, never a retired scheme.
 // EGREGORE_RUNTIME_MVP_CANDIDATE is the offline/test seam.
@@ -2560,7 +2594,7 @@ function upgradeElapsed(st) {
 // Plain-language body shared by the non-interactive `settings <slug> runtime`
 // output and the interactive panel. Returns undecorated strings; callers add
 // color. Never JSON, never internal paths beyond the instance's own root.
-function formatUpgradeLines(inst, st, { candidate = "" } = {}) {
+function formatUpgradeLines(inst, st, { candidate = "", retrieval = null } = {}) {
   const lines = [];
   const d = st || { status: "none" };
   lines.push(`Selected Egregore: ${inst.name || inst.slug} (${inst.slug || "?"})`);
@@ -2581,6 +2615,17 @@ function formatUpgradeLines(inst, st, { candidate = "" } = {}) {
   } else if (d.status !== "none") {
     lines.push("Previous Runtime remains active until activation.");
   }
+  if (retrieval) {
+    if (retrieval.repair) {
+      lines.push("Local retrieval: repair needed");
+      if (retrieval.embeddingsDetail) lines.push(`  ✗ ${retrieval.embeddingsDetail}`);
+      lines.push("  → run: bin/search.sh reindex --embed");
+    } else if (retrieval.searchStage && retrieval.searchStage !== "ready") {
+      lines.push(`Local retrieval: ${retrieval.searchStage}`);
+    } else if (retrieval.searchStage === "ready") {
+      lines.push("Local retrieval: ready");
+    }
+  }
   if (Array.isArray(d.stages) && d.status !== "none" && d.status !== "active") {
     lines.push("");
     for (const stage of d.stages) {
@@ -2984,7 +3029,7 @@ const SETTINGS_DOMAIN_NOUN = { repo: "repo name", admin: "github handle", people
 // Runtime-update panel: renders the durable upgrade state from the Python
 // engine. Same geometry as the settings panel; plain-language body from
 // formatUpgradeLines with launcher glyph decoration only.
-function renderUpgradePanel({ inst, data, candidate, mode, notice, width }) {
+function renderUpgradePanel({ inst, data, candidate, retrieval, mode, notice, width }) {
   const outerWidth = Math.min(Math.max(50, width - 2), 126);
   const innerWidth = Math.max(48, outerWidth - 2);
   const margin = " ".repeat(Math.max(0, Math.floor((width - outerWidth) / 2)));
@@ -2997,7 +3042,7 @@ function renderUpgradePanel({ inst, data, candidate, mode, notice, width }) {
     ? ["Checking this egregore's Runtime state…"]
     : data === null
       ? ["Runtime update state is unavailable for this egregore."]
-      : formatUpgradeLines(inst, data, { candidate });
+      : formatUpgradeLines(inst, data, { candidate, retrieval });
   for (const raw of body) {
     let line = raw;
     if (/^  ✓ /.test(raw)) line = `  ${GREEN}✓${RESET} ${raw.slice(4)}`;
@@ -3041,7 +3086,7 @@ function renderUpgradePanel({ inst, data, candidate, mode, notice, width }) {
   return lines;
 }
 
-function renderSettingsPanel({ inst, data, cursor, view, domain, items, listCursor, mode, input, notice, width, upgrade }) {
+function renderSettingsPanel({ inst, data, cursor, view, domain, items, listCursor, mode, input, notice, width, upgrade, retrieval }) {
   const title = inst.slug || inst.name || path.basename(inst.path);
   const outerWidth = Math.min(Math.max(50, width - 2), 126);
   const innerWidth = Math.max(48, outerWidth - 2);
@@ -3196,7 +3241,12 @@ function renderSettingsPanel({ inst, data, cursor, view, domain, items, listCurs
             ? `${YELLOW}${upgradeSummary(upgrade)}${RESET}`
             : `${DIM}${upgradeSummary(upgrade)}${RESET}`;
     const rows = [
-      { name: "Runtime update", value: upgradeValue },
+      {
+        name: "Runtime update",
+        value: retrieval && retrieval.repair
+          ? `${upgradeValue} ${YELLOW}· retrieval repair needed${RESET}`
+          : upgradeValue,
+      },
       { name: "Privacy & access", value: `${DIM}identity · boundary · consent${RESET}` },
       { name: "Telemetry", value: `${DIM}personal · opt-out${RESET}` },
       { name: "Hosted Artifacts", value: (d.hosting !== false) ? `${GREEN}ON${RESET}` : `${YELLOW}OFF${RESET}` },
@@ -3350,6 +3400,7 @@ async function browser(args = {}) {
         inst: state.upgradeInst,
         data: state.upgradeData,
         candidate: state.upgradeCandidate,
+        retrieval: state.upgradeRetrieval,
         mode: state.upgradeMode,
         notice: state.upgradeNotice,
         width: w,
@@ -3375,6 +3426,7 @@ async function browser(args = {}) {
         notice: state.settingsNotice,
         width: w,
         upgrade: state.settingsUpgrade,
+        retrieval: state.settingsRetrieval,
       });
       for (const line of settingsLines) out.push(line + ANSI.clearLine + "\n");
       const remainingRows = Math.max(0, h - settingsLines.length - 1);
@@ -3903,8 +3955,13 @@ async function browser(args = {}) {
           if (S.settingsCursor === 0) {
             state.upgradeInst = S.settingsInst;
             state.upgradeData = S.settingsUpgrade;
+            state.upgradeRetrieval = S.settingsRetrieval;
             state.upgradeMode = "view";
             state.upgradeNotice = "";
+            retrievalHealthAsync(S.settingsInst, (health) => {
+              state.upgradeRetrieval = health;
+              if (state.upgradeInst) render();
+            });
             refreshUpgrade();
             if (!state.upgradeCandidate) {
               fetchRuntimeMvpCandidate().then((v) => {
@@ -4190,10 +4247,15 @@ async function browser(args = {}) {
         state.settingsCursor = 0;
         state.settingsView = "menu";
         state.settingsUpgrade = undefined;
+        state.settingsRetrieval = undefined;
         upgradeStatusAsync(pick, (st) => {
           state.settingsUpgrade = st;
           if (state.settingsInst === pick && !state.upgradeInst) render();
         });
+        retrievalHealthAsync(pick, (health) => {
+          state.settingsRetrieval = health;
+          if (state.settingsInst === pick && !state.upgradeInst) render();
+        });
         state.settingsNotice = "";
         render();
         return;

package/lib/setup.js

@@ -1327,17 +1327,46 @@ function currentTemplatePath() {
 //   # egregore-launcher-version: X.Y.Z   (bash)
 //   // egregore-launcher-version: X.Y.Z  (node)
 function launcherVersion(contents) {
-  const m = contents.match(/egregore-launcher-version:\s*(\d+\.\d+\.\d+)/);
+  // Capture the full stamp including any prerelease suffix. A prerelease-blind
+  // regex made 0.21.0-runtime-mvp.1 and .2 both read as "0.21.0", so the
+  // refresh treated the newer template as a local edit and refused to upgrade.
+  const m = contents.match(/egregore-launcher-version:\s*(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/);
   return m ? m[1] : null;
 }
 
-// Return 1 if a > b, -1 if a < b, 0 if equal. Both are semver strings "x.y.z".
+// Return 1 if a > b, -1 if a < b, 0 if equal. Semver with prerelease rules:
+// a release outranks any prerelease of the same core; prerelease identifiers
+// compare dot-by-dot, numerically when both numeric.
 function compareVersions(a, b) {
-  const pa = a.split(".").map(Number);
-  const pb = b.split(".").map(Number);
+  const splitOnce = (v) => {
+    const i = v.indexOf("-");
+    return i === -1 ? [v, ""] : [v.slice(0, i), v.slice(i + 1)];
+  };
+  const [coreA, preA] = splitOnce(a);
+  const [coreB, preB] = splitOnce(b);
+  const pa = coreA.split(".").map(Number);
+  const pb = coreB.split(".").map(Number);
   for (let i = 0; i < 3; i++) {
     if (pa[i] !== pb[i]) return pa[i] > pb[i] ? 1 : -1;
   }
+  if (!preA && !preB) return 0;
+  if (!preA) return 1;
+  if (!preB) return -1;
+  const ia = preA.split(".");
+  const ib = preB.split(".");
+  for (let i = 0; i < Math.max(ia.length, ib.length); i++) {
+    if (ia[i] === undefined) return -1;
+    if (ib[i] === undefined) return 1;
+    const na = /^\d+$/.test(ia[i]) ? Number(ia[i]) : NaN;
+    const nb = /^\d+$/.test(ib[i]) ? Number(ib[i]) : NaN;
+    if (!Number.isNaN(na) && !Number.isNaN(nb)) {
+      if (na !== nb) return na > nb ? 1 : -1;
+    } else if (Number.isNaN(na) !== Number.isNaN(nb)) {
+      return Number.isNaN(na) ? 1 : -1;
+    } else if (ia[i] !== ib[i]) {
+      return ia[i] > ib[i] ? 1 : -1;
+    }
+  }
   return 0;
 }
 
@@ -1628,6 +1657,8 @@ async function installShellAlias(egregoreDir, ui) {
 
 module.exports = {
   install,
+  launcherVersion,
+  compareVersions,
   ghApi,
   acceptPendingInvitations,
   registerInstance,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-egregore",
-  "version": "0.21.0-runtime-mvp.2",
+  "version": "0.21.0-runtime-mvp.4",
   "description": "Set up Egregore for your team in one command — installs the egregore launcher and your choice of Claude Code, Codex, or Pi.",
   "license": "MIT",
   "bin": {

package/runtime/claude/egregore_runtime/adapters/qmd.py

@@ -353,8 +353,13 @@ class QmdLocalRetriever:
             and counts["documents"] > 0
             and self._index_state_usable()
         )
+        # Semantic queries embed the query text at request time, so the model
+        # must be present even when every stored vector is current. Stored
+        # vectors without the model is a repair state, never "ready".
+        model_available = self._embedding_model_available()
         semantic_ready = bool(
             bm25_ready
+            and model_available
             and counts["vectors"] > 0
             and counts["pending"] == 0
             and self._semantic_state_current()
@@ -362,9 +367,15 @@ class QmdLocalRetriever:
         )
         embedding_state = self._embedding_state(status, semantic_ready=semantic_ready)
         if embedding_state == "missing_model":
-            warnings.append(
-                f"{EMBEDDING_MODEL} is not installed; hybrid requests degrade to lexical retrieval while embedding warms"
-            )
+            if counts["vectors"] > 0:
+                warnings.append(
+                    f"{EMBEDDING_MODEL} is missing while stored vectors are intact; "
+                    "semantic queries are unavailable until repair — run: bin/search.sh reindex --embed"
+                )
+            else:
+                warnings.append(
+                    f"{EMBEDDING_MODEL} is not installed; hybrid requests degrade to lexical retrieval while embedding warms"
+                )
 
         runtime = self._owned_runtime()
         if not canonical_ready or not qmd_available or not status_ok:
@@ -1568,10 +1579,13 @@ class QmdLocalRetriever:
     def _embedding_state(self, status: str, *, semantic_ready: bool = False) -> str:
         if self._live_lock(self._embed_lock_path()):
             return "running"
-        if semantic_ready:
-            return "ready"
+        # Model presence outranks stored-vector completeness: query-time
+        # embedding needs the model, so a complete build with a missing model
+        # is a repair state, not "ready".
         if not self._embedding_model_available():
             return "missing_model"
+        if semantic_ready:
+            return "ready"
         counts = self._status_counts(status)
         if counts["pending"] > 0 or counts["documents"] > 0:
             return "pending"

package/runtime/claude/egregore_runtime/readiness.py

@@ -236,6 +236,16 @@ def _embeddings_item(health: RetrieverHealth) -> ReadinessItem:
             key="embeddings", label=label, stage=STAGE_BUILDING, detail=detail
         )
     if state == "missing_model":
+        if health.semantic_source_revision:
+            return ReadinessItem(
+                key="embeddings",
+                label=label,
+                stage=STAGE_UNAVAILABLE,
+                detail=(
+                    "embedding model missing — stored vectors intact · "
+                    "repair: bin/search.sh reindex --embed"
+                ),
+            )
         return ReadinessItem(
             key="embeddings",
             label=label,
@@ -254,6 +264,16 @@ def _semantic_item(health: RetrieverHealth) -> ReadinessItem:
     label = "Semantic build"
     source = _short_revision(health.source_revision)
     build = _short_revision(health.semantic_source_revision)
+    if health.embedding_state == "missing_model":
+        return ReadinessItem(
+            key="semantic",
+            label=label,
+            stage=STAGE_UNAVAILABLE,
+            detail=(
+                "embedding model missing — semantic queries unavailable · "
+                "repair: bin/search.sh reindex --embed"
+            ),
+        )
     if health.semantic_ready:
         return ReadinessItem(
             key="semantic",
@@ -282,6 +302,16 @@ def _search_item(health: RetrieverHealth) -> ReadinessItem:
         return ReadinessItem(
             key="search", label=label, stage=STAGE_READY, detail="hybrid current"
         )
+    if health.bm25_ready and health.embedding_state == "missing_model":
+        return ReadinessItem(
+            key="search",
+            label=label,
+            stage=STAGE_READY,
+            detail=(
+                "lexical only — embedding model missing · "
+                "repair: bin/search.sh reindex --embed"
+            ),
+        )
     if health.bm25_ready and health.semantic_source_revision:
         return ReadinessItem(
             key="search",

package/runtime/codex/egregore_runtime/adapters/qmd.py

@@ -353,8 +353,13 @@ class QmdLocalRetriever:
             and counts["documents"] > 0
             and self._index_state_usable()
         )
+        # Semantic queries embed the query text at request time, so the model
+        # must be present even when every stored vector is current. Stored
+        # vectors without the model is a repair state, never "ready".
+        model_available = self._embedding_model_available()
         semantic_ready = bool(
             bm25_ready
+            and model_available
             and counts["vectors"] > 0
             and counts["pending"] == 0
             and self._semantic_state_current()
@@ -362,9 +367,15 @@ class QmdLocalRetriever:
         )
         embedding_state = self._embedding_state(status, semantic_ready=semantic_ready)
         if embedding_state == "missing_model":
-            warnings.append(
-                f"{EMBEDDING_MODEL} is not installed; hybrid requests degrade to lexical retrieval while embedding warms"
-            )
+            if counts["vectors"] > 0:
+                warnings.append(
+                    f"{EMBEDDING_MODEL} is missing while stored vectors are intact; "
+                    "semantic queries are unavailable until repair — run: bin/search.sh reindex --embed"
+                )
+            else:
+                warnings.append(
+                    f"{EMBEDDING_MODEL} is not installed; hybrid requests degrade to lexical retrieval while embedding warms"
+                )
 
         runtime = self._owned_runtime()
         if not canonical_ready or not qmd_available or not status_ok:
@@ -1568,10 +1579,13 @@ class QmdLocalRetriever:
     def _embedding_state(self, status: str, *, semantic_ready: bool = False) -> str:
         if self._live_lock(self._embed_lock_path()):
             return "running"
-        if semantic_ready:
-            return "ready"
+        # Model presence outranks stored-vector completeness: query-time
+        # embedding needs the model, so a complete build with a missing model
+        # is a repair state, not "ready".
         if not self._embedding_model_available():
             return "missing_model"
+        if semantic_ready:
+            return "ready"
         counts = self._status_counts(status)
         if counts["pending"] > 0 or counts["documents"] > 0:
             return "pending"

package/runtime/codex/egregore_runtime/readiness.py

@@ -236,6 +236,16 @@ def _embeddings_item(health: RetrieverHealth) -> ReadinessItem:
             key="embeddings", label=label, stage=STAGE_BUILDING, detail=detail
         )
     if state == "missing_model":
+        if health.semantic_source_revision:
+            return ReadinessItem(
+                key="embeddings",
+                label=label,
+                stage=STAGE_UNAVAILABLE,
+                detail=(
+                    "embedding model missing — stored vectors intact · "
+                    "repair: bin/search.sh reindex --embed"
+                ),
+            )
         return ReadinessItem(
             key="embeddings",
             label=label,
@@ -254,6 +264,16 @@ def _semantic_item(health: RetrieverHealth) -> ReadinessItem:
     label = "Semantic build"
     source = _short_revision(health.source_revision)
     build = _short_revision(health.semantic_source_revision)
+    if health.embedding_state == "missing_model":
+        return ReadinessItem(
+            key="semantic",
+            label=label,
+            stage=STAGE_UNAVAILABLE,
+            detail=(
+                "embedding model missing — semantic queries unavailable · "
+                "repair: bin/search.sh reindex --embed"
+            ),
+        )
     if health.semantic_ready:
         return ReadinessItem(
             key="semantic",
@@ -282,6 +302,16 @@ def _search_item(health: RetrieverHealth) -> ReadinessItem:
         return ReadinessItem(
             key="search", label=label, stage=STAGE_READY, detail="hybrid current"
         )
+    if health.bm25_ready and health.embedding_state == "missing_model":
+        return ReadinessItem(
+            key="search",
+            label=label,
+            stage=STAGE_READY,
+            detail=(
+                "lexical only — embedding model missing · "
+                "repair: bin/search.sh reindex --embed"
+            ),
+        )
     if health.bm25_ready and health.semantic_source_revision:
         return ReadinessItem(
             key="search",

package/runtime/pi/egregore_runtime/adapters/qmd.py

@@ -353,8 +353,13 @@ class QmdLocalRetriever:
             and counts["documents"] > 0
             and self._index_state_usable()
         )
+        # Semantic queries embed the query text at request time, so the model
+        # must be present even when every stored vector is current. Stored
+        # vectors without the model is a repair state, never "ready".
+        model_available = self._embedding_model_available()
         semantic_ready = bool(
             bm25_ready
+            and model_available
             and counts["vectors"] > 0
             and counts["pending"] == 0
             and self._semantic_state_current()
@@ -362,9 +367,15 @@ class QmdLocalRetriever:
         )
         embedding_state = self._embedding_state(status, semantic_ready=semantic_ready)
         if embedding_state == "missing_model":
-            warnings.append(
-                f"{EMBEDDING_MODEL} is not installed; hybrid requests degrade to lexical retrieval while embedding warms"
-            )
+            if counts["vectors"] > 0:
+                warnings.append(
+                    f"{EMBEDDING_MODEL} is missing while stored vectors are intact; "
+                    "semantic queries are unavailable until repair — run: bin/search.sh reindex --embed"
+                )
+            else:
+                warnings.append(
+                    f"{EMBEDDING_MODEL} is not installed; hybrid requests degrade to lexical retrieval while embedding warms"
+                )
 
         runtime = self._owned_runtime()
         if not canonical_ready or not qmd_available or not status_ok:
@@ -1568,10 +1579,13 @@ class QmdLocalRetriever:
     def _embedding_state(self, status: str, *, semantic_ready: bool = False) -> str:
         if self._live_lock(self._embed_lock_path()):
             return "running"
-        if semantic_ready:
-            return "ready"
+        # Model presence outranks stored-vector completeness: query-time
+        # embedding needs the model, so a complete build with a missing model
+        # is a repair state, not "ready".
         if not self._embedding_model_available():
             return "missing_model"
+        if semantic_ready:
+            return "ready"
         counts = self._status_counts(status)
         if counts["pending"] > 0 or counts["documents"] > 0:
             return "pending"

package/runtime/pi/egregore_runtime/readiness.py

@@ -236,6 +236,16 @@ def _embeddings_item(health: RetrieverHealth) -> ReadinessItem:
             key="embeddings", label=label, stage=STAGE_BUILDING, detail=detail
         )
     if state == "missing_model":
+        if health.semantic_source_revision:
+            return ReadinessItem(
+                key="embeddings",
+                label=label,
+                stage=STAGE_UNAVAILABLE,
+                detail=(
+                    "embedding model missing — stored vectors intact · "
+                    "repair: bin/search.sh reindex --embed"
+                ),
+            )
         return ReadinessItem(
             key="embeddings",
             label=label,
@@ -254,6 +264,16 @@ def _semantic_item(health: RetrieverHealth) -> ReadinessItem:
     label = "Semantic build"
     source = _short_revision(health.source_revision)
     build = _short_revision(health.semantic_source_revision)
+    if health.embedding_state == "missing_model":
+        return ReadinessItem(
+            key="semantic",
+            label=label,
+            stage=STAGE_UNAVAILABLE,
+            detail=(
+                "embedding model missing — semantic queries unavailable · "
+                "repair: bin/search.sh reindex --embed"
+            ),
+        )
     if health.semantic_ready:
         return ReadinessItem(
             key="semantic",
@@ -282,6 +302,16 @@ def _search_item(health: RetrieverHealth) -> ReadinessItem:
         return ReadinessItem(
             key="search", label=label, stage=STAGE_READY, detail="hybrid current"
         )
+    if health.bm25_ready and health.embedding_state == "missing_model":
+        return ReadinessItem(
+            key="search",
+            label=label,
+            stage=STAGE_READY,
+            detail=(
+                "lexical only — embedding model missing · "
+                "repair: bin/search.sh reindex --embed"
+            ),
+        )
     if health.bm25_ready and health.semantic_source_revision:
         return ReadinessItem(
             key="search",

package/runtime/prime/egregore_runtime/adapters/qmd.py

@@ -353,8 +353,13 @@ class QmdLocalRetriever:
             and counts["documents"] > 0
             and self._index_state_usable()
         )
+        # Semantic queries embed the query text at request time, so the model
+        # must be present even when every stored vector is current. Stored
+        # vectors without the model is a repair state, never "ready".
+        model_available = self._embedding_model_available()
         semantic_ready = bool(
             bm25_ready
+            and model_available
             and counts["vectors"] > 0
             and counts["pending"] == 0
             and self._semantic_state_current()
@@ -362,9 +367,15 @@ class QmdLocalRetriever:
         )
         embedding_state = self._embedding_state(status, semantic_ready=semantic_ready)
         if embedding_state == "missing_model":
-            warnings.append(
-                f"{EMBEDDING_MODEL} is not installed; hybrid requests degrade to lexical retrieval while embedding warms"
-            )
+            if counts["vectors"] > 0:
+                warnings.append(
+                    f"{EMBEDDING_MODEL} is missing while stored vectors are intact; "
+                    "semantic queries are unavailable until repair — run: bin/search.sh reindex --embed"
+                )
+            else:
+                warnings.append(
+                    f"{EMBEDDING_MODEL} is not installed; hybrid requests degrade to lexical retrieval while embedding warms"
+                )
 
         runtime = self._owned_runtime()
         if not canonical_ready or not qmd_available or not status_ok:
@@ -1568,10 +1579,13 @@ class QmdLocalRetriever:
     def _embedding_state(self, status: str, *, semantic_ready: bool = False) -> str:
         if self._live_lock(self._embed_lock_path()):
             return "running"
-        if semantic_ready:
-            return "ready"
+        # Model presence outranks stored-vector completeness: query-time
+        # embedding needs the model, so a complete build with a missing model
+        # is a repair state, not "ready".
         if not self._embedding_model_available():
             return "missing_model"
+        if semantic_ready:
+            return "ready"
         counts = self._status_counts(status)
         if counts["pending"] > 0 or counts["documents"] > 0:
             return "pending"

package/runtime/prime/egregore_runtime/readiness.py

@@ -236,6 +236,16 @@ def _embeddings_item(health: RetrieverHealth) -> ReadinessItem:
             key="embeddings", label=label, stage=STAGE_BUILDING, detail=detail
         )
     if state == "missing_model":
+        if health.semantic_source_revision:
+            return ReadinessItem(
+                key="embeddings",
+                label=label,
+                stage=STAGE_UNAVAILABLE,
+                detail=(
+                    "embedding model missing — stored vectors intact · "
+                    "repair: bin/search.sh reindex --embed"
+                ),
+            )
         return ReadinessItem(
             key="embeddings",
             label=label,
@@ -254,6 +264,16 @@ def _semantic_item(health: RetrieverHealth) -> ReadinessItem:
     label = "Semantic build"
     source = _short_revision(health.source_revision)
     build = _short_revision(health.semantic_source_revision)
+    if health.embedding_state == "missing_model":
+        return ReadinessItem(
+            key="semantic",
+            label=label,
+            stage=STAGE_UNAVAILABLE,
+            detail=(
+                "embedding model missing — semantic queries unavailable · "
+                "repair: bin/search.sh reindex --embed"
+            ),
+        )
     if health.semantic_ready:
         return ReadinessItem(
             key="semantic",
@@ -282,6 +302,16 @@ def _search_item(health: RetrieverHealth) -> ReadinessItem:
         return ReadinessItem(
             key="search", label=label, stage=STAGE_READY, detail="hybrid current"
         )
+    if health.bm25_ready and health.embedding_state == "missing_model":
+        return ReadinessItem(
+            key="search",
+            label=label,
+            stage=STAGE_READY,
+            detail=(
+                "lexical only — embedding model missing · "
+                "repair: bin/search.sh reindex --embed"
+            ),
+        )
     if health.bm25_ready and health.semantic_source_revision:
         return ReadinessItem(
             key="search",