@askexenow/exe-os 0.9.294 → 0.9.296

package/dist/chunk-5Q4MR6SL.js

@@ -0,0 +1,123 @@
+import {
+  getClient
+} from "./chunk-WUKHLCBE.js";
+
+// src/lib/session-kill-telemetry.ts
+import crypto from "crypto";
+import { appendFileSync } from "fs";
+import path from "path";
+import os from "os";
+var KILL_FILE_LOG = path.join(os.homedir(), ".exe-os", "logs", "session-kills.jsonl");
+var TOKENS_PER_IDLE_MINUTE = 50;
+async function recordSessionKill(input) {
+  const killedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const id = crypto.randomUUID();
+  try {
+    const logEntry = JSON.stringify({
+      id,
+      timestamp: killedAt,
+      session: input.sessionName,
+      agent: input.agentId,
+      reason: input.reason,
+      ticksIdle: input.ticksIdle ?? null,
+      tokensSaved: input.estimatedTokensSaved ?? null
+    });
+    appendFileSync(KILL_FILE_LOG, logEntry + "\n");
+  } catch {
+    process.stderr.write(
+      `[session-kill-telemetry] file log write failed for ${input.sessionName}
+`
+    );
+  }
+  try {
+    const client = getClient();
+    await client.execute({
+      sql: `INSERT INTO session_kills
+              (id, session_name, agent_id, killed_at, reason,
+               ticks_idle, estimated_tokens_saved)
+            VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      args: [
+        id,
+        input.sessionName,
+        input.agentId,
+        killedAt,
+        input.reason,
+        input.ticksIdle ?? null,
+        input.estimatedTokensSaved ?? null
+      ]
+    });
+  } catch (err) {
+    process.stderr.write(
+      `[session-kill-telemetry] DB write failed: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+  }
+}
+async function countKillsSince(sinceISO) {
+  try {
+    const client = getClient();
+    const result = await client.execute({
+      sql: `SELECT COUNT(*) AS n FROM session_kills WHERE killed_at >= ?`,
+      args: [sinceISO]
+    });
+    const row = result.rows[0];
+    return row ? Number(row.n) : 0;
+  } catch {
+    return 0;
+  }
+}
+var IDLE_KILL_STREAK_META_KEY = "idle_kill_suspect_streak";
+var IDLE_KILL_SUSPECT_DAY_THRESHOLD = 3;
+var IDLE_KILL_MIN_LIVE_SESSIONS = 5;
+function parseStreakState(raw) {
+  if (!raw) return { lastDate: null, streak: 0 };
+  try {
+    const parsed = JSON.parse(raw);
+    return {
+      lastDate: typeof parsed.lastDate === "string" ? parsed.lastDate : null,
+      streak: typeof parsed.streak === "number" ? parsed.streak : 0
+    };
+  } catch {
+    return { lastDate: null, streak: 0 };
+  }
+}
+function nextStreakState(prev, qualifiesToday, todayDate) {
+  if (!qualifiesToday) return { lastDate: todayDate, streak: 0 };
+  if (prev.lastDate === todayDate) return prev;
+  return { lastDate: todayDate, streak: prev.streak + 1 };
+}
+function computeIdleKillSuspectStreak(prev, killsToday, liveSessions, todayDate) {
+  const qualifies = killsToday === 0 && liveSessions >= IDLE_KILL_MIN_LIVE_SESSIONS;
+  const state = nextStreakState(prev, qualifies, todayDate);
+  return {
+    state,
+    suspect: state.streak >= IDLE_KILL_SUSPECT_DAY_THRESHOLD
+  };
+}
+async function sumTokensSavedSince(sinceISO) {
+  try {
+    const client = getClient();
+    const result = await client.execute({
+      sql: `SELECT COALESCE(SUM(estimated_tokens_saved), 0) AS total
+            FROM session_kills
+            WHERE killed_at >= ?`,
+      args: [sinceISO]
+    });
+    const row = result.rows[0];
+    return row ? Number(row.total) : 0;
+  } catch {
+    return 0;
+  }
+}
+
+export {
+  TOKENS_PER_IDLE_MINUTE,
+  recordSessionKill,
+  countKillsSince,
+  IDLE_KILL_STREAK_META_KEY,
+  IDLE_KILL_SUSPECT_DAY_THRESHOLD,
+  IDLE_KILL_MIN_LIVE_SESSIONS,
+  parseStreakState,
+  computeIdleKillSuspectStreak,
+  sumTokensSavedSince
+};

package/dist/chunk-6327RBWR.js

@@ -0,0 +1,345 @@
+import {
+  employeeSessionName,
+  isEmployeeAlive,
+  resolveExeSession,
+  sendIntercom,
+  strictSessionScopeFilter
+} from "./chunk-K5ZO532Q.js";
+import {
+  parseMessage,
+  serializeMessage
+} from "./chunk-4JERP7NT.js";
+import {
+  recordOrchestrationEventBestEffort
+} from "./chunk-NLZHVIOP.js";
+import {
+  getClient
+} from "./chunk-WUKHLCBE.js";
+
+// src/lib/messaging.ts
+import crypto from "crypto";
+function generateUlid() {
+  const timestamp = Date.now().toString(36).padStart(10, "0");
+  const random = crypto.randomBytes(10).toString("hex").slice(0, 16);
+  return (timestamp + random).toUpperCase();
+}
+function rowToMessage(row) {
+  return {
+    id: row.id,
+    fromAgent: row.from_agent,
+    fromDevice: row.from_device,
+    targetAgent: row.target_agent,
+    targetProject: row.target_project ?? null,
+    targetDevice: row.target_device,
+    sessionScope: row.session_scope ?? null,
+    content: row.content,
+    priority: row.priority ?? "normal",
+    status: row.status ?? "pending",
+    serverSeq: row.server_seq != null ? Number(row.server_seq) : null,
+    retryCount: Number(row.retry_count ?? 0),
+    createdAt: row.created_at,
+    deliveredAt: row.delivered_at ?? null,
+    processedAt: row.processed_at ?? null,
+    failedAt: row.failed_at ?? null,
+    failureReason: row.failure_reason ?? null
+  };
+}
+var MAX_RETRIES = 10;
+async function countUnreadMessages(targetAgent, sessionScope) {
+  const client = getClient();
+  const scope = strictSessionScopeFilter(sessionScope);
+  const result = await client.execute({
+    sql: `SELECT COUNT(*) AS count FROM messages
+          WHERE target_agent = ? AND status IN ('pending', 'delivered')${scope.sql}`,
+    args: [targetAgent, ...scope.args]
+  });
+  return Number(result.rows[0]?.count ?? 0);
+}
+async function sendMessage(input) {
+  const client = getClient();
+  const id = generateUlid();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const targetDevice = input.targetDevice ?? "local";
+  const sessionScope = input.sessionScope === void 0 ? resolveExeSession() : input.sessionScope;
+  await client.execute({
+    sql: `INSERT INTO messages (id, from_agent, from_device, target_agent, target_project, target_device, session_scope, content, priority, status, founder_id, created_at)
+          VALUES (?, ?, 'local', ?, ?, ?, ?, ?, ?, 'pending', ?, ?)`,
+    args: [
+      id,
+      input.fromAgent,
+      input.targetAgent,
+      input.targetProject ?? null,
+      targetDevice,
+      sessionScope,
+      input.content,
+      input.priority ?? "normal",
+      input.founderId ?? null,
+      now
+    ]
+  });
+  recordOrchestrationEventBestEffort({
+    eventType: "message.sent",
+    source: "messaging.sendMessage",
+    agentId: input.fromAgent,
+    payload: { targetAgent: input.targetAgent, priority: input.priority ?? "normal", targetDevice },
+    sessionScope: sessionScope ?? null
+  });
+  try {
+    if (targetDevice !== "local") {
+      await deliverCrossMachineMessage(id, targetDevice);
+    } else {
+      await deliverLocalMessage(id);
+    }
+  } catch {
+  }
+  const sentScope = strictSessionScopeFilter(sessionScope);
+  const result = await client.execute({
+    sql: `SELECT * FROM messages WHERE id = ?${sentScope.sql}`,
+    args: [id, ...sentScope.args]
+  });
+  return rowToMessage(result.rows[0]);
+}
+var _wsClientSend = null;
+function setWsClientSend(fn) {
+  _wsClientSend = fn;
+}
+async function deliverCrossMachineMessage(messageId, targetDevice) {
+  const client = getClient();
+  const result = await client.execute({
+    sql: "SELECT * FROM messages WHERE id = ?",
+    args: [messageId]
+  });
+  if (result.rows.length === 0) return false;
+  const msg = rowToMessage(result.rows[0]);
+  if (msg.status !== "pending") return false;
+  if (!_wsClientSend) {
+    return false;
+  }
+  const payload = JSON.stringify({
+    id: msg.id,
+    fromAgent: msg.fromAgent,
+    targetAgent: msg.targetAgent,
+    targetProject: msg.targetProject,
+    sessionScope: msg.sessionScope,
+    content: msg.content,
+    priority: msg.priority,
+    createdAt: msg.createdAt
+  });
+  const sent = _wsClientSend(targetDevice, payload);
+  if (sent) {
+    await client.execute({
+      sql: "UPDATE messages SET status = 'synced' WHERE id = ?",
+      args: [messageId]
+    });
+    return true;
+  }
+  return false;
+}
+async function deliverLocalMessage(messageId) {
+  const client = getClient();
+  const result = await client.execute({
+    sql: "SELECT * FROM messages WHERE id = ?",
+    args: [messageId]
+  });
+  if (result.rows.length === 0) return false;
+  const msg = rowToMessage(result.rows[0]);
+  if (msg.status !== "pending") return false;
+  const targetAgent = msg.targetAgent;
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  try {
+    const exeSession = resolveExeSession();
+    if (!exeSession) {
+      throw new Error("No coordinator session found");
+    }
+    process.stderr.write(`[messaging] ENTER deliverLocal: target=${targetAgent} exeSession=${exeSession}
+`);
+    const { isCoordinatorName: isCoord } = await import("./lib/employees.js");
+    const isCOO = isCoord(targetAgent);
+    process.stderr.write(`[messaging] COO check: targetAgent="${targetAgent}" isCOO=${isCOO}
+`);
+    const sessionName = isCOO ? exeSession : employeeSessionName(targetAgent, exeSession);
+    process.stderr.write(`[messaging] delivery attempt: target=${targetAgent} session=${sessionName} isCOO=${isCOO}
+`);
+    if (!isCOO && !isEmployeeAlive(sessionName)) {
+      throw new Error("Session not running \u2014 message stays queued");
+    }
+    const unreadCount = await countUnreadMessages(targetAgent, msg.sessionScope);
+    if (unreadCount <= 0) {
+      return false;
+    }
+    const intercomResult = sendIntercom(sessionName, { force: true, reason: "message" });
+    process.stderr.write(`[messaging] intercom result for ${sessionName}: ${intercomResult}
+`);
+    await client.execute({
+      sql: "UPDATE messages SET status = 'delivered', delivered_at = ? WHERE id = ?",
+      args: [now, messageId]
+    });
+    recordOrchestrationEventBestEffort({
+      eventType: "message.delivered",
+      source: "messaging.deliverLocalMessage",
+      agentId: msg.targetAgent,
+      payload: { fromAgent: msg.fromAgent, priority: msg.priority }
+    });
+    return true;
+  } catch (err) {
+    process.stderr.write(
+      `[messaging] delivery failed for message ${messageId}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    const newRetryCount = msg.retryCount + 1;
+    if (newRetryCount >= MAX_RETRIES) {
+      await markFailed(messageId, "session unavailable after 10 retries", msg.sessionScope);
+    } else {
+      await client.execute({
+        sql: "UPDATE messages SET retry_count = ? WHERE id = ?",
+        args: [newRetryCount, messageId]
+      });
+    }
+    return false;
+  }
+}
+async function getPendingMessages(targetAgent, sessionScope) {
+  const client = getClient();
+  const scope = strictSessionScopeFilter(sessionScope);
+  const result = await client.execute({
+    sql: `SELECT * FROM messages
+          WHERE target_agent = ? AND status IN ('pending', 'delivered')${scope.sql}
+          ORDER BY id`,
+    args: [targetAgent, ...scope.args]
+  });
+  return result.rows.map((row) => rowToMessage(row));
+}
+async function markRead(messageId, sessionScope) {
+  const client = getClient();
+  const scope = strictSessionScopeFilter(sessionScope);
+  await client.execute({
+    sql: `UPDATE messages SET status = 'read'
+          WHERE id = ? AND status IN ('pending', 'delivered')${scope.sql}`,
+    args: [messageId, ...scope.args]
+  });
+  recordOrchestrationEventBestEffort({
+    eventType: "message.read",
+    source: "messaging.markRead",
+    payload: { messageId }
+  });
+}
+async function markAcknowledged(messageId, sessionScope) {
+  const client = getClient();
+  const scope = strictSessionScopeFilter(sessionScope);
+  await client.execute({
+    sql: `UPDATE messages SET status = 'acknowledged', processed_at = ?
+          WHERE id = ? AND status = 'read'${scope.sql}`,
+    args: [(/* @__PURE__ */ new Date()).toISOString(), messageId, ...scope.args]
+  });
+}
+async function markProcessed(messageId, sessionScope) {
+  const client = getClient();
+  const scope = strictSessionScopeFilter(sessionScope);
+  await client.execute({
+    sql: `UPDATE messages SET status = 'processed', processed_at = ?
+          WHERE id = ?${scope.sql}`,
+    args: [(/* @__PURE__ */ new Date()).toISOString(), messageId, ...scope.args]
+  });
+}
+async function getMessageStatus(messageId, sessionScope) {
+  const client = getClient();
+  const scope = strictSessionScopeFilter(sessionScope);
+  const result = await client.execute({
+    sql: `SELECT status FROM messages WHERE id = ?${scope.sql}`,
+    args: [messageId, ...scope.args]
+  });
+  return result.rows[0]?.status ?? null;
+}
+async function getUnacknowledgedMessages(targetAgent, sessionScope) {
+  const client = getClient();
+  const scope = strictSessionScopeFilter(sessionScope);
+  const result = await client.execute({
+    sql: `SELECT * FROM messages
+          WHERE target_agent = ? AND status IN ('pending', 'delivered', 'read')${scope.sql}
+          ORDER BY id`,
+    args: [targetAgent, ...scope.args]
+  });
+  return result.rows.map((row) => rowToMessage(row));
+}
+async function getReadMessages(targetAgent, sessionScope) {
+  const client = getClient();
+  const scope = strictSessionScopeFilter(sessionScope);
+  const result = await client.execute({
+    sql: `SELECT * FROM messages
+          WHERE target_agent = ? AND status = 'read'${scope.sql}
+          ORDER BY id`,
+    args: [targetAgent, ...scope.args]
+  });
+  return result.rows.map((row) => rowToMessage(row));
+}
+async function markFailed(messageId, reason, sessionScope) {
+  const client = getClient();
+  const scope = strictSessionScopeFilter(sessionScope);
+  await client.execute({
+    sql: `UPDATE messages SET status = 'failed', failed_at = ?, failure_reason = ?
+          WHERE id = ?${scope.sql}`,
+    args: [(/* @__PURE__ */ new Date()).toISOString(), reason, messageId, ...scope.args]
+  });
+}
+async function getFailedMessages(sessionScope) {
+  const client = getClient();
+  const scope = strictSessionScopeFilter(sessionScope);
+  const result = await client.execute({
+    sql: `SELECT * FROM messages WHERE status = 'failed'${scope.sql} ORDER BY created_at DESC`,
+    args: [...scope.args]
+  });
+  return result.rows.map((row) => rowToMessage(row));
+}
+async function retryPendingMessages(sessionScope) {
+  const client = getClient();
+  const scope = strictSessionScopeFilter(sessionScope);
+  const result = await client.execute({
+    sql: `SELECT * FROM messages
+          WHERE status = 'pending' AND retry_count < ?${scope.sql}
+          ORDER BY id`,
+    args: [MAX_RETRIES, ...scope.args]
+  });
+  let delivered = 0;
+  for (const row of result.rows) {
+    const msg = rowToMessage(row);
+    try {
+      const success = await deliverLocalMessage(msg.id);
+      if (success) delivered++;
+    } catch {
+    }
+  }
+  return delivered;
+}
+async function sendTypedMessage(envelope, targetAgent, opts) {
+  return sendMessage({
+    fromAgent: envelope.from,
+    targetAgent,
+    targetProject: opts?.targetProject,
+    targetDevice: opts?.targetDevice,
+    content: serializeMessage(envelope),
+    priority: opts?.priority,
+    sessionScope: opts?.sessionScope
+  });
+}
+function parseIncomingMessage(content) {
+  return parseMessage(content);
+}
+
+export {
+  countUnreadMessages,
+  sendMessage,
+  setWsClientSend,
+  deliverLocalMessage,
+  getPendingMessages,
+  markRead,
+  markAcknowledged,
+  markProcessed,
+  getMessageStatus,
+  getUnacknowledgedMessages,
+  getReadMessages,
+  markFailed,
+  getFailedMessages,
+  retryPendingMessages,
+  sendTypedMessage,
+  parseIncomingMessage
+};

package/dist/chunk-6MZZREZY.js

@@ -0,0 +1,199 @@
+import {
+  resolveAnthropicAuth
+} from "./chunk-EJIF4FNT.js";
+
+// src/lib/retrieval-health.ts
+async function getRetrievalHealth() {
+  let embedDaemon = "unavailable";
+  try {
+    const { isDaemonAlive } = await import("./mcp-health-WDOB6XUB.js");
+    const { alive } = isDaemonAlive();
+    if (alive) {
+      try {
+        const { pingDaemon } = await import("./lib/exe-daemon-client.js");
+        const health = await pingDaemon();
+        if (health) {
+          const worker = health.embedWorker;
+          const embeddingField = health.embedding;
+          if (worker?.disabledByDesign || embeddingField === "disabled") {
+            embedDaemon = "disabled";
+          } else if (worker) {
+            embedDaemon = worker.forked && worker.ready && worker.pid != null ? "running" : "stopped";
+          } else if (embeddingField === "ok") {
+            embedDaemon = "running";
+          } else {
+            embedDaemon = "stopped";
+          }
+        } else {
+          embedDaemon = "stopped";
+        }
+      } catch {
+        embedDaemon = "stopped";
+      }
+    } else {
+      embedDaemon = "unavailable";
+    }
+  } catch {
+    embedDaemon = "unavailable";
+  }
+  let configuredSearchMode = "hybrid";
+  let selfQueryRouterEnabled = true;
+  try {
+    const { loadConfigSync } = await import("./lib/config.js");
+    const cfg = loadConfigSync();
+    configuredSearchMode = cfg.searchMode ?? "hybrid";
+    selfQueryRouterEnabled = cfg.selfQueryRouter ?? true;
+  } catch {
+  }
+  let actualSearchMode;
+  if (configuredSearchMode === "fts") {
+    actualSearchMode = "fts+graph";
+  } else if (embedDaemon === "running") {
+    actualSearchMode = "hybrid (vector+fts+graph)";
+  } else {
+    actualSearchMode = "fts+graph (degraded from hybrid)";
+  }
+  let queryRouter;
+  if (!selfQueryRouterEnabled) {
+    queryRouter = "disabled";
+  } else if (embedDaemon === "running" || embedDaemon === "disabled") {
+    queryRouter = resolveAnthropicAuth() ? "active" : "fallback";
+  } else {
+    queryRouter = "fallback";
+  }
+  let totalMemories = 0;
+  let memoriesWithVectors = 0;
+  let entities = 0;
+  let relationships = 0;
+  try {
+    const { getClient } = await import("./lib/database.js");
+    const client = getClient();
+    const [totalRes, vectorRes] = await Promise.all([
+      client.execute("SELECT COUNT(*) as cnt FROM memories WHERE status IS NULL OR status != 'deleted'"),
+      client.execute("SELECT COUNT(*) as cnt FROM memories WHERE vector IS NOT NULL AND (status IS NULL OR status != 'deleted')")
+    ]);
+    totalMemories = Number(totalRes.rows[0]?.cnt ?? 0);
+    memoriesWithVectors = Number(vectorRes.rows[0]?.cnt ?? 0);
+    try {
+      const { getGraphStats } = await import("./graph-query-AP5R6ZHO.js");
+      const stats = await getGraphStats(client);
+      entities = stats.entities;
+      relationships = stats.relationships;
+    } catch {
+    }
+  } catch {
+  }
+  const staleCount = totalMemories - memoriesWithVectors;
+  const coveragePct = totalMemories > 0 ? Math.round(memoriesWithVectors / totalMemories * 100) : null;
+  let dbRestore = { hasEvents: false, count: 0, last: null, quarantineFiles: 0 };
+  try {
+    const { getDbRestoreHealth } = await import("./db-restore-events-GNZS42YO.js");
+    dbRestore = getDbRestoreHealth();
+  } catch {
+  }
+  const summary = {
+    embedDaemon,
+    searchMode: {
+      configured: configuredSearchMode,
+      actual: actualSearchMode
+    },
+    queryRouter,
+    vectorBackfill: {
+      totalMemories,
+      memoriesWithVectors,
+      staleCount,
+      coveragePct
+    },
+    graph: {
+      entities,
+      relationships
+    },
+    dbRestore
+  };
+  return {
+    ...summary,
+    degradations: computeDegradations(summary)
+  };
+}
+function computeDegradations(h) {
+  const out = [];
+  const isRuntimeDowngrade = h.searchMode.actual.includes("degraded");
+  if (isRuntimeDowngrade) {
+    out.push({
+      code: "retrieval_downgraded",
+      severity: "warn",
+      message: `Retrieval running as "${h.searchMode.actual}" (configured: "${h.searchMode.configured}")`,
+      remediation: h.embedDaemon === "disabled" ? "Embeddings are disabled. Enable them in settings if you want vector retrieval." : "Embed daemon is not running. Start the daemon / embed worker to restore hybrid retrieval."
+    });
+  } else if (h.searchMode.configured === "fts") {
+    out.push({
+      code: "embeddings_off",
+      severity: "info",
+      message: "Search mode is FTS-only by configuration (keyword + graph; no vector retrieval)",
+      remediation: 'Switch searchMode to "hybrid" in settings to enable vector retrieval.'
+    });
+  }
+  if (h.queryRouter === "fallback") {
+    out.push({
+      code: "query_router_fallback",
+      severity: "info",
+      message: "Self-query-router using rule-based fallback (LLM routing is an optional enrichment; keyword + graph retrieval unaffected)",
+      remediation: "To enable LLM-based query routing, provide an Anthropic credential: set ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN if you use Claude Code / OpenCode / a subscription-OAuth host."
+    });
+  }
+  if (h.dbRestore.hasEvents) {
+    const last = h.dbRestore.last;
+    if (last && (last.kind === "restore-failed" || last.kind === "zeroed-no-wal")) {
+      out.push({
+        code: "db_corruption_unrecovered",
+        severity: "critical",
+        message: `DB corruption could not be auto-recovered: ${last.detail ?? last.kind} (${last.at})`,
+        remediation: "Restore from a known-good backup (`exe-os cloud reupload` or restore a backup); preserved corrupt DB is in ~/.exe-os/."
+      });
+    } else if (last && (last.kind === "auto-restore" || last.kind === "wal-recovery")) {
+      out.push({
+        code: "db_auto_restored",
+        severity: "warn",
+        message: last.kind === "auto-restore" ? `DB was auto-restored from backup${last.restoredFrom ? ` (${last.restoredFrom})` : ""}${typeof last.hoursLost === "number" ? `, ~${last.hoursLost}h data-loss window` : ""} at ${last.at}` : `DB was reconstructed from WAL after a 0-byte corruption at ${last.at}`,
+        remediation: "Recent memories may be missing. Run a cloud sync to reconcile and verify recent data."
+      });
+    } else if (h.dbRestore.quarantineFiles > 0) {
+      out.push({
+        code: "db_corruption_quarantine",
+        severity: "warn",
+        message: `${h.dbRestore.quarantineFiles} quarantined corrupt DB file(s) present in ~/.exe-os/ (prior corruption event)`,
+        remediation: "Verify data integrity; remove quarantined .corrupt-*/.zeroed-* files once you've confirmed no data is needed."
+      });
+    }
+  }
+  return out;
+}
+var SEVERITY_ICON = {
+  info: "\u2139\uFE0F",
+  // ℹ️
+  warn: "\u{1F7E0}",
+  // 🟠
+  critical: "\u{1F534}"
+  // 🔴
+};
+function formatDegradations(degradations, heading = "Degradations") {
+  const lines = [];
+  lines.push(`### ${heading}`);
+  if (degradations.length === 0) {
+    lines.push("\u{1F7E2} None \u2014 all retrieval and storage subsystems nominal.");
+    return lines.join("\n");
+  }
+  const order = { critical: 0, warn: 1, info: 2 };
+  const sorted = [...degradations].sort((a, b) => order[a.severity] - order[b.severity]);
+  for (const d of sorted) {
+    lines.push(`${SEVERITY_ICON[d.severity]} ${d.message}`);
+    if (d.remediation) lines.push(`   \u2192 ${d.remediation}`);
+  }
+  return lines.join("\n");
+}
+
+export {
+  getRetrievalHealth,
+  computeDegradations,
+  formatDegradations
+};