iranti-control-plane 0.4.0 → 0.4.1

package/dist/server/bundle.cjs

@@ -1301,8 +1301,8 @@ var require_node = __commonJS({
           break;
         case "PIPE":
         case "TCP":
-          var net2 = require("net");
-          stream2 = new net2.Socket({
+          var net3 = require("net");
+          stream2 = new net3.Socket({
             fd: fd2,
             readable: false,
             writable: true
@@ -25933,8 +25933,8 @@ var require_stream = __commonJS({
     };
     function getNodejsStreamFuncs() {
       function getStream2(ssl) {
-        const net2 = require("net");
-        return new net2.Socket();
+        const net3 = require("net");
+        return new net3.Socket();
       }
       function getSecureStream2(options) {
         const tls = require("tls");
@@ -26056,8 +26056,8 @@ var require_connection = __commonJS({
               options.key = self.ssl.key;
             }
           }
-          const net2 = require("net");
-          if (net2.isIP && net2.isIP(host) === 0) {
+          const net3 = require("net");
+          if (net3.isIP && net3.isIP(host) === 0) {
             options.servername = host;
           }
           try {
@@ -27674,18 +27674,18 @@ var require_client2 = __commonJS({
       this._connecting = false;
       this._connected = false;
       this._queryable = true;
-      const cp = this.connectionParameters = new ConnectionParameters(config);
-      if (config.nativeConnectionString) cp.nativeConnectionString = config.nativeConnectionString;
-      this.user = cp.user;
+      const cp2 = this.connectionParameters = new ConnectionParameters(config);
+      if (config.nativeConnectionString) cp2.nativeConnectionString = config.nativeConnectionString;
+      this.user = cp2.user;
       Object.defineProperty(this, "password", {
         configurable: true,
         enumerable: false,
         writable: true,
-        value: cp.password
+        value: cp2.password
       });
-      this.database = cp.database;
-      this.host = cp.host;
-      this.port = cp.port;
+      this.database = cp2.database;
+      this.host = cp2.host;
+      this.port = cp2.port;
       this.namedQueries = {};
     };
     Client2.Query = NativeQuery;
@@ -28595,6 +28595,12 @@ function runtimeRootCandidates() {
   add(joinPortable((0, import_os2.homedir)(), ".iranti"));
   return Array.from(candidates);
 }
+function classifyRuntimeRoot(runtimeRoot) {
+  const leaf = basenamePortable(resolvePortable(runtimeRoot)).toLowerCase();
+  if (leaf === ".iranti-runtime") return "primary";
+  if (leaf === ".iranti") return "legacy";
+  return "custom";
+}
 
 // src/server/lib/instance-authority.ts
 function deriveInstanceId(instanceDir) {
@@ -31706,7 +31712,135 @@ logsRouter.use((err, _req, res, _next) => {
 var import_express6 = __toESM(require_express2(), 1);
 var import_promises4 = require("fs/promises");
 var import_path7 = require("path");
+var net = __toESM(require("net"), 1);
 init_esm();
+
+// src/server/lib/doctor-remediation.ts
+var LOCAL_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+function quoteCommandArg(value) {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function buildIrantiDoctorCommand(scope) {
+  const quotedRoot = quoteCommandArg(scope.runtimeRoot);
+  return `iranti doctor --instance ${scope.instanceName} --root ${quotedRoot}`;
+}
+function buildDockerContainerName(scope) {
+  const suffix = scope.instanceName.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return suffix ? `iranti_pgvector_${suffix}` : "iranti_pgvector";
+}
+function parseDatabaseTarget(databaseUrl2) {
+  if (!databaseUrl2) return null;
+  try {
+    const parsed = new URL(databaseUrl2);
+    const host = parsed.hostname || null;
+    return {
+      host,
+      port: parsed.port ? Number.parseInt(parsed.port, 10) : 5432,
+      name: parsed.pathname.replace(/^\//, "") || null,
+      user: parsed.username ? decodeURIComponent(parsed.username) : null,
+      password: parsed.password ? decodeURIComponent(parsed.password) : null,
+      isLocal: host ? LOCAL_HOSTS.has(host.toLowerCase()) : false
+    };
+  } catch {
+    return null;
+  }
+}
+function classifyPgvectorIssue(detail) {
+  const normalized = (detail ?? "").trim().toLowerCase();
+  if (/does not exist|unknown database|3d000/.test(normalized)) {
+    return "database_missing";
+  }
+  if (/extension "vector" is not available|pgvector extension is not installed|does not have the pgvector extension installed|create extension if not exists vector|no pgvector/.test(
+    normalized
+  )) {
+    return "missing_extension";
+  }
+  if (/unreachable|database not reachable|econnrefused|connect timeout|timed out|failed to connect|could not connect|connection terminated/.test(
+    normalized
+  )) {
+    return "database_unreachable";
+  }
+  return "generic";
+}
+function buildCreateDatabaseCommand(target) {
+  if (!target.host || !target.port || !target.user || !target.name) return null;
+  return {
+    label: "Create the missing database",
+    command: `createdb -h ${quoteCommandArg(target.host)} -p ${target.port} -U ${quoteCommandArg(target.user)} ${quoteCommandArg(target.name)}`,
+    allowRun: false
+  };
+}
+function buildCreateExtensionCommand(target) {
+  if (!target.host || !target.port || !target.user || !target.name) return null;
+  return {
+    label: "Enable pgvector in this database",
+    command: `psql -h ${quoteCommandArg(target.host)} -p ${target.port} -U ${quoteCommandArg(target.user)} -d ${quoteCommandArg(target.name)} -c "CREATE EXTENSION IF NOT EXISTS vector;"`,
+    allowRun: false
+  };
+}
+function buildDockerRunCommand(scope, target) {
+  if (!target.isLocal || !target.port || !target.name || !target.user) return null;
+  const password = target.password && target.password.trim() !== "" ? target.password : "postgres";
+  return {
+    label: "Start a local pgvector database with Docker",
+    command: `docker run -d --name ${buildDockerContainerName(scope)} -e POSTGRES_USER=${quoteCommandArg(target.user)} -e POSTGRES_PASSWORD=${quoteCommandArg(password)} -e POSTGRES_DB=${quoteCommandArg(target.name)} -p ${target.port}:5432 pgvector/pgvector:pg16`,
+    allowRun: false
+  };
+}
+function buildPgvectorRemediation(scope, detail) {
+  const target = parseDatabaseTarget(scope.databaseUrl);
+  const issue = classifyPgvectorIssue(detail);
+  const commands = [];
+  const doctorCommand = {
+    label: "Re-run Iranti doctor",
+    command: buildIrantiDoctorCommand(scope),
+    allowRun: true
+  };
+  if (!target) {
+    return {
+      operatorNote: "This instance does not have a usable DATABASE_URL yet. The safest local path on macOS, Windows, and Linux is a pgvector Docker container plus a refreshed instance env.",
+      commands: [doctorCommand]
+    };
+  }
+  if (issue === "database_missing") {
+    const createDb = buildCreateDatabaseCommand(target);
+    const createExtension = buildCreateExtensionCommand(target);
+    if (createDb) commands.push(createDb);
+    if (createExtension) commands.push(createExtension);
+    commands.push(doctorCommand);
+    return {
+      operatorNote: target.isLocal ? "The PostgreSQL server is reachable, but the target database does not exist yet. Create the database, enable pgvector, then rerun doctor. If you would rather avoid local PostgreSQL setup, switch this instance to a Docker-backed pgvector database." : "The configured PostgreSQL server is reachable, but the target database does not exist yet. Create the database, enable pgvector, then rerun doctor.",
+      commands
+    };
+  }
+  if (issue === "missing_extension") {
+    const createExtension = buildCreateExtensionCommand(target);
+    if (createExtension) commands.push(createExtension);
+    commands.push(doctorCommand);
+    return {
+      operatorNote: target.isLocal ? "This PostgreSQL server is reachable, but it does not expose pgvector. If you can install extensions here, run the psql command below. Otherwise move this instance to a Docker-backed pgvector database." : "This instance points at a non-local PostgreSQL server. That server must provide the pgvector extension for the default vector backend.",
+      commands
+    };
+  }
+  if (issue === "database_unreachable") {
+    const dockerCommand = buildDockerRunCommand(scope, target);
+    if (dockerCommand) commands.push(dockerCommand);
+    commands.push(doctorCommand);
+    return {
+      operatorNote: target.isLocal ? "Best cross-platform local fix: start a pgvector Docker container on the configured localhost port, then rerun doctor. The Docker command below works on macOS, Windows, and Linux." : "This instance points at a non-local PostgreSQL host and the pgvector backend is unreachable. Verify that the database server is online, reachable from this machine, and still matches DATABASE_URL.",
+      commands
+    };
+  }
+  const fallbackDockerCommand = buildDockerRunCommand(scope, target);
+  if (fallbackDockerCommand) commands.push(fallbackDockerCommand);
+  commands.push(doctorCommand);
+  return {
+    operatorNote: target.isLocal ? "Iranti could not complete the pgvector check cleanly. If the current local PostgreSQL server is unreliable, the Docker pgvector path below is the fastest cross-platform reset on macOS, Windows, and Linux." : "Iranti could not complete the pgvector check cleanly. Verify the configured PostgreSQL server, then rerun doctor.",
+    commands
+  };
+}
+
+// src/server/routes/control-plane/setup.ts
 var { Pool: Pool5 } = esm_default;
 var setupRouter = (0, import_express6.Router)();
 function scopeSummary2(scope) {
@@ -31716,6 +31850,22 @@ function scopeSummary2(scope) {
     source: scope.source
   };
 }
+function primaryRuntimeRootHint(scope) {
+  if (classifyRuntimeRoot(scope.runtimeRoot) !== "legacy") return "";
+  return ` This instance lives under the legacy runtime root ${scope.runtimeRoot}. Newer Iranti instances usually live under ~/.iranti-runtime, so Control Plane is intentionally showing both roots.`;
+}
+function checkRuntimeRoot(scope) {
+  if (classifyRuntimeRoot(scope.runtimeRoot) !== "legacy") return null;
+  return {
+    id: "runtime_root",
+    label: "Instance storage",
+    status: "warning",
+    message: `This instance is stored under the legacy runtime root ${scope.runtimeRoot}.`,
+    actionRequired: "Migrate this instance to the primary runtime root so new instances, runtime commands, and future repair flows all converge on the same home.",
+    cliCommand: null,
+    repairAction: "control-plane:migrate-root"
+  };
+}
 async function resolveScopeOrThrow2(instanceRef) {
   const scope = await resolveInstanceAuthority(instanceRef);
   if (!scope) {
@@ -31756,6 +31906,23 @@ function normalizeProviderId3(value) {
   const normalized = value.trim().toLowerCase();
   return normalized === "anthropic" ? "claude" : normalized;
 }
+async function isTcpPortReachable(host, port, timeoutMs = 1200) {
+  return await new Promise((resolve10) => {
+    const socket = new net.Socket();
+    let settled = false;
+    const finish = (reachable) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve10(reachable);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+    socket.connect(port, host);
+  });
+}
 function providerLabel(providerId) {
   switch (normalizeProviderId3(providerId)) {
     case "claude":
@@ -31780,15 +31947,17 @@ function providerLabel(providerId) {
 }
 async function checkDatabase(scope, pool2) {
   const cliCommand = `iranti doctor --instance ${scope.instanceName} --debug`;
+  const target = parseDatabaseTarget(scope.databaseUrl);
+  const legacyRootNote = primaryRuntimeRootHint(scope);
   if (!pool2) {
     return {
       id: "database",
       label: "Database connection",
       status: "incomplete",
       message: "DATABASE_URL is not configured for this instance.",
-      actionRequired: `Add DATABASE_URL to ${scope.instanceEnvPath}, then restart the instance.`,
+      actionRequired: `Add DATABASE_URL to ${scope.instanceEnvPath}, then restart the instance.${legacyRootNote}`,
       cliCommand,
-      repairAction: null
+      repairAction: "control-plane:open-configure-db"
     };
   }
   try {
@@ -31814,14 +31983,29 @@ async function checkDatabase(scope, pool2) {
       repairAction: null
     };
   } catch {
+    if (target?.isLocal && target.host && target.port) {
+      const reachable = await isTcpPortReachable(target.host, target.port);
+      if (!reachable) {
+        const dbLabel = target.name ? `${target.host}:${target.port}/${target.name}` : `${target.host}:${target.port}`;
+        return {
+          id: "database",
+          label: "Database connection",
+          status: "incomplete",
+          message: `Database not reachable for this instance. ${target.host}:${target.port} is not accepting connections.`,
+          actionRequired: `DATABASE_URL in ${scope.instanceEnvPath} currently points to ${dbLabel}, but nothing is listening there right now. Start the database on that port or update DATABASE_URL to the actual database target, then rerun doctor.${legacyRootNote}`,
+          cliCommand,
+          repairAction: "control-plane:open-configure-db"
+        };
+      }
+    }
     return {
       id: "database",
       label: "Database connection",
       status: "incomplete",
       message: "Database not reachable for this instance.",
-      actionRequired: `Verify DATABASE_URL in ${scope.instanceEnvPath}, then rerun doctor.`,
+      actionRequired: `Verify DATABASE_URL in ${scope.instanceEnvPath}, then rerun doctor.${legacyRootNote}`,
       cliCommand,
-      repairAction: null
+      repairAction: "control-plane:open-configure-db"
     };
   }
 }
@@ -31962,16 +32146,26 @@ function checkProjectIntegration(scope, projectStep) {
 }
 async function buildSetupStatus(scope) {
   const firstRunDetected = await readFirstRunDetected(scope);
+  const runtimeRootKind = classifyRuntimeRoot(scope.runtimeRoot);
   return withScopedPool2(scope.databaseUrl, async (pool2) => {
+    const runtimeRootStep = checkRuntimeRoot(scope);
     const databaseStep = await checkDatabase(scope, pool2);
     const providerStep = checkProvider(scope);
     const projectStep = checkProjectBinding(scope);
     const integrationStep = checkProjectIntegration(scope, projectStep);
-    const steps = [databaseStep, providerStep, projectStep, integrationStep];
+    const steps = [
+      ...runtimeRootStep ? [runtimeRootStep] : [],
+      databaseStep,
+      providerStep,
+      projectStep,
+      integrationStep
+    ];
     const isFullyConfigured = steps.every((step) => step.status === "complete" || step.status === "not_applicable" || step.status === "warning");
     return {
       instanceId: scope.instanceId,
       scope: scopeSummary2(scope),
+      runtimeRoot: scope.runtimeRoot,
+      runtimeRootKind,
       steps,
       isFullyConfigured,
       firstRunDetected
@@ -32042,7 +32236,9 @@ async function doctorCheckRuntimeAvailability(scope) {
         label: "Runtime availability",
         status: "pass",
         message: `Iranti runtime is running and reachable at ${scope.apiBaseUrl}.`,
-        repairAction: null
+        repairAction: null,
+        operatorNote: null,
+        commands: []
       };
     }
     return {
@@ -32050,7 +32246,9 @@ async function doctorCheckRuntimeAvailability(scope) {
       label: "Runtime availability",
       status: res.status >= 500 ? "fail" : "warn",
       message: `Iranti runtime responded with HTTP ${res.status}; runtime-only checks may be incomplete.`,
-      repairAction: null
+      repairAction: null,
+      operatorNote: null,
+      commands: []
     };
   } catch {
     return {
@@ -32058,7 +32256,9 @@ async function doctorCheckRuntimeAvailability(scope) {
       label: "Runtime availability",
       status: "warn",
       message: `Iranti runtime is not running or not reachable at ${scope.apiBaseUrl}; runtime-only checks were skipped.`,
-      repairAction: null
+      repairAction: null,
+      operatorNote: null,
+      commands: []
     };
   } finally {
     clearTimeout(timeout);
@@ -32260,18 +32460,20 @@ repairRouter.post(
     }
   }
 );
-async function doctorCheckDatabase(databaseUrl2) {
-  if (!databaseUrl2) {
+async function doctorCheckDatabase(scope) {
+  if (!scope.databaseUrl) {
     return {
       id: "database_reachability",
       label: "Database connection",
       status: "fail",
       message: "DATABASE_URL is not configured for this instance.",
-      repairAction: null
+      repairAction: null,
+      operatorNote: "This instance cannot reach PostgreSQL until DATABASE_URL is configured.",
+      commands: []
     };
   }
   const pool2 = new Pool6({
-    connectionString: databaseUrl2,
+    connectionString: scope.databaseUrl,
     max: 1,
     idleTimeoutMillis: 1e3,
     connectionTimeoutMillis: 2e3
@@ -32286,15 +32488,21 @@ async function doctorCheckDatabase(databaseUrl2) {
       label: "Database connection",
       status: "pass",
       message: "Database connection is healthy.",
-      repairAction: null
+      repairAction: null,
+      operatorNote: null,
+      commands: []
     };
-  } catch {
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const remediation = buildPgvectorRemediation(scope, detail);
     return {
       id: "database_reachability",
       label: "Database connection",
       status: "fail",
       message: "Database not reachable for this instance. Check DATABASE_URL and the database service.",
-      repairAction: null
+      repairAction: null,
+      operatorNote: remediation.operatorNote,
+      commands: remediation.commands
     };
   } finally {
     await pool2.end().catch(() => {
@@ -32310,7 +32518,9 @@ function doctorCheckProvider(scope) {
     label: "Provider configuration",
     status: hasKey ? "pass" : "warn",
     message: hasKey ? "At least one LLM provider key is configured." : "No LLM provider key found in this instance env. Configure a provider key, then restart Iranti.",
-    repairAction: null
+    repairAction: null,
+    operatorNote: null,
+    commands: []
   };
 }
 function doctorCheckProjectBindings(scope) {
@@ -32319,7 +32529,9 @@ function doctorCheckProjectBindings(scope) {
     label: "Project bindings",
     status: scope.boundProjects.length > 0 ? "pass" : "warn",
     message: scope.boundProjects.length > 0 ? `${scope.boundProjects.length} bound project${scope.boundProjects.length === 1 ? "" : "s"} discovered for this instance.` : "No bound projects found for this instance. Project integration checks cannot be run until a project is bound.",
-    repairAction: null
+    repairAction: null,
+    operatorNote: null,
+    commands: []
   };
 }
 function projectRepairUrl(scope, projectPath, kind) {
@@ -32335,14 +32547,18 @@ function doctorProjectChecks(scope) {
       label: `MCP integration (${projectName})`,
       status: integration.anyMcpPresent && integration.anyMcpHasIranti ? "pass" : "warn",
       message: integration.anyMcpPresent && integration.anyMcpHasIranti ? `A workspace MCP file is present and configured for ${project.projectPath}.` : `No workspace MCP file with an Iranti entry was found for ${project.projectPath}.`,
-      repairAction: integration.anyMcpPresent && integration.anyMcpHasIranti ? null : projectRepairUrl(scope, project.projectPath, "mcp-json")
+      repairAction: integration.anyMcpPresent && integration.anyMcpHasIranti ? null : projectRepairUrl(scope, project.projectPath, "mcp-json"),
+      operatorNote: null,
+      commands: []
     };
     const claudeCheck = {
       id: `claude_md_integration:${project.projectPath}`,
       label: `CLAUDE.md integration (${projectName})`,
       status: integration.claudeMdPresent && integration.claudeMdHasIranti ? "pass" : "warn",
       message: integration.claudeMdPresent && integration.claudeMdHasIranti ? `CLAUDE.md references Iranti for ${project.projectPath}.` : `CLAUDE.md is missing or does not reference Iranti for ${project.projectPath}.`,
-      repairAction: integration.claudeMdPresent && integration.claudeMdHasIranti ? null : projectRepairUrl(scope, project.projectPath, "claude-md")
+      repairAction: integration.claudeMdPresent && integration.claudeMdHasIranti ? null : projectRepairUrl(scope, project.projectPath, "claude-md"),
+      operatorNote: null,
+      commands: []
     };
     return [mcpCheck, claudeCheck];
   });
@@ -32350,20 +32566,23 @@ function doctorProjectChecks(scope) {
 function slugifyDoctorCheckId(value) {
   return value.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
 }
-function mapCliDoctorChecks(payload) {
+function mapCliDoctorChecks(payload, scope) {
   const checks = payload.checks.map((check) => ({
     id: `iranti_doctor:${slugifyDoctorCheckId(check.name)}`,
     label: check.name,
     status: check.status,
     message: check.detail,
-    repairAction: null
+    repairAction: null,
+    ...check.name.toLowerCase().includes("vector backend") && (scope.env["IRANTI_VECTOR_BACKEND"] ?? "pgvector").trim().toLowerCase() === "pgvector" && check.status !== "pass" ? buildPgvectorRemediation(scope, check.detail) : { operatorNote: null, commands: [] }
   }));
   const remediations = (payload.remediations ?? []).map((detail, index) => ({
     id: `iranti_doctor:remediation_${index + 1}`,
     label: `Recommended remediation ${index + 1}`,
     status: payload.status === "fail" ? "fail" : "warn",
     message: detail,
-    repairAction: null
+    repairAction: null,
+    operatorNote: null,
+    commands: []
   }));
   return [...checks, ...remediations];
 }
@@ -32372,7 +32591,7 @@ repairRouter.post("/:instanceId/doctor", async (req, res, next) => {
     const scope = await resolveScopeOr404(req.params["instanceId"], res);
     if (!scope) return;
     const [dbCheck, runtimeCheck] = await Promise.all([
-      doctorCheckDatabase(scope.databaseUrl),
+      doctorCheckDatabase(scope),
       doctorCheckRuntimeAvailability(scope)
     ]);
     let checks;
@@ -32385,7 +32604,7 @@ repairRouter.post("/:instanceId/doctor", async (req, res, next) => {
         scope.runtimeRoot,
         "--json"
       ], { allowNonZeroExit: true });
-      checks = mapCliDoctorChecks(doctor.json);
+      checks = mapCliDoctorChecks(doctor.json, scope);
     } catch (error) {
       checks = [
         {
@@ -32393,7 +32612,9 @@ repairRouter.post("/:instanceId/doctor", async (req, res, next) => {
           label: "Iranti doctor",
           status: "warn",
           message: error instanceof Error ? error.message : String(error),
-          repairAction: null
+          repairAction: null,
+          operatorNote: null,
+          commands: []
         },
         runtimeCheck,
         dbCheck,
@@ -34726,6 +34947,15 @@ var import_express14 = __toESM(require_express2(), 1);
 init_esm();
 var diagnosticsRouter = (0, import_express14.Router)();
 var { Pool: Pool7 } = esm_default;
+var DIAGNOSTIC_ENTITY_TYPE = "__diagnostics__";
+var DIAGNOSTIC_ENTITY_ID = "__probe__";
+var ROUNDTRIP_KEY = "roundtrip_marker";
+var ROUNDTRIP_VALUE = "control-plane-roundtrip-ok";
+var ROUNDTRIP_SUMMARY = "Stable control-plane round-trip probe";
+var VECTOR_PROBE_KEY = "semantic_probe";
+var VECTOR_PROBE_VALUE = "Shared memory helps research teams preserve handoffs and working context.";
+var VECTOR_PROBE_SUMMARY = "Semantic probe for vector-search diagnostics";
+var VECTOR_PROBE_QUERY = "team memory for research workflows";
 var lastDiagnosticResult = /* @__PURE__ */ new Map();
 function scopeSummary4(scope) {
   return {
@@ -34753,6 +34983,9 @@ function buildRunCommand(scope) {
   const quotedRoot = /\s/.test(scope.runtimeRoot) ? `"${scope.runtimeRoot}"` : scope.runtimeRoot;
   return `iranti run --instance ${scope.instanceName} --root ${quotedRoot}`;
 }
+function buildKbQueryUrl(scope, key) {
+  return `${scope.apiBaseUrl}/kb/query/${encodeURIComponent(DIAGNOSTIC_ENTITY_TYPE)}/${encodeURIComponent(DIAGNOSTIC_ENTITY_ID)}/${encodeURIComponent(key)}`;
+}
 async function withScopedPool3(databaseUrl2, fn) {
   if (!databaseUrl2) return fn(null);
   const pool2 = new Pool7({
@@ -34942,46 +35175,37 @@ async function checkVectorBackend2(scope, pool2) {
   };
   return withTimeout(work(), 3e3, "vector_backend");
 }
-function extractProbeValueFromSearch(body) {
+function extractExactQueryValue(body) {
   if (body === null || typeof body !== "object") return null;
   const obj = body;
-  const items = Array.isArray(obj["results"]) ? obj["results"] : Array.isArray(obj["facts"]) ? obj["facts"] : Array.isArray(obj["items"]) ? obj["items"] : [];
-  for (const item of items) {
-    if (!item || typeof item !== "object") continue;
-    const fact = item;
-    if (!String(fact["entity"] ?? "").startsWith("__diagnostics__")) continue;
-    if (fact["key"] !== "probe_timestamp") continue;
-    const value = fact["value"] ?? fact["valueRaw"] ?? fact["valueSummary"];
-    if (value !== null && value !== void 0) return String(value);
-  }
-  return null;
-}
-async function deleteProbeFact(scope) {
-  try {
-    await fetch(`${scope.apiBaseUrl}/kb/delete?entity=__diagnostics__/__probe__&key=probe_timestamp`, {
-      method: "DELETE",
-      headers: buildHeaders4(scope)
-    });
-  } catch {
-  }
+  if (obj["found"] !== true) return null;
+  const raw = obj["value"];
+  if (raw === null || raw === void 0) return null;
+  if (typeof raw === "string") return raw;
+  if (typeof raw === "object" && raw !== null && typeof raw["text"] === "string") {
+    return String(raw["text"]);
+  }
+  return String(raw);
+}
+async function writeDiagnosticFact(scope, key, value, summary) {
+  return fetch(`${scope.apiBaseUrl}/kb/write`, {
+    method: "POST",
+    headers: buildHeaders4(scope),
+    body: JSON.stringify({
+      entity: `${DIAGNOSTIC_ENTITY_TYPE}/${DIAGNOSTIC_ENTITY_ID}`,
+      agent: "control_plane_operator",
+      key,
+      value,
+      summary,
+      confidence: 50,
+      source: "control_plane_diagnostics"
+    })
+  });
 }
 async function checkIngestRoundtrip(scope) {
   const start = Date.now();
-  const probeTimestamp = (/* @__PURE__ */ new Date()).toISOString();
   const work = async () => {
-    const writeRes = await fetch(`${scope.apiBaseUrl}/kb/write`, {
-      method: "POST",
-      headers: buildHeaders4(scope),
-      body: JSON.stringify({
-        entity: "__diagnostics__/__probe__",
-        agent: "control_plane_operator",
-        key: "probe_timestamp",
-        value: probeTimestamp,
-        summary: "Diagnostic probe",
-        confidence: 50,
-        source: "control_plane_diagnostics"
-      })
-    });
+    const writeRes = await writeDiagnosticFact(scope, ROUNDTRIP_KEY, ROUNDTRIP_VALUE, ROUNDTRIP_SUMMARY);
     if (!writeRes.ok) {
       return {
         check: "ingest_roundtrip",
@@ -34991,27 +35215,25 @@ async function checkIngestRoundtrip(scope) {
         durationMs: Date.now() - start
       };
     }
-    const queryRes = await fetch(`${scope.apiBaseUrl}/kb/search?query=probe_timestamp&limit=5`, {
+    const queryRes = await fetch(buildKbQueryUrl(scope, ROUNDTRIP_KEY), {
       method: "GET",
       headers: buildHeaders4(scope)
     });
     if (!queryRes.ok) {
-      await deleteProbeFact(scope);
       return {
         check: "ingest_roundtrip",
         status: "fail",
-        message: `Read probe failed: GET /kb/search returned HTTP ${queryRes.status}`,
+        message: `Read probe failed: GET /kb/query returned HTTP ${queryRes.status}`,
         fixHint: null,
         durationMs: Date.now() - start
       };
     }
     const body = await queryRes.json();
-    await deleteProbeFact(scope);
-    const value = extractProbeValueFromSearch(body);
+    const value = extractExactQueryValue(body);
     return {
       check: "ingest_roundtrip",
-      status: value !== null ? "pass" : "fail",
-      message: value !== null ? "Ingest round-trip succeeded" : "Probe fact was written but could not be read back",
+      status: value === ROUNDTRIP_VALUE ? "pass" : "fail",
+      message: value === ROUNDTRIP_VALUE ? "Ingest round-trip succeeded" : "Probe fact was written but could not be read back exactly",
       fixHint: null,
       durationMs: Date.now() - start
     };
@@ -35075,7 +35297,17 @@ function extractSearchItems(body) {
 async function checkVectorSearch(scope) {
   const start = Date.now();
   const work = async () => {
-    const res = await fetch(`${scope.apiBaseUrl}/kb/search?query=diagnostic+probe&limit=1`, {
+    const writeRes = await writeDiagnosticFact(scope, VECTOR_PROBE_KEY, VECTOR_PROBE_VALUE, VECTOR_PROBE_SUMMARY);
+    if (!writeRes.ok) {
+      return {
+        check: "vector_search_check",
+        status: "fail",
+        message: `Write probe failed: POST /kb/write returned HTTP ${writeRes.status}`,
+        fixHint: `Check API key scopes for ${scope.instanceName}.`,
+        durationMs: Date.now() - start
+      };
+    }
+    const res = await fetch(`${scope.apiBaseUrl}/kb/search?query=${encodeURIComponent(VECTOR_PROBE_QUERY)}&limit=5`, {
       method: "GET",
       headers: buildHeaders4(scope)
     });
@@ -35088,22 +35320,31 @@ async function checkVectorSearch(scope) {
         durationMs: Date.now() - start
       };
     }
+    let matchedProbe = false;
     let hasVectorScore = false;
     try {
       const body = await res.json();
-      hasVectorScore = extractSearchItems(body).some((item) => {
-        if (!item || typeof item !== "object") return false;
-        const score = item["vectorScore"];
-        return typeof score === "number" && score > 0;
-      });
+      const items = extractSearchItems(body);
+      for (const item of items) {
+        if (!item || typeof item !== "object") continue;
+        const fact = item;
+        const entity = String(fact["entity"] ?? "");
+        const key = String(fact["key"] ?? "");
+        if (entity !== `${DIAGNOSTIC_ENTITY_TYPE}/${DIAGNOSTIC_ENTITY_ID}` || key !== VECTOR_PROBE_KEY) continue;
+        matchedProbe = true;
+        const score = fact["vectorScore"];
+        hasVectorScore = typeof score === "number" && score > 0;
+        break;
+      }
     } catch {
+      matchedProbe = true;
       hasVectorScore = true;
     }
     return {
       check: "vector_search_check",
-      status: hasVectorScore ? "pass" : "warn",
-      message: hasVectorScore ? "Vector search returned results with non-zero vectorScore" : "Vector search returned 200 but vectorScore=0 for all results",
-      fixHint: null,
+      status: matchedProbe && hasVectorScore ? "pass" : "warn",
+      message: matchedProbe && hasVectorScore ? "Semantic vector probe returned a non-zero vectorScore" : matchedProbe ? "Semantic probe surfaced, but only through lexical matching (vectorScore=0)" : "Semantic vector probe did not appear in hybrid search results",
+      fixHint: matchedProbe && hasVectorScore ? null : matchedProbe ? "Vector backend is reachable, so this usually means embeddings are stale or the semantic probe is underweighted. Re-run doctor and inspect vector index consistency if real search feels weak." : "Vector backend is reachable, but semantic ranking did not surface the known probe. Re-run doctor and inspect vector index consistency if this persists.",
       durationMs: Date.now() - start
     };
   };
@@ -36444,6 +36685,44 @@ function createLifecycleError(code, message, detail) {
 function sleep(ms) {
   return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
+async function readInstanceStatus(name, runtimeRoot, timeoutMs) {
+  const status = await runIrantiJson(["status", "--root", runtimeRoot, "--json"], {
+    timeoutMs
+  });
+  return status.json.instances.find((entry) => entry.name === name) ?? null;
+}
+async function waitForRuntimeReady(name, runtimeRoot) {
+  const timeoutMs = toPositiveInteger(process.env["IRANTI_CP_START_CONFIRM_TIMEOUT_MS"], 15e3);
+  const intervalMs = toPositiveInteger(process.env["IRANTI_CP_START_CONFIRM_POLL_MS"], 500);
+  const statusTimeoutMs = Math.min(timeoutMs, 5e3);
+  const deadline = Date.now() + timeoutMs;
+  let lastObserved = "no runtime status observed";
+  let lastClassification = "missing";
+  while (Date.now() <= deadline) {
+    try {
+      const instance = await readInstanceStatus(name, runtimeRoot, statusTimeoutMs);
+      if (!instance) {
+        lastObserved = `instance '${name}' not reported by iranti status`;
+        lastClassification = "missing";
+      } else {
+        lastObserved = instance.runtime.detail;
+        lastClassification = instance.runtime.classification;
+        if (instance.runtime.classification === "running" || instance.runtime.classification === "unhealthy") {
+          return instance;
+        }
+      }
+    } catch (error) {
+      lastObserved = error instanceof Error ? error.message : String(error);
+      lastClassification = "unknown";
+    }
+    await sleep(intervalMs);
+  }
+  throw createLifecycleError(
+    "START_CONFIRMATION_TIMEOUT",
+    `Iranti instance '${name}' did not become ready within ${Math.ceil(timeoutMs / 1e3)}s after recovery.`,
+    { runtimeRoot, classification: lastClassification, detail: lastObserved }
+  );
+}
 async function waitForConfirmedStart(name, runtimeRoot, pid, child) {
   const timeoutMs = toPositiveInteger(process.env["IRANTI_CP_START_CONFIRM_TIMEOUT_MS"], 15e3);
   const intervalMs = toPositiveInteger(process.env["IRANTI_CP_START_CONFIRM_POLL_MS"], 500);
@@ -36460,10 +36739,7 @@ async function waitForConfirmedStart(name, runtimeRoot, pid, child) {
       );
     }
     try {
-      const status = await runIrantiJson(["status", "--root", runtimeRoot, "--json"], {
-        timeoutMs: statusTimeoutMs
-      });
-      const instance = status.json.instances.find((entry) => entry.name === name);
+      const instance = await readInstanceStatus(name, runtimeRoot, statusTimeoutMs);
       if (!instance) {
         lastObserved = `instance '${name}' not reported by iranti status`;
         lastClassification = "missing";
@@ -36473,13 +36749,6 @@ async function waitForConfirmedStart(name, runtimeRoot, pid, child) {
         if (instance.runtime.classification === "running" && instance.runtime.running && instance.runtime.state?.pid === pid) {
           return instance;
         }
-        if (instance.runtime.classification === "invalid") {
-          throw createLifecycleError(
-            "START_RUNTIME_INVALID",
-            `Iranti reported invalid runtime state for '${name}' after spawn: ${instance.runtime.detail}`,
-            { pid, runtimeRoot, classification: instance.runtime.classification, detail: instance.runtime.detail }
-          );
-        }
       }
     } catch (error) {
       if (typeof error === "object" && error && "code" in error && typeof error.code === "string") {
@@ -36491,11 +36760,17 @@ async function waitForConfirmedStart(name, runtimeRoot, pid, child) {
     await sleep(intervalMs);
   }
   throw createLifecycleError(
-    "START_CONFIRMATION_TIMEOUT",
-    `Iranti instance '${name}' did not become running within ${Math.ceil(timeoutMs / 1e3)}s after spawn.`,
+    lastClassification === "invalid" ? "START_RUNTIME_INVALID" : "START_CONFIRMATION_TIMEOUT",
+    lastClassification === "invalid" ? `Iranti reported invalid runtime state for '${name}' after spawn: ${lastObserved}` : `Iranti instance '${name}' did not become running within ${Math.ceil(timeoutMs / 1e3)}s after spawn.`,
     { pid, runtimeRoot, classification: lastClassification, detail: lastObserved }
   );
 }
+async function recoverInvalidRuntime(name, runtimeRoot) {
+  await runIrantiCommand(["instance", "restart", name, "--root", runtimeRoot], {
+    timeoutMs: 6e4
+  });
+  return waitForRuntimeReady(name, runtimeRoot);
+}
 lifecycleRouter.post("/:name/start", async (req, res) => {
   const { name } = req.params;
   if (!isValidInstanceName(name)) {
@@ -36558,20 +36833,37 @@ lifecycleRouter.post("/:name/start", async (req, res) => {
       return;
     }
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
-    const confirmed = await waitForConfirmedStart(name, runtimeRoot, pid, child);
-    managedProcesses.set(name, { child, pid, startedAt });
+    let confirmed;
+    let recovered = false;
+    try {
+      confirmed = await waitForConfirmedStart(name, runtimeRoot, pid, child);
+    } catch (error) {
+      const code = typeof error === "object" && error && "code" in error ? String(error.code ?? "") : "";
+      if (code !== "START_RUNTIME_INVALID") throw error;
+      confirmed = await recoverInvalidRuntime(name, runtimeRoot);
+      recovered = true;
+    }
+    if (!recovered) {
+      managedProcesses.set(name, { child, pid, startedAt });
+    } else {
+      managedProcesses.delete(name);
+    }
     auditLog("START", name, {
       pid,
       startedAt,
       runtimeRoot,
       runtimeClassification: confirmed.runtime.classification,
-      runtimeDetail: confirmed.runtime.detail
+      runtimeDetail: confirmed.runtime.detail,
+      recovered
     });
     const response = {
       instanceName: name,
       pid,
       status: "started",
-      startedAt
+      startedAt,
+      recovered: recovered || void 0,
+      recoveryAction: recovered ? "restart" : void 0,
+      note: recovered ? "Control Plane detected invalid runtime metadata after spawn and recovered the instance with a restart." : void 0
     };
     res.status(200).json(response);
   } catch (err) {
@@ -37086,6 +37378,9 @@ function parseEnvFile2(filePath) {
   }
   return parsed;
 }
+function buildSimpleEnvFile(entries) {
+  return Object.entries(entries).map(([key, value]) => `${key}=${value}`).join("\n") + "\n";
+}
 function diffEnvKeys(before, after) {
   const keys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
   return Array.from(keys).filter((key) => before[key] !== after[key]).sort();
@@ -37139,10 +37434,62 @@ function instancePaths(runtimeRoot, name) {
     envFile: (0, import_path13.join)(instanceDir, ".env")
   };
 }
+async function moveDirectory(fromPath, toPath) {
+  try {
+    await (0, import_promises7.rename)(fromPath, toPath);
+  } catch (error) {
+    const code = error.code;
+    if (code !== "EXDEV") throw error;
+    await (0, import_promises7.cp)(fromPath, toPath, { recursive: true, force: true });
+    await (0, import_promises7.rm)(fromPath, { recursive: true, force: true });
+  }
+}
+async function rewriteProjectBindingInstanceEnv(projectPath, oldEnvPath, newEnvPath) {
+  const bindingPath = (0, import_path13.join)(projectPath, ".env.iranti");
+  if (!(0, import_fs8.existsSync)(bindingPath)) return;
+  const parsed = parseSimpleEnv2(await (0, import_promises7.readFile)(bindingPath, "utf8"));
+  const current = parsed["IRANTI_INSTANCE_ENV"]?.trim() ?? "";
+  if (!current) return;
+  if ((0, import_path13.resolve)(current) !== (0, import_path13.resolve)(oldEnvPath)) return;
+  parsed["IRANTI_INSTANCE_ENV"] = newEnvPath;
+  await (0, import_promises7.writeFile)(bindingPath, buildSimpleEnvFile(parsed), "utf8");
+}
+async function rewriteMovedInstanceEnv(instanceDir, previousInstanceDir) {
+  const envPath = (0, import_path13.join)(instanceDir, ".env");
+  if (!(0, import_fs8.existsSync)(envPath)) return;
+  const parsed = parseSimpleEnv2(await (0, import_promises7.readFile)(envPath, "utf8"));
+  const oldBase = (0, import_path13.resolve)(previousInstanceDir);
+  const nextEscalation = (0, import_path13.join)(instanceDir, "escalation");
+  const nextRequestLog = (0, import_path13.join)(instanceDir, "logs", "api-requests.log");
+  const currentEscalation = parsed["IRANTI_ESCALATION_DIR"]?.trim() ?? "";
+  const currentRequestLog = parsed["IRANTI_REQUEST_LOG_FILE"]?.trim() ?? "";
+  if (!currentEscalation || (0, import_path13.resolve)(currentEscalation).startsWith(oldBase)) {
+    parsed["IRANTI_ESCALATION_DIR"] = nextEscalation;
+  }
+  if (!currentRequestLog || (0, import_path13.resolve)((0, import_path13.dirname)(currentRequestLog)).startsWith((0, import_path13.resolve)((0, import_path13.join)(previousInstanceDir, "logs")))) {
+    parsed["IRANTI_REQUEST_LOG_FILE"] = nextRequestLog;
+  }
+  await (0, import_promises7.writeFile)(envPath, buildSimpleEnvFile(parsed), "utf8");
+}
+async function rewriteMovedInstanceMeta(instanceDir, name) {
+  const metaPath = (0, import_path13.join)(instanceDir, "instance.json");
+  if (!(0, import_fs8.existsSync)(metaPath)) return;
+  const parsed = JSON.parse(await (0, import_promises7.readFile)(metaPath, "utf8"));
+  parsed["name"] = name;
+  parsed["instanceDir"] = instanceDir;
+  parsed["envFile"] = (0, import_path13.join)(instanceDir, ".env");
+  await (0, import_promises7.writeFile)(metaPath, `${JSON.stringify(parsed, null, 2)}
+`, "utf8");
+}
+async function clearMovedRuntimeMetadata(instanceDir) {
+  const runtimePath = (0, import_path13.join)(instanceDir, "runtime.json");
+  if (!(0, import_fs8.existsSync)(runtimePath)) return;
+  await (0, import_promises7.rm)(runtimePath, { force: true });
+}
 function escapePgIdentifier(value) {
   return `"${value.replace(/"/g, '""')}"`;
 }
-function parseDatabaseTarget(dbUrl) {
+function parseDatabaseTarget2(dbUrl) {
   const parsed = new URL(dbUrl);
   const databaseName = decodeURIComponent(parsed.pathname.replace(/^\//, "").trim());
   if (!databaseName) {
@@ -37158,7 +37505,7 @@ function parseDatabaseTarget(dbUrl) {
   };
 }
 async function dropDatabase(dbUrl) {
-  const { adminUrl, databaseName } = parseDatabaseTarget(dbUrl);
+  const { adminUrl, databaseName } = parseDatabaseTarget2(dbUrl);
   const pool2 = new Pool8({ connectionString: adminUrl });
   try {
     await pool2.query(
@@ -37447,6 +37794,83 @@ instanceLifecycleRouter.delete("/instances/:name", async (req, res) => {
     droppedDatabase: droppedDatabaseName
   });
 });
+instanceLifecycleRouter.post("/instances/:name/migrate-root", async (req, res) => {
+  const { name } = req.params;
+  if (!isValidInstanceName2(name)) {
+    res.status(400).json({
+      error: "Invalid instance name. Use only alphanumeric characters, hyphens, and underscores (1-64 chars).",
+      code: "INVALID_PARAM"
+    });
+    return;
+  }
+  const resolvedAuthority = await resolveInstanceAuthority(name);
+  if (!resolvedAuthority) {
+    res.status(404).json({
+      error: `Instance "${name}" not found.`,
+      code: "NOT_FOUND"
+    });
+    return;
+  }
+  const currentRoot = resolvedAuthority.runtimeRoot;
+  const targetRoot = preferredRuntimeRoot();
+  if ((0, import_path13.resolve)(currentRoot) === (0, import_path13.resolve)(targetRoot)) {
+    res.status(200).json({
+      ok: true,
+      name,
+      migrated: false,
+      runtimeRoot: currentRoot,
+      runtimeRootKind: classifyRuntimeRoot(currentRoot),
+      instanceId: resolvedAuthority.instanceId,
+      note: "Instance is already stored in the preferred runtime root.",
+      updatedBindings: 0
+    });
+    return;
+  }
+  if (await isInstanceRunning(currentRoot, name)) {
+    res.status(409).json({
+      error: `Instance "${name}" is still running. Stop or recover it before migrating the runtime root.`,
+      code: "INSTANCE_RUNNING"
+    });
+    return;
+  }
+  const targetInstanceDir = (0, import_path13.join)(targetRoot, "instances", name);
+  if ((0, import_fs8.existsSync)(targetInstanceDir)) {
+    res.status(409).json({
+      error: `Target runtime root already contains an instance named "${name}".`,
+      code: "TARGET_EXISTS"
+    });
+    return;
+  }
+  const oldEnvPath = resolvedAuthority.instanceEnvPath;
+  const newEnvPath = (0, import_path13.join)(targetInstanceDir, ".env");
+  try {
+    await (0, import_promises7.mkdir)((0, import_path13.join)(targetRoot, "instances"), { recursive: true });
+    await moveDirectory(resolvedAuthority.instanceDir, targetInstanceDir);
+    await rewriteMovedInstanceEnv(targetInstanceDir, resolvedAuthority.instanceDir);
+    await rewriteMovedInstanceMeta(targetInstanceDir, name);
+    await clearMovedRuntimeMetadata(targetInstanceDir);
+    let updatedBindings = 0;
+    for (const project of resolvedAuthority.boundProjects) {
+      await rewriteProjectBindingInstanceEnv(project.projectPath, oldEnvPath, newEnvPath);
+      updatedBindings += 1;
+    }
+    res.status(200).json({
+      ok: true,
+      name,
+      migrated: true,
+      runtimeRoot: targetRoot,
+      runtimeRootKind: classifyRuntimeRoot(targetRoot),
+      instanceId: deriveInstanceId(targetInstanceDir),
+      note: "Instance moved to the preferred runtime root and bound project env files were updated.",
+      updatedBindings
+    });
+  } catch (error) {
+    res.status(500).json({
+      error: commandFailureMessage(error),
+      code: "MIGRATE_FAILED"
+    });
+  }
+});
 
 // src/server/routes/control-plane/project-bindings.ts
 var import_express25 = __toESM(require_express2(), 1);