@wrongstack/webui-server 0.308.0 → 0.308.1

package/dist/index.js

@@ -7376,11 +7376,11 @@ async function handleGitDiff(ws, projectRoot, path39) {
   try {
     const git = makeGit(cwd);
     const { readFile: readFile13 } = await import("node:fs/promises");
-    const { join: join18 } = await import("node:path");
+    const { join: join19 } = await import("node:path");
     const oldText = await git(["show", `HEAD:${path39}`]);
     let newText = "";
     try {
-      const abs = cwd ? join18(cwd, path39) : path39;
+      const abs = cwd ? join19(cwd, path39) : path39;
       const buf = await readFile13(abs);
       if (buf.includes(0)) {
         reply2({ oldText: "", newText: "", binary: true });
@@ -10411,6 +10411,7 @@ function strictDecodeParam(segment, res) {
 }
 
 // src/server/http-server/vector-memory-handlers.ts
+import { getSageSurface } from "@wrongstack/sage";
 import { sanitizeApiError as sanitizeApiError2 } from "@wrongstack/core/security";
 function snapshotVectorMemory(store, opts = {}) {
   const stats = store.stats();
@@ -10420,6 +10421,9 @@ function snapshotVectorMemory(store, opts = {}) {
     stats
   };
 }
+function snapshotVectorMemoryCache(store) {
+  return store.cacheStats();
+}
 async function handleVectorMemoryStatus(res, getStore, opts = {}) {
   const store = getStore();
   if (!store) {
@@ -10439,7 +10443,8 @@ async function handleVectorMemoryStatus(res, getStore, opts = {}) {
       dimensions: snap.stats.dimensions,
       entries: snap.stats.entries,
       vectors: snap.stats.vectors,
-      providers: snap.stats.providers
+      providers: snap.stats.providers,
+      cache: snapshotVectorMemoryCache(store)
     };
     res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
     res.end(JSON.stringify(body));
@@ -10459,7 +10464,29 @@ function parseSearchParams(url) {
   const limit = Math.min(50, Math.max(1, Number.isFinite(rawLimit) ? rawLimit : 10));
   const rawThreshold = url.searchParams.get("threshold");
   const threshold = rawThreshold !== null && rawThreshold !== "" ? Math.max(0, Math.min(1, Number.parseFloat(rawThreshold))) : void 0;
-  return { query, limit, threshold: Number.isFinite(threshold) ? threshold : void 0 };
+  const similarity = url.searchParams.get("similarity") === "1";
+  return { query, limit, threshold: Number.isFinite(threshold) ? threshold : void 0, similarity };
+}
+function cosineMatrix(vectors) {
+  const n = vectors.length;
+  const out = new Array(n);
+  for (let i = 0; i < n; i++) {
+    out[i] = new Array(n).fill(0);
+  }
+  for (let i = 0; i < n; i++) {
+    out[i][i] = 1;
+    for (let j = i + 1; j < n; j++) {
+      const a = vectors[i];
+      const b = vectors[j];
+      let dot = 0;
+      const len = Math.min(a.length, b.length);
+      for (let k = 0; k < len; k++) dot += (a[k] ?? 0) * (b[k] ?? 0);
+      const score = Math.max(0, Math.min(1, dot));
+      out[i][j] = score;
+      out[j][i] = score;
+    }
+  }
+  return out;
 }
 async function handleVectorMemorySearch(res, url, getStore) {
   const store = getStore();
@@ -10468,7 +10495,7 @@ async function handleVectorMemorySearch(res, url, getStore) {
     res.end(JSON.stringify({ error: "Vector memory not enabled in this host" }));
     return;
   }
-  const { query, limit, threshold } = parseSearchParams(url);
+  const { query, limit, threshold, similarity } = parseSearchParams(url);
   if (query.trim().length === 0) {
     res.writeHead(400, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "Missing required query parameter `q`" }));
@@ -10477,7 +10504,8 @@ async function handleVectorMemorySearch(res, url, getStore) {
   try {
     const hits = await store.search(query, {
       limit,
-      ...threshold !== void 0 ? { threshold } : {}
+      ...threshold !== void 0 ? { threshold } : {},
+      includeVectors: similarity
     });
     const body = {
       hits: hits.map((h) => ({
@@ -10489,6 +10517,12 @@ async function handleVectorMemorySearch(res, url, getStore) {
       })),
       count: hits.length
     };
+    if (similarity && hits.length > 1) {
+      const vecs = hits.map((h) => h.vector).filter((v) => v !== void 0);
+      if (vecs.length === hits.length) {
+        body.similarity = cosineMatrix(vecs);
+      }
+    }
     res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
     res.end(JSON.stringify(body));
   } catch (error2) {
@@ -10573,7 +10607,7 @@ async function handleVectorMemoryForget(res, url, getStore) {
   const id = match ? strictDecodeParam(decodeSessionId(match[1]), res) : null;
   if (id === null) return;
   try {
-    const removed = store.forget(id);
+    const removed = await store.forget(id);
     res.writeHead(200, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ removed }));
   } catch (error2) {
@@ -10586,6 +10620,86 @@ async function handleVectorMemoryForget(res, url, getStore) {
     );
   }
 }
+function parseMemorySearchParams(url) {
+  const query = url.searchParams.get("q") ?? "";
+  const rawLimit = Number.parseInt(url.searchParams.get("limit") ?? "20", 10);
+  const limit = Math.min(50, Math.max(1, Number.isFinite(rawLimit) ? rawLimit : 20));
+  const explain = url.searchParams.get("explain") === "1";
+  return { query, limit, explain };
+}
+async function handleMemorySearch(res, url, getStore) {
+  const store = getStore();
+  if (!store) {
+    res.writeHead(503, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Memory store not enabled in this host" }));
+    return;
+  }
+  const { query, limit, explain } = parseMemorySearchParams(url);
+  if (query.trim().length === 0) {
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Missing required query parameter `q`" }));
+    return;
+  }
+  const Sage = getSageSurface(store);
+  if (!Sage) {
+    res.writeHead(503, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        error: "Memory search requires the SAGE surface (this host does not expose it)."
+      })
+    );
+    return;
+  }
+  try {
+    let payload;
+    if (explain && typeof Sage.searchSageWithBreakdown === "function") {
+      const hits = await Sage.searchSageWithBreakdown(query, { limit });
+      payload = {
+        count: hits.length,
+        channel: "breakdown",
+        hits: hits.map((h) => ({
+          id: h.memory.id,
+          text: h.memory.text,
+          kind: h.memory.kind,
+          status: h.memory.status,
+          tags: h.memory.tags ?? [],
+          lexicalScore: h.lexicalScore,
+          vectorScore: h.vectorScore,
+          finalScore: h.finalScore,
+          source: h.source
+        }))
+      };
+    } else {
+      const rows = await Sage.searchSage(query, { limit });
+      const total = rows.length;
+      payload = {
+        count: total,
+        channel: "lexical",
+        hits: rows.map((memory, index) => ({
+          id: memory.id,
+          text: memory.text,
+          kind: memory.kind,
+          status: memory.status,
+          tags: memory.tags ?? [],
+          lexicalScore: total <= 1 ? 1 : 1 - index / Math.max(1, total - 1),
+          vectorScore: null,
+          finalScore: total <= 1 ? 1 : 1 - index / Math.max(1, total - 1),
+          source: "lexical"
+        }))
+      };
+    }
+    res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+    res.end(JSON.stringify(payload));
+  } catch (error2) {
+    res.writeHead(500, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        error: "Memory search failed",
+        detail: sanitizeApiError2(error2)
+      })
+    );
+  }
+}
 
 // src/server/http-server/api-router.ts
 async function handleApiRoutes(req, res, url, deps2, requireAccessToken, accessTokenOk, getTechStackRuntime) {
@@ -11036,6 +11150,15 @@ async function handleApiRoutes(req, res, url, deps2, requireAccessToken, accessT
     await handleVectorMemoryStore(res, req, () => deps2.getVectorMemoryStore?.());
     return true;
   }
+  if (url.pathname === "/api/memory/search" && req.method === "GET") {
+    if (requireAccessToken && !accessTokenOk) {
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Unauthorized" }));
+      return true;
+    }
+    await handleMemorySearch(res, url, () => deps2.getMemoryStore?.());
+    return true;
+  }
   if (url.pathname === "/api/deadcode/action-plan" && req.method === "POST") {
     await handleDeadCodeActionPlan(
       res,
@@ -11200,12 +11323,15 @@ function createHttpServer(opts) {
         distDir,
         url,
         opts,
-        port,
+        // Live port from the socket: the bind may have advanced past an
+        // EADDRINUSE (listenWithRetry) after this server was constructed,
+        // and the CSP must advertise the port actually serving this request.
+        res.socket?.localPort ?? port,
         shouldSetAuthCookie
       );
     } catch (err) {
       if (err.code === "ENOENT") {
-        await handleSpaFallback(res, distDir, opts, port);
+        await handleSpaFallback(res, distDir, opts, res.socket?.localPort ?? port);
       } else {
         console.error({ url: req.url, err });
         res.writeHead(500);
@@ -14136,13 +14262,13 @@ async function handleMcpRoute(ws, msg, handlers) {
 }
 
 // src/server/memory-handlers.ts
-import { getSageSurface } from "@wrongstack/sage";
+import { getSageSurface as getSageSurface2 } from "@wrongstack/sage";
 function requiresSage(command) {
   return `\`${command}\` requires the SAGE backend (Sage.enabled).`;
 }
 async function handleMemoryList(ws, memoryStore) {
   try {
-    const Sage = getSageSurface(memoryStore);
+    const Sage = getSageSurface2(memoryStore);
     if (Sage) {
       const [stats, memories] = await Promise.all([Sage.stats(), Sage.listSage()]);
       const text3 = memories.length === 0 ? "\u{1F9E0} SAGE is empty." : formatSageText(stats, memories);
@@ -14177,7 +14303,7 @@ function formatSageText(stats, memories) {
   return lines.join("\n");
 }
 async function handleSageList(ws, memoryStore) {
-  const Sage = getSageSurface(memoryStore);
+  const Sage = getSageSurface2(memoryStore);
   if (!Sage) {
     send(ws, {
       type: "memory.sage.list",
@@ -14193,7 +14319,7 @@ async function handleSageList(ws, memoryStore) {
   }
 }
 async function handleSageListPage(ws, msg, memoryStore) {
-  const Sage = getSageSurface(memoryStore);
+  const Sage = getSageSurface2(memoryStore);
   if (!Sage) {
     send(ws, {
       type: "memory.sage.listPage",
@@ -14243,8 +14369,50 @@ async function handleSageListPage(ws, msg, memoryStore) {
     send(ws, { type: "memory.sage.listPage", payload: { error: errMessage(err) } });
   }
 }
+async function handleSageSearchBreakdown(ws, msg, memoryStore) {
+  const Sage = getSageSurface2(memoryStore);
+  if (!Sage) {
+    send(ws, {
+      type: "memory.sage.searchBreakdown",
+      payload: { error: requiresSage("memory.sage.searchBreakdown") }
+    });
+    return;
+  }
+  try {
+    const payload = msg.payload ?? {};
+    const query = typeof payload["query"] === "string" ? payload["query"] : "";
+    if (query.trim().length === 0) {
+      send(ws, {
+        type: "memory.sage.searchBreakdown",
+        payload: { error: "Missing required field `query`" }
+      });
+      return;
+    }
+    const limit = typeof payload["limit"] === "number" ? payload["limit"] : 20;
+    const includeStale = payload["includeStale"] === true;
+    const includeStatuses = includeStale ? ["active", "stale"] : ["active"];
+    const options = { limit, includeStatuses };
+    if (typeof Sage.searchSageWithBreakdown === "function") {
+      const hits2 = await Sage.searchSageWithBreakdown(query, options);
+      send(ws, { type: "memory.sage.searchBreakdown", payload: { hits: hits2, source: "breakdown" } });
+      return;
+    }
+    const rows = await Sage.searchSage(query, options);
+    const total = rows.length;
+    const hits = rows.map((memory, index) => ({
+      memory,
+      vectorScore: null,
+      lexicalScore: total <= 1 ? 1 : 1 - index / Math.max(1, total - 1),
+      finalScore: total <= 1 ? 1 : 1 - index / Math.max(1, total - 1),
+      source: "lexical"
+    }));
+    send(ws, { type: "memory.sage.searchBreakdown", payload: { hits, source: "lexical" } });
+  } catch (err) {
+    send(ws, { type: "memory.sage.searchBreakdown", payload: { error: errMessage(err) } });
+  }
+}
 async function handleSageGet(ws, msg, memoryStore) {
-  const Sage = getSageSurface(memoryStore);
+  const Sage = getSageSurface2(memoryStore);
   if (!Sage) {
     send(ws, {
       type: "memory.sage.get",
@@ -14269,7 +14437,7 @@ async function handleSageGet(ws, msg, memoryStore) {
   }
 }
 async function handleSageGraph(ws, msg, memoryStore) {
-  const Sage = getSageSurface(memoryStore);
+  const Sage = getSageSurface2(memoryStore);
   if (!Sage?.graphFor) {
     send(ws, {
       type: "memory.sage.graph",
@@ -14303,7 +14471,7 @@ async function handleSageGraph(ws, msg, memoryStore) {
   }
 }
 async function handleSageUpdate(ws, msg, memoryStore) {
-  const Sage = getSageSurface(memoryStore);
+  const Sage = getSageSurface2(memoryStore);
   if (!Sage) {
     send(ws, {
       type: "memory.sage.update",
@@ -14331,7 +14499,7 @@ async function handleSageUpdate(ws, msg, memoryStore) {
   }
 }
 async function handleSageRemember(ws, msg, memoryStore) {
-  const Sage = getSageSurface(memoryStore);
+  const Sage = getSageSurface2(memoryStore);
   if (!Sage) {
     send(ws, {
       type: "memory.sage.remember",
@@ -14365,7 +14533,7 @@ async function handleSageRemember(ws, msg, memoryStore) {
   }
 }
 async function handleSageDelete(ws, msg, memoryStore) {
-  const Sage = getSageSurface(memoryStore);
+  const Sage = getSageSurface2(memoryStore);
   if (!Sage) {
     send(ws, {
       type: "memory.sage.delete",
@@ -14398,7 +14566,7 @@ async function handleSageDelete(ws, msg, memoryStore) {
   }
 }
 async function handleSageRecover(ws, msg, memoryStore) {
-  const Sage = getSageSurface(memoryStore);
+  const Sage = getSageSurface2(memoryStore);
   if (!Sage?.recoverSage) {
     send(ws, {
       type: "memory.sage.recover",
@@ -14442,7 +14610,7 @@ async function handleSageRecover(ws, msg, memoryStore) {
   }
 }
 async function handleSageListCandidates(ws, msg, memoryStore) {
-  const Sage = getSageSurface(memoryStore);
+  const Sage = getSageSurface2(memoryStore);
   if (!Sage) {
     send(ws, {
       type: "memory.sage.listCandidates",
@@ -14470,7 +14638,7 @@ async function handleSageListCandidates(ws, msg, memoryStore) {
   }
 }
 async function handleSageCandidateResolve(ws, msg, memoryStore) {
-  const Sage = getSageSurface(memoryStore);
+  const Sage = getSageSurface2(memoryStore);
   if (!Sage) {
     send(ws, {
       type: "memory.sage.candidateResolve",
@@ -14527,7 +14695,7 @@ async function handleSageCandidateResolve(ws, msg, memoryStore) {
   }
 }
 async function handleSageBackfillRecoverable(ws, msg, memoryStore) {
-  const Sage = getSageSurface(memoryStore);
+  const Sage = getSageSurface2(memoryStore);
   if (!Sage?.backfillRecoverable) {
     send(ws, {
       type: "memory.sage.backfillRecoverable",
@@ -14567,7 +14735,7 @@ async function handleSageBackfillRecoverable(ws, msg, memoryStore) {
   }
 }
 async function handleSageForFile(ws, msg, memoryStore) {
-  const Sage = getSageSurface(memoryStore);
+  const Sage = getSageSurface2(memoryStore);
   if (!Sage?.findMemoriesForFile) {
     send(ws, {
       type: "memory.sage.forFile",
@@ -14659,6 +14827,9 @@ async function handleMemoryRoute(ctx, ws, message) {
     case "memory.sage.forFile":
       await handleSageForFile(ws, message, store);
       return true;
+    case "memory.sage.searchBreakdown":
+      await handleSageSearchBreakdown(ws, message, store);
+      return true;
     default:
       return false;
   }
@@ -15049,23 +15220,31 @@ var SURFACE_DEFAULT_PORTS = {
   webui: { http: 3456 },
   simpleui: { http: 3466 }
 };
+var MAX_TCP_PORT = 65535;
 function surfaceLabel(surface) {
   return surface === "webui" ? "WebUI" : "SimpleUI";
 }
+function isStrictPort() {
+  const value = process.env["WEBUI_STRICT_PORT"];
+  return value === "1" || value === "true";
+}
 function getSurfaceDefaultPorts(surface) {
   return { http: SURFACE_DEFAULT_PORTS[surface].http };
 }
 function isPortFree(host, port) {
+  return probePort(host, port).then((err) => err === null);
+}
+function probePort(host, port) {
   return new Promise((resolve20) => {
     const srv = net2.createServer();
-    srv.once("error", () => resolve20(false));
+    srv.once("error", (err) => resolve20(err));
     srv.once("listening", () => {
-      srv.close(() => resolve20(true));
+      srv.close(() => resolve20(null));
     });
     try {
       srv.listen(port, host);
-    } catch {
-      resolve20(false);
+    } catch (err) {
+      resolve20(err);
     }
   });
 }
@@ -15074,7 +15253,7 @@ async function findFreePort(host, startPort, opts = {}) {
   const maxTries = opts.maxTries ?? 200;
   let port = startPort;
   for (let i = 0; i < maxTries; i++) {
-    if (port > 65535) port = 1024 + port % 5e4;
+    if (port > MAX_TCP_PORT) port = 1024 + port % 5e4;
     if (!exclude.has(port) && await isPortFree(host, port)) {
       return port;
     }
@@ -15085,6 +15264,50 @@ async function findFreePort(host, startPort, opts = {}) {
     field: "port"
   });
 }
+function listenWithRetry(server, host, port, opts = {}) {
+  const maxTries = opts.maxTries ?? 10;
+  return new Promise((resolve20, reject) => {
+    const canAdvance = (candidate) => candidate < MAX_TCP_PORT;
+    const probeable = (candidate) => Number.isInteger(candidate) && candidate >= 0 && candidate <= MAX_TCP_PORT;
+    const attempt = (candidate, remaining) => {
+      void (async () => {
+        if (probeable(candidate)) {
+          const probeErr = await probePort(host, candidate);
+          if (probeErr !== null) {
+            if (probeErr.code === "EADDRINUSE" && remaining > 1 && canAdvance(candidate)) {
+              attempt(candidate + 1, remaining - 1);
+              return;
+            }
+            reject(probeErr);
+            return;
+          }
+        }
+        const onError = (err) => {
+          server.off("listening", onListening);
+          server.off("error", onError);
+          if (err.code === "EADDRINUSE" && remaining > 1 && canAdvance(candidate)) {
+            attempt(candidate + 1, remaining - 1);
+            return;
+          }
+          reject(err);
+        };
+        const onListening = () => {
+          server.off("error", onError);
+          const address = server.address();
+          resolve20(address && typeof address === "object" ? address.port : candidate);
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        try {
+          server.listen(candidate, host);
+        } catch (err) {
+          onError(err);
+        }
+      })();
+    };
+    attempt(port, maxTries);
+  });
+}
 
 // src/server/frontend-static-serve.ts
 import { spawn as spawn2 } from "node:child_process";
@@ -15218,7 +15441,10 @@ async function startStaticServe(opts, deps2 = {}) {
     ...opts.vectorMemoryModelCacheDir ? { vectorMemoryModelCacheDir: opts.vectorMemoryModelCacheDir } : {}
   });
   if (!opts.deferListen) {
-    server.listen(opts.httpPort, opts.host);
+    const boundPort = await listenWithRetry(server, opts.host, opts.httpPort, {
+      maxTries: opts.strictPort ? 1 : 10
+    });
+    return { server, port: boundPort };
   }
   return { server, port: opts.httpPort };
 }
@@ -15351,7 +15577,7 @@ function announceWebuiReady(p) {
     token: p.wsToken,
     publicUrl: p.publicUrl
   });
-  p.server.on("listening", () => {
+  const announce = () => {
     const extraUrls = formatExternalAccessUrls({
       bindHost: p.host,
       port: p.httpPort,
@@ -15368,7 +15594,12 @@ ${extraUrls.join("\n")}
 ${extraBlock}`
     );
     if (p.open) launch(openUrl);
-  });
+  };
+  if (p.server.listening) {
+    announce();
+    return;
+  }
+  p.server.on("listening", announce);
 }
 var DEFAULT_CHILD_CLEANUP_TIMEOUT_MS = 1e4;
 async function runBounded(work, timeoutMs, label, debug) {
@@ -18459,6 +18690,7 @@ var CLIENT_KNOWLEDGE_MESSAGE_TYPES = [
   "memory.sage.listPage",
   "memory.sage.recover",
   "memory.sage.remember",
+  "memory.sage.searchBreakdown",
   "memory.sage.update"
 ];
 var CLIENT_EXTENSION_MESSAGE_TYPES = [
@@ -18746,6 +18978,7 @@ var SERVER_KNOWLEDGE_MESSAGE_TYPES = [
   "memory.sage.listPage",
   "memory.sage.recover",
   "memory.sage.remember",
+  "memory.sage.searchBreakdown",
   "memory.sage.update"
 ];
 var SERVER_EXTENSION_MESSAGE_TYPES = [
@@ -19623,7 +19856,12 @@ function createSessionHandlers(ctx) {
       sessionScopedPath(sessionsDirectory(), next.id, ".tasks.json")
     );
     ctx.tokenCounter.reset?.();
-    if (usage) ctx.tokenCounter.account(usage, currentConfig().model, ctx.context.provider.id);
+    if (usage) {
+      ctx.tokenCounter.account(usage, currentConfig().model, ctx.context.provider.id);
+      if (typeof usage.input === "number" && usage.input > 0) {
+        ctx.context.lastRequestTokens = usage.input;
+      }
+    }
     ctx.setSessionStartedAt?.(Date.now());
     await ctx.onSessionSwapped?.(next.id);
   };
@@ -24434,6 +24672,11 @@ import {
   wstackGlobalRoot as wstackGlobalRoot4
 } from "@wrongstack/core/utils";
 import { ensureSessionShell } from "@wrongstack/tools";
+import {
+  TransformersEmbeddingProvider,
+  VectorMemoryStore,
+  startFirstBootSageSync
+} from "@wrongstack/vector-memory";
 
 // src/server/backend-services.ts
 import { join as join15 } from "node:path";
@@ -27386,7 +27629,7 @@ async function resolvePorts(opts) {
   const publicUrl = opts.publicUrl ?? process.env["WEBUI_PUBLIC_URL"];
   const publicWsUrl = opts.publicWsUrl ?? process.env["WEBUI_PUBLIC_WS_URL"];
   const requireToken = opts.requireToken ?? envFlag("WEBUI_REQUIRE_TOKEN");
-  const strictPort = process.env["WEBUI_STRICT_PORT"] === "1" || process.env["WEBUI_STRICT_PORT"] === "true";
+  const strictPort = isStrictPort();
   let httpPort = requestedHttpPort;
   if (!strictPort) {
     httpPort = await findFreePort(wsHost, requestedHttpPort);
@@ -27605,7 +27848,7 @@ function registerShutdown(deps2) {
 
 // src/server/start-webui-companion.ts
 import * as http2 from "node:http";
-function setupCompanionServer(httpServer, wsHost, httpPort) {
+async function setupCompanionServer(httpServer, wsHost, httpPort) {
   const companion = wsHost === "127.0.0.1" ? "::1" : wsHost === "0.0.0.0" || wsHost === void 0 ? "::" : wsHost === "::" || wsHost === "[::]" ? "0.0.0.0" : null;
   if (!companion) return null;
   const companionLabel = companion.includes(":") ? `[${companion}]` : companion;
@@ -27616,16 +27859,23 @@ function setupCompanionServer(httpServer, wsHost, httpPort) {
     (req, socket, head2) => httpServer.emit("upgrade", req, socket, head2)
   );
   companionServer.on("error", (err) => {
-    const expected = err.code === "EAFNOSUPPORT" || err.code === "EADDRNOTAVAIL" || err.code === "EADDRINUSE";
+    const expected = err.code === "EAFNOSUPPORT" || err.code === "EADDRNOTAVAIL";
     if (!expected) {
       console.warn(
         `[WebUI] companion listener on ${companionLabel} failed (${err.code ?? "unknown"}): ${err.message}. The primary address is unaffected.`
       );
     }
   });
-  companionServer.listen(httpPort, companion, () => {
-    console.log(`[WebUI] HTTP server running on http://${companionLabel}:${httpPort}`);
-  });
+  try {
+    await listenWithRetry(companionServer, companion, httpPort, { maxTries: 1 });
+  } catch (err) {
+    const code = err?.code ?? "unknown";
+    console.warn(
+      `[WebUI] companion listener on ${companionLabel} not started (${code}): ${err?.message ?? err}. The primary address is unaffected.`
+    );
+    return null;
+  }
+  console.log(`[WebUI] HTTP server running on http://${companionLabel}:${httpPort}`);
   return companionServer;
 }
 
@@ -27820,6 +28070,7 @@ function setupWebuiShutdown(options) {
       await options.memoryStore.dispose().catch(
         (err) => options.logger.warn(`sage connection disposal failed: ${toErrorMessage16(err)}`)
       );
+      options.vectorMemoryStore?.close();
       await unregisterInstance(process.pid, path37.dirname(options.globalConfigPath));
     }
   });
@@ -27884,7 +28135,8 @@ function createStandaloneTodosCheckpointLifecycle(input) {
 async function startWebUI(opts = {}) {
   ensureSessionShell();
   const ports = await resolvePorts(opts);
-  const { wsHost, httpPort, publicUrl, publicWsUrl, requireToken } = ports;
+  const { wsHost, publicUrl, publicWsUrl, requireToken } = ports;
+  let httpPort = ports.httpPort;
   console.log("[WebUI] Starting backend services...");
   const boot = await bootConfig();
   const { config: baseConfig, globalConfigPath, wpaths, logger } = boot;
@@ -27912,6 +28164,27 @@ async function startWebUI(opts = {}) {
     );
   }
   const needsProvider = !config.provider || !config.model;
+  let vectorMemoryStore;
+  const vectorMemoryModelCacheDir = path38.join(
+    projectRoot,
+    ".wrongstack",
+    "cache",
+    "transformers-models"
+  );
+  try {
+    vectorMemoryStore = new VectorMemoryStore({
+      provider: new TransformersEmbeddingProvider({
+        cacheDir: vectorMemoryModelCacheDir
+      }),
+      projectRoot
+    });
+  } catch (error2) {
+    const message = error2 instanceof Error ? error2.message : String(error2);
+    logger.warn(
+      `vector memory store disabled: ${message} \u2014 standalone WebUI will run on the SAGE-only surface.`
+    );
+    vectorMemoryStore = void 0;
+  }
   const preContext = await createPreContextServices({
     config,
     wpaths,
@@ -27959,6 +28232,13 @@ async function startWebUI(opts = {}) {
   let sessionStartedAt = preContext.sessionStartedAt;
   let modeId = preContext.modeId;
   const needsSetup = preContext.needsSetup;
+  if (vectorMemoryStore) {
+    void startFirstBootSageSync({
+      store: vectorMemoryStore,
+      memoryStore,
+      logger
+    });
+  }
   const prefSnapshot2 = () => prefSnapshot(context.meta);
   const persistPrefsToConfig2 = async (payload) => persistPrefsToConfig(prefHelperDeps, configWriteLock, payload);
   const trustBoundary = opts.trustBoundary ?? createCompatibilityTrustBoundary3({ policyId: "webui-trusted-host-compat-v1" });
@@ -28079,7 +28359,12 @@ async function startWebUI(opts = {}) {
       events,
       permissionPolicy
     }),
-    distDir: opts.distDir
+    distDir: opts.distDir,
+    // Vector memory store — mirrors the CLI host. When `vectorMemoryStore`
+    // construction failed (read-only FS, etc.) we still pass the getter;
+    // it just resolves to `undefined` and the API router answers 503.
+    getVectorMemoryStore: () => vectorMemoryStore,
+    vectorMemoryModelCacheDir
   });
   const wsResult = createWsServers(httpServer, ports, accessToken);
   const { wssPrimary, wssSecondary, clients } = wsResult;
@@ -28134,7 +28419,25 @@ async function startWebUI(opts = {}) {
     },
     watcherMetricsRef
   );
-  httpServer.listen(httpPort, wsHost, () => {
+  const strictPort = isStrictPort();
+  const boundPort = await listenWithRetry(httpServer, wsHost, httpPort, {
+    maxTries: strictPort ? 1 : 10
+  });
+  if (boundPort !== httpPort) {
+    console.warn(
+      JSON.stringify({
+        level: "warn",
+        event: "webui.port_reassigned",
+        protocol: "HTTP",
+        requested: httpPort,
+        assigned: boundPort,
+        reason: "bind-time EADDRINUSE retry",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      })
+    );
+    httpPort = boundPort;
+  }
+  {
     const authHint = requireToken ? " (authentication required; configure WEBUI_TOKEN out of band)" : "";
     console.log(`[WebUI] HTTP server listening on http://${wsHost}:${httpPort}${authHint}`);
     const extraUrls = formatExternalAccessUrls({
@@ -28145,8 +28448,8 @@ async function startWebUI(opts = {}) {
     if (extraUrls.length > 0) {
       console.log("[WebUI] Protected endpoints on external interfaces:\n" + extraUrls.join("\n"));
     }
-  });
-  const companionServer = setupCompanionServer(httpServer, wsHost, httpPort);
+  }
+  const companionServer = await setupCompanionServer(httpServer, wsHost, httpPort);
   async function touchProjectEntry(root, workDir) {
     const resolved = path38.resolve(root);
     const manifest = await loadManifest(globalConfigPath);
@@ -28405,6 +28708,7 @@ projectRoot: ${ev.projectRoot ?? "?"}`,
     },
     codebaseIndexing,
     memoryStore,
+    vectorMemoryStore,
     globalConfigPath
   });
 }
@@ -28638,9 +28942,11 @@ export {
   isPidAlive,
   isPortFree,
   isRegisteredMessageType,
+  isStrictPort,
   isWildcardBind,
   joinSessionRegistryWithWebUIInstances,
   listInstances,
+  listenWithRetry,
   loadManifest,
   loadSavedProviders,
   markConnectionActivity,