create-egregore 0.21.0-runtime-mvp.13 → 0.21.0-runtime-mvp.15

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.21.0-runtime-mvp.13
+// egregore-launcher-version: 0.21.0-runtime-mvp.15
 //
 // 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.13";
+const VERSION = "0.21.0-runtime-mvp.15";
 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");
@@ -2673,7 +2673,11 @@ function formatUpgradeLines(inst, st, { candidate = "", retrieval = null } = {})
     + (d.candidate_version ? ` → candidate ${d.candidate_version}` : candidate ? ` → candidate ${candidate} available` : ""));
   lines.push(`Status: ${UPGRADE_STATUS_LABEL[d.status] || d.status}`);
   if (d.candidate_digest) lines.push(`Package digest: sha256 ${String(d.candidate_digest).slice(0, 16)}…`);
-  if (d.failure && d.failure.message) lines.push(`Attention: ${d.failure.message}`);
+  // A recorded failure only needs attention while the transaction is stuck
+  // on it; once a later prepare succeeds the line would contradict "ready".
+  if (d.failure && d.failure.message && (d.status === "failed" || d.status === "interrupted")) {
+    lines.push(`Attention: ${d.failure.message}`);
+  }
   if (d.rollback_version && d.status !== "none") lines.push(`Rollback target: ${d.rollback_version}`);
   const ts = d.team_sync;
   if (ts && ts.label) lines.push(`Team memory: ${ts.label}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-egregore",
-  "version": "0.21.0-runtime-mvp.13",
+  "version": "0.21.0-runtime-mvp.15",
   "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/bin/lib/greeting.sh

@@ -95,19 +95,15 @@ if [ -n "$SAVED_BRANCH" ]; then
   echo "  ✓ Auto-saved uncommitted work on $SAVED_BRANCH"
 fi
 
-# --- Unshared org-settings drift (launcher writes not yet shared) ---
-if [ "${SETTINGS_ADAPTER_RESTORED:-false}" = "true" ]; then
-  echo "  ◇ restored org .claude/settings.json — a generated adapter had replaced it locally"
-fi
+# --- Org-settings sync receipts. A settings.json heal is logged to
+# .egregore/settings-drift.log, never announced; local settings changes reach
+# the control plane through bin/settings.sh, so there is nothing to ask. ---
 if [ -n "${SETTINGS_SYNCED_FROM_ORG:-}" ]; then
   echo "  ◇ org settings synced from the control plane (${SETTINGS_SYNCED_FROM_ORG})"
 fi
 if [ -n "${SETTINGS_POSTURE_HELD:-}" ]; then
   echo "  ◇ boundary posture was set to ${SETTINGS_POSTURE_HELD} elsewhere — relaxing access needs your confirm: bash bin/settings.sh posture ${SETTINGS_POSTURE_HELD}"
 fi
-if [ -n "${UNSHARED_SETTINGS_KEYS:-}" ]; then
-  echo "  ◇ org settings changed on this machine (${UNSHARED_SETTINGS_KEYS}) — say \"share settings\" to make them org-wide"
-fi
 
 # --- Footer: health + repos + memory (tertiary) ---
 echo "$SEPARATOR"

package/runtime/claude/bin/lib/settings-drift.sh

@@ -61,7 +61,11 @@ settings_drift_heal() {
 
   if ! git diff --quiet -- .claude/settings.json 2>/dev/null; then
     if _settings_is_reduced_adapter; then
-      git checkout -- .claude/settings.json 2>/dev/null && SETTINGS_ADAPTER_RESTORED="true"
+      if git checkout -- .claude/settings.json 2>/dev/null; then
+        SETTINGS_ADAPTER_RESTORED="true"
+        mkdir -p .egregore 2>/dev/null && printf '%s restored .claude/settings.json: a generated adapter had replaced the org file\n' \
+          "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> .egregore/settings-drift.log 2>/dev/null || true
+      fi
     fi
   fi
 

package/runtime/claude/bin/search.sh

@@ -32,6 +32,19 @@ _maintenance_runtime() {
     python3 -m egregore_runtime.adapters.qmd_cli "$@"
 }
 
+_now_ms() {
+  if command -v perl >/dev/null 2>&1; then
+    perl -MTime::HiRes=time -e 'printf("%d\n", time() * 1000)'
+  else
+    echo $(( $(date +%s) * 1000 ))
+  fi
+}
+
+_elapsed_s() {
+  # One-decimal seconds since a _now_ms() timestamp.
+  awk -v ms="$(( $(_now_ms) - $1 ))" 'BEGIN { printf "%.1f", ms / 1000 }'
+}
+
 _result_paths() {
   local line path canonical_prefix
   canonical_prefix="**file:** \`memory/"
@@ -125,14 +138,14 @@ _banner_and_emit() {
     actual="${actual%% *}"
     required="${gap#*required=}"
     required="${required%% *}"
-    dur=$(( $(date +%s) - t0 ))
+    dur=$(_elapsed_s "$t0")
     printf '⌕ Egregore · searching your organization’s memory · %s · evidence gap · %s/%s sources · %ss\n\n' \
       "$label" "$actual" "$required" "$dur"
     [ "$hide_results" = 1 ] || printf '%s\n' "$out" | tail -n +2
     return 0
   fi
   hits=$(printf '%s\n' "$out" | _result_paths | wc -l | tr -d ' ')
-  dur=$(( $(date +%s) - t0 ))
+  dur=$(_elapsed_s "$t0")
   product="Egregore"
   surface="searching your organization’s memory"
   if [ "$emit" = "_enrich" ] && [ "$hits" -gt 0 ]; then
@@ -223,7 +236,7 @@ cmd_query() {
   esac
 
   local t0 out emit="cat" query_rc
-  t0=$(date +%s)
+  t0=$(_now_ms)
   out=$(_runtime "${args[@]}" 2>&1)
   query_rc=$?
   if [ "$query_rc" -ne 0 ]; then
@@ -235,20 +248,31 @@ cmd_query() {
     } >&2
     return "$query_rc"
   fi
-  # Content-free query telemetry: mode, duration, result count. Never the
-  # query text. This is what makes Runtime/QMD retrieval visible in the
-  # telemetry event list instead of only legacy graph_query rows.
+  # The runtime marks a query that ran without its persistent worker (the
+  # pinned CLI started cold). Strip the marker from the evidence and carry
+  # it into the banner, the telemetry, and a one-line repair hint.
+  local cold=0 cold_json=false
+  if printf '%s\n' "$out" | grep -qx 'EGREGORE_RETRIEVAL_COLD_START'; then
+    cold=1
+    cold_json=true
+    out=$(printf '%s\n' "$out" | grep -vx 'EGREGORE_RETRIEVAL_COLD_START')
+  fi
+  # Content-free query telemetry: mode, duration, result count, degraded
+  # path. Never the query text. This is what makes Runtime/QMD retrieval
+  # visible in the telemetry event list instead of only legacy graph_query rows.
   local _tele_count _tele_ms
-  _tele_ms=$(( ($(date +%s) - t0) * 1000 ))
+  _tele_ms=$(( $(_now_ms) - t0 ))
   _tele_count=$(printf '%s' "$out" | jq 'if type == "array" then length elif type == "object" then (.results // [] | length) else empty end' 2>/dev/null || true)
   if [[ "$_tele_count" =~ ^[0-9]+$ ]]; then
     bash "$SCRIPT_DIR/bin/telemetry.sh" emit "query" \
-      "$(jq -n --arg mode "$label" --argjson d "$_tele_ms" --argjson c "$_tele_count" \
-        '{mode:$mode, duration_ms:$d, count:$c}')" 2>/dev/null &
+      "$(jq -n --arg mode "$label" --argjson d "$_tele_ms" --argjson c "$_tele_count" --argjson cold "$cold_json" \
+        '{mode:$mode, duration_ms:$d, count:$c, degraded:$cold}')" 2>/dev/null &
   else
     bash "$SCRIPT_DIR/bin/telemetry.sh" emit "query" \
-      "$(jq -n --arg mode "$label" --argjson d "$_tele_ms" '{mode:$mode, duration_ms:$d}')" 2>/dev/null &
+      "$(jq -n --arg mode "$label" --argjson d "$_tele_ms" --argjson cold "$cold_json" \
+        '{mode:$mode, duration_ms:$d, degraded:$cold}')" 2>/dev/null &
   fi
+  [ "$cold" = 1 ] && label="${label} · cold start"
 
   [ "$enrich" = 1 ] && emit="_enrich"
   if [ "$context_packet" = 1 ]; then
@@ -263,6 +287,9 @@ cmd_query() {
   else
     _banner_and_emit "$label" "$t0" "$emit" "$out"
   fi
+  if [ "$cold" = 1 ]; then
+    echo "  ↳ the retrieval server was not running, so this query started QMD cold. Repair: bash bin/search.sh start" >&2
+  fi
 }
 
 cmd_reindex() {

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

@@ -157,6 +157,11 @@ class QmdLocalRetriever:
         self._resolved_command: tuple[str, ...] | None = None
         self._version_checked = False
         self._daemon_available = False
+        # Outcome of the most recent typed query: True when the owned worker
+        # answered, False when the pinned CLI ran cold, None when no query
+        # ran or persistence is disabled. Read by the harness so a slow
+        # retrieval is never silent.
+        self._last_query_used_daemon: bool | None = None
         self._source_revision_cache: str | None = None
         self._configure_isolated_environment()
         self._prefer_usable_node_runtime()
@@ -726,7 +731,10 @@ class QmdLocalRetriever:
         limit: int,
         intent: str,
     ) -> list[dict[str, Any]]:
-        if self._persistent_enabled() and self._ensure_daemon():
+        self._last_query_used_daemon = None
+        if not self._persistent_enabled():
+            daemon_error = "daemon unavailable"
+        elif self._ensure_daemon():
             payload = {
                 "searches": searches,
                 "collections": [self.collection],
@@ -746,6 +754,7 @@ class QmdLocalRetriever:
                     body = json.loads(response.read().decode("utf-8"))
                 results = body.get("results") if isinstance(body, dict) else None
                 if isinstance(results, list):
+                    self._last_query_used_daemon = True
                     return [item for item in results if isinstance(item, dict)]
             except (OSError, ValueError, urllib.error.URLError) as exc:
                 self._daemon_available = False
@@ -754,8 +763,13 @@ class QmdLocalRetriever:
                 daemon_error = str(exc)
             else:
                 daemon_error = "daemon returned an invalid result payload"
+            self._last_query_used_daemon = False
         else:
+            # The owned worker could not be started or reused. The pinned CLI
+            # answers cold; the harness surfaces that instead of a silent
+            # multi-second query.
             daemon_error = "daemon unavailable"
+            self._last_query_used_daemon = False
 
         query_document = "\n".join(
             f"{item['type']}: {self._single_line(item['query'])}" for item in searches
@@ -1009,6 +1023,13 @@ class QmdLocalRetriever:
     def _persistent_enabled(self) -> bool:
         return self.environment.get("EGREGORE_QMD_PERSISTENT", "1") != "0"
 
+    @property
+    def last_query_used_daemon(self) -> bool | None:
+        """True when the last typed query answered through the owned worker,
+        False when it fell back to a cold CLI run, None when no query ran or
+        the persistent worker is disabled for this instance."""
+        return self._last_query_used_daemon
+
     def _ensure_daemon(self) -> bool:
         if not self._persistent_enabled():
             return False
@@ -1153,15 +1174,30 @@ class QmdLocalRetriever:
 
     @staticmethod
     def _port_available(port: int) -> bool:
+        """A port is free only when both loopback families can bind it.
+
+        The worker binds "localhost", which resolves to ::1 as well as
+        127.0.0.1. Probing IPv4 alone reported a port free while a foreign
+        server held [::1] on it; the owned worker then died on bind and every
+        query ran the CLI cold.
+        """
         if port == 8181:
             return False
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
-            probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        for family, address in (
+            (socket.AF_INET, "127.0.0.1"),
+            (socket.AF_INET6, "::1"),
+        ):
             try:
-                probe.bind(("127.0.0.1", port))
-                return True
+                probe = socket.socket(family, socket.SOCK_STREAM)
             except OSError:
-                return False
+                continue  # family not available on this host
+            with probe:
+                probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                try:
+                    probe.bind((address, port))
+                except OSError:
+                    return False
+        return True
 
     def _allocate_port(self) -> int:
         for _ in range(20):

package/runtime/claude/egregore_runtime/harness_cli.py

@@ -369,6 +369,12 @@ def _query(args: argparse.Namespace) -> int:
             )
         else:
             print("No results found.")
+    retriever = getattr(runtime, "retriever", None)
+    if not args.json and getattr(retriever, "last_query_used_daemon", None) is False:
+        # The owned QMD worker was unavailable and the pinned CLI answered
+        # cold. bin/search.sh turns this marker into a visible "cold start"
+        # note so a slow query is never silent.
+        print("EGREGORE_RETRIEVAL_COLD_START")
     return 0
 
 

package/runtime/claude/egregore_runtime/upgrade.py

@@ -53,6 +53,40 @@ BUNDLE_TREES = ("claude", "codex", "pi", "prime")
 # wins and duplicates are skipped.
 APPLY_TREES = ("claude", "codex", "pi", "prime")
 APPLY_TREE = APPLY_TREES[0]
+# Bundle metadata at the root of each adapter tree; never instance content.
+BUNDLE_MANIFEST = "manifest.json"
+# The harness settings adapter the bundle generates; an instance's richer
+# committed copy is preserved on activation.
+SETTINGS_ADAPTER = ".claude/settings.json"
+
+
+def _settings_carries_more(existing: Path, candidate: Path) -> bool:
+    """True when the instance's settings file has hook events or permission
+    allows the candidate's generated adapter lacks. An unreadable candidate
+    keeps the existing file; an unreadable or missing existing file does not."""
+    if not existing.is_file():
+        return False
+    try:
+        current = json.loads(existing.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    try:
+        incoming = json.loads(candidate.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return True
+    if not isinstance(current, dict) or not isinstance(incoming, dict):
+        return False
+
+    def hooks(doc: dict) -> set[str]:
+        value = doc.get("hooks")
+        return set(value.keys()) if isinstance(value, dict) else set()
+
+    def allows(doc: dict) -> set[str]:
+        perms = doc.get("permissions")
+        value = perms.get("allow") if isinstance(perms, dict) else None
+        return {str(v) for v in value} if isinstance(value, list) else set()
+
+    return bool(hooks(current) - hooks(incoming)) or bool(allows(current) - allows(incoming))
 
 STATUS_PENDING = "pending"
 STATUS_PREPARING = "preparing"
@@ -744,6 +778,22 @@ class UpgradeEngine:
                     continue
                 relative = str(source_file.relative_to(tree))
                 selected.setdefault(relative, source_file)
+        # The bundle's own manifest describes the package, not the instance;
+        # nothing in an instance reads it and it only shows up as an untracked
+        # file in the instance's repository.
+        selected.pop(BUNDLE_MANIFEST, None)
+        # The instance's own settings adapter may carry hook events or
+        # permission allows the generated public-safe adapter lacks (an org's
+        # committed .claude/settings.json). Activation never reduces it — the
+        # same rule the installer applies. A stale generated adapter (equal or
+        # a subset) still upgrades.
+        preserved: list[str] = []
+        candidate_settings = selected.get(SETTINGS_ADAPTER)
+        if candidate_settings is not None and _settings_carries_more(
+            instance / SETTINGS_ADAPTER, candidate_settings
+        ):
+            selected.pop(SETTINGS_ADAPTER, None)
+            preserved.append(SETTINGS_ADAPTER)
         # Journal opens the transaction BEFORE the first byte moves. From here
         # until the caller clears it, a crash is recoverable from the backup.
         self.store.write_apply_journal({
@@ -794,7 +844,12 @@ class UpgradeEngine:
             (self.store.root / "rollback-files.tar.gz").unlink(missing_ok=True)
             (self.store.root / "rollback-manifest.json").unlink(missing_ok=True)
             raise
-        return {"applied_files": len(selected), "replaced": len(replaced), "added": len(added)}
+        return {
+            "applied_files": len(selected),
+            "replaced": len(replaced),
+            "added": len(added),
+            "preserved": preserved,
+        }
 
     def activate(self) -> dict[str, Any]:
         self._acquire_apply_lock()
@@ -886,7 +941,14 @@ class UpgradeEngine:
         self.store.request_cancel()
         worker = state.get("worker") or {}
         pid = worker.get("pid")
-        if state.get("status") == STATUS_PREPARING and not (pid and _pid_alive(pid)):
+        status = state.get("status")
+        if status in (STATUS_PENDING, STATUS_READY, STATUS_FAILED):
+            # Nothing is running: release the staged candidate outright so a
+            # newer one can be staged. A ready or failed candidate used to be
+            # unreleasable — cancel ignored it and init refused "already staged".
+            state["status"] = STATUS_CANCELLED
+            self.store.write(state)
+        elif status == STATUS_PREPARING and not (pid and _pid_alive(pid)):
             # No live worker will observe the flag — record the cancel now.
             state["status"] = STATUS_CANCELLED
             self.store.write(state)

package/runtime/codex/bin/lib/greeting.sh

@@ -95,19 +95,15 @@ if [ -n "$SAVED_BRANCH" ]; then
   echo "  ✓ Auto-saved uncommitted work on $SAVED_BRANCH"
 fi
 
-# --- Unshared org-settings drift (launcher writes not yet shared) ---
-if [ "${SETTINGS_ADAPTER_RESTORED:-false}" = "true" ]; then
-  echo "  ◇ restored org .claude/settings.json — a generated adapter had replaced it locally"
-fi
+# --- Org-settings sync receipts. A settings.json heal is logged to
+# .egregore/settings-drift.log, never announced; local settings changes reach
+# the control plane through bin/settings.sh, so there is nothing to ask. ---
 if [ -n "${SETTINGS_SYNCED_FROM_ORG:-}" ]; then
   echo "  ◇ org settings synced from the control plane (${SETTINGS_SYNCED_FROM_ORG})"
 fi
 if [ -n "${SETTINGS_POSTURE_HELD:-}" ]; then
   echo "  ◇ boundary posture was set to ${SETTINGS_POSTURE_HELD} elsewhere — relaxing access needs your confirm: bash bin/settings.sh posture ${SETTINGS_POSTURE_HELD}"
 fi
-if [ -n "${UNSHARED_SETTINGS_KEYS:-}" ]; then
-  echo "  ◇ org settings changed on this machine (${UNSHARED_SETTINGS_KEYS}) — say \"share settings\" to make them org-wide"
-fi
 
 # --- Footer: health + repos + memory (tertiary) ---
 echo "$SEPARATOR"

package/runtime/codex/bin/lib/settings-drift.sh

@@ -61,7 +61,11 @@ settings_drift_heal() {
 
   if ! git diff --quiet -- .claude/settings.json 2>/dev/null; then
     if _settings_is_reduced_adapter; then
-      git checkout -- .claude/settings.json 2>/dev/null && SETTINGS_ADAPTER_RESTORED="true"
+      if git checkout -- .claude/settings.json 2>/dev/null; then
+        SETTINGS_ADAPTER_RESTORED="true"
+        mkdir -p .egregore 2>/dev/null && printf '%s restored .claude/settings.json: a generated adapter had replaced the org file\n' \
+          "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> .egregore/settings-drift.log 2>/dev/null || true
+      fi
     fi
   fi
 

package/runtime/codex/bin/search.sh

@@ -32,6 +32,19 @@ _maintenance_runtime() {
     python3 -m egregore_runtime.adapters.qmd_cli "$@"
 }
 
+_now_ms() {
+  if command -v perl >/dev/null 2>&1; then
+    perl -MTime::HiRes=time -e 'printf("%d\n", time() * 1000)'
+  else
+    echo $(( $(date +%s) * 1000 ))
+  fi
+}
+
+_elapsed_s() {
+  # One-decimal seconds since a _now_ms() timestamp.
+  awk -v ms="$(( $(_now_ms) - $1 ))" 'BEGIN { printf "%.1f", ms / 1000 }'
+}
+
 _result_paths() {
   local line path canonical_prefix
   canonical_prefix="**file:** \`memory/"
@@ -125,14 +138,14 @@ _banner_and_emit() {
     actual="${actual%% *}"
     required="${gap#*required=}"
     required="${required%% *}"
-    dur=$(( $(date +%s) - t0 ))
+    dur=$(_elapsed_s "$t0")
     printf '⌕ Egregore · searching your organization’s memory · %s · evidence gap · %s/%s sources · %ss\n\n' \
       "$label" "$actual" "$required" "$dur"
     [ "$hide_results" = 1 ] || printf '%s\n' "$out" | tail -n +2
     return 0
   fi
   hits=$(printf '%s\n' "$out" | _result_paths | wc -l | tr -d ' ')
-  dur=$(( $(date +%s) - t0 ))
+  dur=$(_elapsed_s "$t0")
   product="Egregore"
   surface="searching your organization’s memory"
   if [ "$emit" = "_enrich" ] && [ "$hits" -gt 0 ]; then
@@ -223,7 +236,7 @@ cmd_query() {
   esac
 
   local t0 out emit="cat" query_rc
-  t0=$(date +%s)
+  t0=$(_now_ms)
   out=$(_runtime "${args[@]}" 2>&1)
   query_rc=$?
   if [ "$query_rc" -ne 0 ]; then
@@ -235,20 +248,31 @@ cmd_query() {
     } >&2
     return "$query_rc"
   fi
-  # Content-free query telemetry: mode, duration, result count. Never the
-  # query text. This is what makes Runtime/QMD retrieval visible in the
-  # telemetry event list instead of only legacy graph_query rows.
+  # The runtime marks a query that ran without its persistent worker (the
+  # pinned CLI started cold). Strip the marker from the evidence and carry
+  # it into the banner, the telemetry, and a one-line repair hint.
+  local cold=0 cold_json=false
+  if printf '%s\n' "$out" | grep -qx 'EGREGORE_RETRIEVAL_COLD_START'; then
+    cold=1
+    cold_json=true
+    out=$(printf '%s\n' "$out" | grep -vx 'EGREGORE_RETRIEVAL_COLD_START')
+  fi
+  # Content-free query telemetry: mode, duration, result count, degraded
+  # path. Never the query text. This is what makes Runtime/QMD retrieval
+  # visible in the telemetry event list instead of only legacy graph_query rows.
   local _tele_count _tele_ms
-  _tele_ms=$(( ($(date +%s) - t0) * 1000 ))
+  _tele_ms=$(( $(_now_ms) - t0 ))
   _tele_count=$(printf '%s' "$out" | jq 'if type == "array" then length elif type == "object" then (.results // [] | length) else empty end' 2>/dev/null || true)
   if [[ "$_tele_count" =~ ^[0-9]+$ ]]; then
     bash "$SCRIPT_DIR/bin/telemetry.sh" emit "query" \
-      "$(jq -n --arg mode "$label" --argjson d "$_tele_ms" --argjson c "$_tele_count" \
-        '{mode:$mode, duration_ms:$d, count:$c}')" 2>/dev/null &
+      "$(jq -n --arg mode "$label" --argjson d "$_tele_ms" --argjson c "$_tele_count" --argjson cold "$cold_json" \
+        '{mode:$mode, duration_ms:$d, count:$c, degraded:$cold}')" 2>/dev/null &
   else
     bash "$SCRIPT_DIR/bin/telemetry.sh" emit "query" \
-      "$(jq -n --arg mode "$label" --argjson d "$_tele_ms" '{mode:$mode, duration_ms:$d}')" 2>/dev/null &
+      "$(jq -n --arg mode "$label" --argjson d "$_tele_ms" --argjson cold "$cold_json" \
+        '{mode:$mode, duration_ms:$d, degraded:$cold}')" 2>/dev/null &
   fi
+  [ "$cold" = 1 ] && label="${label} · cold start"
 
   [ "$enrich" = 1 ] && emit="_enrich"
   if [ "$context_packet" = 1 ]; then
@@ -263,6 +287,9 @@ cmd_query() {
   else
     _banner_and_emit "$label" "$t0" "$emit" "$out"
   fi
+  if [ "$cold" = 1 ]; then
+    echo "  ↳ the retrieval server was not running, so this query started QMD cold. Repair: bash bin/search.sh start" >&2
+  fi
 }
 
 cmd_reindex() {

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

@@ -157,6 +157,11 @@ class QmdLocalRetriever:
         self._resolved_command: tuple[str, ...] | None = None
         self._version_checked = False
         self._daemon_available = False
+        # Outcome of the most recent typed query: True when the owned worker
+        # answered, False when the pinned CLI ran cold, None when no query
+        # ran or persistence is disabled. Read by the harness so a slow
+        # retrieval is never silent.
+        self._last_query_used_daemon: bool | None = None
         self._source_revision_cache: str | None = None
         self._configure_isolated_environment()
         self._prefer_usable_node_runtime()
@@ -726,7 +731,10 @@ class QmdLocalRetriever:
         limit: int,
         intent: str,
     ) -> list[dict[str, Any]]:
-        if self._persistent_enabled() and self._ensure_daemon():
+        self._last_query_used_daemon = None
+        if not self._persistent_enabled():
+            daemon_error = "daemon unavailable"
+        elif self._ensure_daemon():
             payload = {
                 "searches": searches,
                 "collections": [self.collection],
@@ -746,6 +754,7 @@ class QmdLocalRetriever:
                     body = json.loads(response.read().decode("utf-8"))
                 results = body.get("results") if isinstance(body, dict) else None
                 if isinstance(results, list):
+                    self._last_query_used_daemon = True
                     return [item for item in results if isinstance(item, dict)]
             except (OSError, ValueError, urllib.error.URLError) as exc:
                 self._daemon_available = False
@@ -754,8 +763,13 @@ class QmdLocalRetriever:
                 daemon_error = str(exc)
             else:
                 daemon_error = "daemon returned an invalid result payload"
+            self._last_query_used_daemon = False
         else:
+            # The owned worker could not be started or reused. The pinned CLI
+            # answers cold; the harness surfaces that instead of a silent
+            # multi-second query.
             daemon_error = "daemon unavailable"
+            self._last_query_used_daemon = False
 
         query_document = "\n".join(
             f"{item['type']}: {self._single_line(item['query'])}" for item in searches
@@ -1009,6 +1023,13 @@ class QmdLocalRetriever:
     def _persistent_enabled(self) -> bool:
         return self.environment.get("EGREGORE_QMD_PERSISTENT", "1") != "0"
 
+    @property
+    def last_query_used_daemon(self) -> bool | None:
+        """True when the last typed query answered through the owned worker,
+        False when it fell back to a cold CLI run, None when no query ran or
+        the persistent worker is disabled for this instance."""
+        return self._last_query_used_daemon
+
     def _ensure_daemon(self) -> bool:
         if not self._persistent_enabled():
             return False
@@ -1153,15 +1174,30 @@ class QmdLocalRetriever:
 
     @staticmethod
     def _port_available(port: int) -> bool:
+        """A port is free only when both loopback families can bind it.
+
+        The worker binds "localhost", which resolves to ::1 as well as
+        127.0.0.1. Probing IPv4 alone reported a port free while a foreign
+        server held [::1] on it; the owned worker then died on bind and every
+        query ran the CLI cold.
+        """
         if port == 8181:
             return False
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
-            probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        for family, address in (
+            (socket.AF_INET, "127.0.0.1"),
+            (socket.AF_INET6, "::1"),
+        ):
             try:
-                probe.bind(("127.0.0.1", port))
-                return True
+                probe = socket.socket(family, socket.SOCK_STREAM)
             except OSError:
-                return False
+                continue  # family not available on this host
+            with probe:
+                probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                try:
+                    probe.bind((address, port))
+                except OSError:
+                    return False
+        return True
 
     def _allocate_port(self) -> int:
         for _ in range(20):

package/runtime/codex/egregore_runtime/harness_cli.py

@@ -369,6 +369,12 @@ def _query(args: argparse.Namespace) -> int:
             )
         else:
             print("No results found.")
+    retriever = getattr(runtime, "retriever", None)
+    if not args.json and getattr(retriever, "last_query_used_daemon", None) is False:
+        # The owned QMD worker was unavailable and the pinned CLI answered
+        # cold. bin/search.sh turns this marker into a visible "cold start"
+        # note so a slow query is never silent.
+        print("EGREGORE_RETRIEVAL_COLD_START")
     return 0