create-egregore 0.21.0-runtime-mvp.3 → 0.21.0-runtime-mvp.5

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.21.0-runtime-mvp.3
+// egregore-launcher-version: 0.21.0-runtime-mvp.5
 //
 // 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.3";
+const VERSION = "0.21.0-runtime-mvp.5";
 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.
@@ -2542,6 +2576,26 @@ const UPGRADE_STATUS_LABEL = {
   "rolled-back": "rolled back",
 };
 
+// Settings-row truth for the Runtime update line. The row must say outright
+// whether this egregore runs the new Runtime — "no update staged" is
+// transaction state, not the condition the user needs to see.
+function runtimeUpdateRowValue(st, candidate) {
+  if (st === undefined) return `${DIM}checking…${RESET}`;
+  if (st === null) return `${DIM}unavailable${RESET}`;
+  if (st.status === "active") {
+    const v = st.active_version || "?";
+    if (candidate && candidate !== v) return `${v} active ${YELLOW}· update available ${candidate}${RESET}`;
+    return `${GREEN}${v} active${RESET}${candidate ? `${DIM} · up to date${RESET}` : ""}`;
+  }
+  if (st.status === "ready-to-activate") return `${GREEN}${upgradeSummary(st)}${RESET}`;
+  if (st.status === "failed" || st.status === "interrupted") return `${YELLOW}${upgradeSummary(st)}${RESET}`;
+  if (st.status === "preparing" || st.status === "pending") return `${DIM}${upgradeSummary(st)}${RESET}`;
+  // No activation record (or cancelled/rolled back): this egregore is not on
+  // the new Runtime. Say so, and name the candidate when we know it.
+  const base = `${YELLOW}not updated to the new Runtime${RESET}`;
+  return candidate ? `${base}${DIM} · ${candidate} available${RESET}` : base;
+}
+
 function upgradeSummary(st) {
   // "none" means no activation record — a first-time state, not freshness.
   if (!st || st.status === "none") return "no update staged";
@@ -2560,7 +2614,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 +2635,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 +3049,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 +3062,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 +3106,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, candidate }) {
   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);
@@ -3186,17 +3251,14 @@ function renderSettingsPanel({ inst, data, cursor, view, domain, items, listCurs
       lines.push(boxLine(`${DIM}↑↓ nav · ${RESET}${BOLD}a${RESET}${DIM} add · ${RESET}${BOLD}d${RESET}${DIM} delete · ← back · q quit${RESET}`, innerWidth, margin));
     }
   } else {
-    const upgradeValue = upgrade === undefined
-      ? `${DIM}checking…${RESET}`
-      : upgrade === null
-        ? `${DIM}unavailable${RESET}`
-        : upgrade.status === "ready-to-activate"
-          ? `${GREEN}${upgradeSummary(upgrade)}${RESET}`
-          : upgrade.status === "failed" || upgrade.status === "interrupted"
-            ? `${YELLOW}${upgradeSummary(upgrade)}${RESET}`
-            : `${DIM}${upgradeSummary(upgrade)}${RESET}`;
+    const upgradeValue = runtimeUpdateRowValue(upgrade, candidate);
     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 +3412,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 +3438,8 @@ async function browser(args = {}) {
         notice: state.settingsNotice,
         width: w,
         upgrade: state.settingsUpgrade,
+        retrieval: state.settingsRetrieval,
+        candidate: state.upgradeCandidate,
       });
       for (const line of settingsLines) out.push(line + ANSI.clearLine + "\n");
       const remainingRows = Math.max(0, h - settingsLines.length - 1);
@@ -3903,8 +3968,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 +4260,21 @@ 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();
+        });
+        if (!state.upgradeCandidate) {
+          fetchRuntimeMvpCandidate().then((v) => {
+            state.upgradeCandidate = v || "";
+            if (state.settingsInst === pick && !state.upgradeInst) render();
+          });
+        }
         state.settingsNotice = "";
         render();
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-egregore",
-  "version": "0.21.0-runtime-mvp.3",
+  "version": "0.21.0-runtime-mvp.5",
   "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",