postgresai 0.16.0-dev.1 → 0.16.0-dev.10

package/dist/bin/postgres-ai.js

@@ -9980,8 +9980,8 @@ var require_utils3 = __commonJS((exports, module) => {
     }
     return ind;
   }
-  function removeDotSegments(path4) {
-    let input = path4;
+  function removeDotSegments(path5) {
+    let input = path5;
     const output = [];
     let nextSlash = -1;
     let len = 0;
@@ -10171,8 +10171,8 @@ var require_schemes = __commonJS((exports, module) => {
       wsComponent.secure = undefined;
     }
     if (wsComponent.resourceName) {
-      const [path4, query] = wsComponent.resourceName.split("?");
-      wsComponent.path = path4 && path4 !== "/" ? path4 : undefined;
+      const [path5, query] = wsComponent.resourceName.split("?");
+      wsComponent.path = path5 && path5 !== "/" ? path5 : undefined;
       wsComponent.query = query;
       wsComponent.resourceName = undefined;
     }
@@ -13307,12 +13307,12 @@ var require_dist2 = __commonJS((exports, module) => {
       throw new Error(`Unknown format "${name}"`);
     return f;
   };
-  function addFormats(ajv, list, fs4, exportName) {
+  function addFormats(ajv, list, fs5, exportName) {
     var _a2;
     var _b;
     (_a2 = (_b = ajv.opts.code).formats) !== null && _a2 !== undefined || (_b.formats = (0, codegen_1._)`require("ajv-formats/dist/formats").${exportName}`);
     for (const f of list)
-      ajv.addFormat(f, fs4[f]);
+      ajv.addFormat(f, fs5[f]);
   }
   module.exports = exports = formatsPlugin;
   Object.defineProperty(exports, "__esModule", { value: true });
@@ -13323,43 +13323,55 @@ var require_dist2 = __commonJS((exports, module) => {
 var exports_util2 = {};
 __export(exports_util2, {
   resolveBaseUrls: () => resolveBaseUrls2,
+  redactSecretsForLog: () => redactSecretsForLog2,
   normalizeBaseUrl: () => normalizeBaseUrl2,
   maskSecret: () => maskSecret2,
-  formatHttpError: () => formatHttpError2
+  formatHttpError: () => formatHttpError2,
+  describeFetchError: () => describeFetchError2
 });
 function isHtmlContent2(text) {
   const trimmed = text.trim();
   return trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html") || trimmed.startsWith("<HTML");
 }
-function formatHttpError2(operation, status, responseBody) {
-  const statusMessage = HTTP_STATUS_MESSAGES2[status] || "Request failed";
-  let errMsg = `${operation}: HTTP ${status} - ${statusMessage}`;
+function formatHttpError2(operation, status, responseBody, statusText) {
+  const generic = HTTP_STATUS_MESSAGES2[status] || "Request failed";
   const remediation = status === 401 ? `
 ${AUTH_REMEDIATION_HINT2}` : "";
-  if (responseBody) {
-    if (isHtmlContent2(responseBody)) {
-      return errMsg + remediation;
-    }
+  let bodyMessage;
+  let bodyDetails;
+  if (responseBody && !isHtmlContent2(responseBody)) {
     try {
       const errObj = JSON.parse(responseBody);
-      const message = errObj.message || errObj.error || errObj.detail;
-      if (message && typeof message === "string") {
-        errMsg += `
-${message}`;
-      } else {
-        errMsg += `
-${JSON.stringify(errObj, null, 2)}`;
+      const message = errObj.message ?? errObj.error;
+      if (typeof message === "string" && message.trim().length > 0) {
+        bodyMessage = message.trim();
+      }
+      const details = errObj.details ?? errObj.detail;
+      if (typeof details === "string" && details.trim().length > 0) {
+        bodyDetails = details.trim();
       }
     } catch {
       const trimmed = responseBody.trim();
       if (trimmed.length > 0 && trimmed.length < 500) {
-        errMsg += `
-${trimmed}`;
+        bodyDetails = trimmed;
       }
     }
   }
+  const trimmedReason = statusText?.trim();
+  const reasonPhrase = trimmedReason && trimmedReason !== STANDARD_REASON_PHRASES2[status] && trimmedReason !== generic ? trimmedReason : undefined;
+  const headline = bodyMessage ?? reasonPhrase ?? generic;
+  let errMsg = `${operation}: HTTP ${status} - ${headline}`;
+  if (bodyDetails && bodyDetails !== headline) {
+    errMsg += `
+${bodyDetails}`;
+  }
   return errMsg + remediation;
 }
+function describeFetchError2(operation, url, err) {
+  const cause = err?.cause;
+  const detail = cause?.code || cause?.message || (err instanceof Error && err.message ? err.message : String(err));
+  return `${operation}: could not reach ${url} (${detail})`;
+}
 function maskSecret2(secret) {
   if (!secret)
     return "";
@@ -13369,6 +13381,28 @@ function maskSecret2(secret) {
     return `${secret.slice(0, 4)}${"*".repeat(secret.length - 8)}${secret.slice(-4)}`;
   return `${secret.slice(0, Math.min(12, secret.length - 8))}${"*".repeat(Math.max(4, secret.length - 16))}${secret.slice(-4)}`;
 }
+function redactSecretsForLog2(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return text;
+  }
+  const walk = (node) => {
+    if (Array.isArray(node)) {
+      return node.map(walk);
+    }
+    if (node && typeof node === "object") {
+      const out = {};
+      for (const [key, value] of Object.entries(node)) {
+        out[key] = SENSITIVE_LOG_KEY2.test(key) && value != null ? "[REDACTED]" : walk(value);
+      }
+      return out;
+    }
+    return node;
+  };
+  return JSON.stringify(walk(parsed));
+}
 function normalizeBaseUrl2(value) {
   const trimmed = (value || "").replace(/\/$/, "");
   try {
@@ -13391,7 +13425,7 @@ function resolveBaseUrls2(opts, cfg, defaults2 = {}) {
     storageBaseUrl: normalizeBaseUrl2(storageCandidate)
   };
 }
-var HTTP_STATUS_MESSAGES2, AUTH_REMEDIATION_HINT2 = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.";
+var HTTP_STATUS_MESSAGES2, AUTH_REMEDIATION_HINT2 = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.", STANDARD_REASON_PHRASES2, SENSITIVE_LOG_KEY2;
 var init_util = __esm(() => {
   HTTP_STATUS_MESSAGES2 = {
     400: "Bad Request",
@@ -13405,6 +13439,21 @@ var init_util = __esm(() => {
     503: "Service Unavailable - server temporarily unavailable",
     504: "Gateway Timeout - server temporarily unavailable"
   };
+  STANDARD_REASON_PHRASES2 = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    408: "Request Timeout",
+    409: "Conflict",
+    413: "Payload Too Large",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout"
+  };
+  SENSITIVE_LOG_KEY2 = /password|connstr/i;
 });
 
 // node_modules/commander/esm.mjs
@@ -13425,7 +13474,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.16.0-dev.1",
+  version: "0.16.0-dev.10",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16236,11 +16285,11 @@ var safeLoadAll = renamed("safeLoadAll", "loadAll");
 var safeDump = renamed("safeDump", "dump");
 
 // bin/postgres-ai.ts
-import * as fs9 from "fs";
-import * as path7 from "path";
+import * as fs11 from "fs";
+import * as path9 from "path";
 import * as os3 from "os";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import * as crypto2 from "crypto";
+import * as crypto4 from "crypto";
 
 // node_modules/pg/esm/index.mjs
 var import_lib = __toESM(require_lib2(), 1);
@@ -16256,7 +16305,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.16.0-dev.1";
+var version = "0.16.0-dev.10";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -16398,35 +16447,59 @@ function isHtmlContent(text) {
   return trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html") || trimmed.startsWith("<HTML");
 }
 var AUTH_REMEDIATION_HINT = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.";
-function formatHttpError(operation, status, responseBody) {
-  const statusMessage = HTTP_STATUS_MESSAGES[status] || "Request failed";
-  let errMsg = `${operation}: HTTP ${status} - ${statusMessage}`;
+var STANDARD_REASON_PHRASES = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  408: "Request Timeout",
+  409: "Conflict",
+  413: "Payload Too Large",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout"
+};
+function formatHttpError(operation, status, responseBody, statusText) {
+  const generic = HTTP_STATUS_MESSAGES[status] || "Request failed";
   const remediation = status === 401 ? `
 ${AUTH_REMEDIATION_HINT}` : "";
-  if (responseBody) {
-    if (isHtmlContent(responseBody)) {
-      return errMsg + remediation;
-    }
+  let bodyMessage;
+  let bodyDetails;
+  if (responseBody && !isHtmlContent(responseBody)) {
     try {
       const errObj = JSON.parse(responseBody);
-      const message = errObj.message || errObj.error || errObj.detail;
-      if (message && typeof message === "string") {
-        errMsg += `
-${message}`;
-      } else {
-        errMsg += `
-${JSON.stringify(errObj, null, 2)}`;
+      const message = errObj.message ?? errObj.error;
+      if (typeof message === "string" && message.trim().length > 0) {
+        bodyMessage = message.trim();
+      }
+      const details = errObj.details ?? errObj.detail;
+      if (typeof details === "string" && details.trim().length > 0) {
+        bodyDetails = details.trim();
       }
     } catch {
       const trimmed = responseBody.trim();
       if (trimmed.length > 0 && trimmed.length < 500) {
-        errMsg += `
-${trimmed}`;
+        bodyDetails = trimmed;
       }
     }
   }
+  const trimmedReason = statusText?.trim();
+  const reasonPhrase = trimmedReason && trimmedReason !== STANDARD_REASON_PHRASES[status] && trimmedReason !== generic ? trimmedReason : undefined;
+  const headline = bodyMessage ?? reasonPhrase ?? generic;
+  let errMsg = `${operation}: HTTP ${status} - ${headline}`;
+  if (bodyDetails && bodyDetails !== headline) {
+    errMsg += `
+${bodyDetails}`;
+  }
   return errMsg + remediation;
 }
+function describeFetchError(operation, url, err) {
+  const cause = err?.cause;
+  const detail = cause?.code || cause?.message || (err instanceof Error && err.message ? err.message : String(err));
+  return `${operation}: could not reach ${url} (${detail})`;
+}
 function maskSecret(secret) {
   if (!secret)
     return "";
@@ -16436,6 +16509,29 @@ function maskSecret(secret) {
     return `${secret.slice(0, 4)}${"*".repeat(secret.length - 8)}${secret.slice(-4)}`;
   return `${secret.slice(0, Math.min(12, secret.length - 8))}${"*".repeat(Math.max(4, secret.length - 16))}${secret.slice(-4)}`;
 }
+var SENSITIVE_LOG_KEY = /password|connstr/i;
+function redactSecretsForLog(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return text;
+  }
+  const walk = (node) => {
+    if (Array.isArray(node)) {
+      return node.map(walk);
+    }
+    if (node && typeof node === "object") {
+      const out = {};
+      for (const [key, value] of Object.entries(node)) {
+        out[key] = SENSITIVE_LOG_KEY.test(key) && value != null ? "[REDACTED]" : walk(value);
+      }
+      return out;
+    }
+    return node;
+  };
+  return JSON.stringify(walk(parsed));
+}
 function normalizeBaseUrl(value) {
   const trimmed = (value || "").replace(/\/$/, "");
   try {
@@ -17267,9 +17363,611 @@ async function fetchReportFileData(params) {
   }
 }
 
-// lib/storage.ts
+// lib/joe.ts
 import * as fs3 from "fs";
 import * as path3 from "path";
+import * as crypto from "node:crypto";
+var JOE_COMMANDS = [
+  "plan",
+  "explain",
+  "exec",
+  "hypo",
+  "activity",
+  "terminate",
+  "reset",
+  "describe"
+];
+var TERMINAL_STATES = new Set([
+  "done",
+  "error",
+  "timed_out"
+]);
+var AI_ENABLED_COMMANDS = new Set([
+  "plan",
+  "explain",
+  "exec",
+  "hypo",
+  "activity",
+  "describe"
+]);
+var EXECUTING_COMMANDS = new Set([
+  "exec",
+  "explain"
+]);
+var DEFAULT_BUDGET_MS = 25000;
+var DEFAULT_POLL_INTERVAL_MS = 800;
+async function callRpc(params) {
+  const { apiKey, apiBaseUrl, fn, body, operation, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/${fn}`);
+  const payload = JSON.stringify(body);
+  const headers = {
+    "access-token": apiKey,
+    "Content-Type": "application/json",
+    Connection: "close"
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.error(`Debug: POST URL: ${url.toString()}`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Request body: ${redactSecretsForLog(payload)}`);
+  }
+  let response;
+  try {
+    response = await fetch(url.toString(), {
+      method: "POST",
+      headers,
+      body: payload
+    });
+  } catch (err) {
+    throw new Error(describeFetchError(operation, base, err));
+  }
+  const text = await response.text();
+  if (debug) {
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response body: ${redactSecretsForLog(text)}`);
+  }
+  if (!response.ok) {
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${operation}: failed to parse response: ${text}`);
+  }
+}
+async function submitCommand(params) {
+  const { apiKey, apiBaseUrl, command, projectId, sql, args, sessionId, idempotencyKey, debug } = params;
+  if (!JOE_COMMANDS.includes(command)) {
+    throw new Error(`Unknown Joe command: ${command}`);
+  }
+  const body = {
+    project_id: projectId,
+    command,
+    sql: sql ?? null,
+    args: args ?? null,
+    session_id: sessionId ?? null
+  };
+  if (idempotencyKey) {
+    body.idempotency_key = idempotencyKey;
+  }
+  return callRpc({
+    apiKey,
+    apiBaseUrl,
+    fn: "joe_command_submit",
+    body,
+    operation: `Failed to submit ${command} command`,
+    debug
+  });
+}
+async function getCommandStatus(params) {
+  const { apiKey, apiBaseUrl, commandId, debug } = params;
+  if (!commandId) {
+    throw new Error("commandId is required");
+  }
+  return callRpc({
+    apiKey,
+    apiBaseUrl,
+    fn: "joe_command_status",
+    body: { command_id: commandId },
+    operation: "Failed to fetch command status",
+    debug
+  });
+}
+async function getCommandResult(params) {
+  const { apiKey, apiBaseUrl, commandId, debug } = params;
+  if (!commandId) {
+    throw new Error("commandId is required");
+  }
+  return callRpc({
+    apiKey,
+    apiBaseUrl,
+    fn: "joe_command_result",
+    body: { command_id: commandId },
+    operation: "Failed to fetch command result",
+    debug
+  });
+}
+function normalizeProjectRow(row) {
+  const projectId = row.project_id ?? row.id ?? 0;
+  return {
+    project_id: Number(projectId),
+    alias: row.alias ?? null,
+    name: row.name ?? null,
+    label: row.label ?? null,
+    joe_ready: Boolean(row.joe_ready ?? row.joe_api_v2_enabled ?? false),
+    tunnel: Boolean(row.tunnel ?? row.tunnel_ready ?? false),
+    instance_id: row.instance_id == null ? null : Number(row.instance_id),
+    dblab_instance_id: row.dblab_instance_id == null ? null : Number(row.dblab_instance_id)
+  };
+}
+async function listProjects(params) {
+  const { apiKey, apiBaseUrl, orgId, debug } = params;
+  const body = {};
+  if (typeof orgId === "number") {
+    body.org_id = orgId;
+  }
+  const rows = await callRpc({
+    apiKey,
+    apiBaseUrl,
+    fn: "projects_list",
+    body,
+    operation: "Failed to list projects",
+    debug
+  });
+  if (!Array.isArray(rows)) {
+    return [];
+  }
+  return rows.map(normalizeProjectRow);
+}
+function isNumericProjectRef(ref) {
+  return /^[0-9]+$/.test(ref.trim());
+}
+async function resolveProjectId(params) {
+  const ref = String(params.project ?? "").trim();
+  if (!ref) {
+    throw new Error("project is required (--project <id|alias>)");
+  }
+  if (isNumericProjectRef(ref)) {
+    return Number(ref);
+  }
+  const projects = await listProjects({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    orgId: params.orgId,
+    debug: params.debug
+  });
+  const needle = ref.toLowerCase();
+  const match = projects.find((p) => p.alias !== null && p.alias.toLowerCase() === needle || p.name !== null && p.name.toLowerCase() === needle || p.label !== null && p.label.toLowerCase() === needle);
+  if (!match) {
+    throw new Error(`Project not found for alias/name '${ref}'. Run 'pgai projects' to see available projects.`);
+  }
+  return match.project_id;
+}
+function sessionStorePath(dir) {
+  return path3.join(dir ?? getConfigDir2(), "joe-sessions.json");
+}
+function readSessionStore(dir) {
+  const file = sessionStorePath(dir);
+  if (!fs3.existsSync(file)) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(fs3.readFileSync(file, "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {}
+  return {};
+}
+function readStoredSessionId(projectId, dir) {
+  const store = readSessionStore(dir);
+  const value = store[String(projectId)];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function writeStoredSessionId(projectId, sessionId, dir) {
+  const baseDir = dir ?? getConfigDir2();
+  if (!fs3.existsSync(baseDir)) {
+    fs3.mkdirSync(baseDir, { recursive: true, mode: 448 });
+  }
+  const store = readSessionStore(dir);
+  store[String(projectId)] = sessionId;
+  fs3.writeFileSync(sessionStorePath(dir), JSON.stringify(store, null, 2) + `
+`, { mode: 384 });
+}
+function clearStoredSessionId(projectId, dir) {
+  const file = sessionStorePath(dir);
+  if (!fs3.existsSync(file)) {
+    return;
+  }
+  const store = readSessionStore(dir);
+  if (String(projectId) in store) {
+    delete store[String(projectId)];
+    fs3.writeFileSync(file, JSON.stringify(store, null, 2) + `
+`, { mode: 384 });
+  }
+}
+function computeIdempotencyKey(command, projectId, sql, args) {
+  if (EXECUTING_COMMANDS.has(command)) {
+    const canonical = `${projectId}
+${command}
+${sql ?? ""}
+${JSON.stringify(args ?? null)}`;
+    return `joe-${crypto.createHash("sha256").update(canonical).digest("hex")}`;
+  }
+  return `joe-${crypto.randomUUID()}`;
+}
+var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function runCommand(params) {
+  const {
+    apiKey,
+    apiBaseUrl,
+    command,
+    projectId,
+    sql,
+    args,
+    sessionId,
+    debug
+  } = params;
+  const budgetMs = typeof params.budgetMs === "number" && Number.isFinite(params.budgetMs) ? params.budgetMs : DEFAULT_BUDGET_MS;
+  const pollIntervalMs = params.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const now = params.now ?? Date.now;
+  const sleep = params.sleep ?? defaultSleep;
+  const idempotencyKey = params.idempotencyKey ?? computeIdempotencyKey(command, projectId, sql, args);
+  const submitted = await submitCommand({
+    apiKey,
+    apiBaseUrl,
+    command,
+    projectId,
+    sql,
+    args,
+    sessionId,
+    idempotencyKey,
+    debug
+  });
+  const commandId = submitted.command_id;
+  const newSessionId = submitted.session_id ?? sessionId ?? null;
+  const deadline = now() + budgetMs;
+  let status = submitted.status;
+  while (true) {
+    const statusResp = await getCommandStatus({ apiKey, apiBaseUrl, commandId, debug });
+    status = statusResp.status;
+    if (TERMINAL_STATES.has(status)) {
+      break;
+    }
+    if (now() >= deadline) {
+      return { commandId, sessionId: newSessionId, status, result: null, budgetExpired: true };
+    }
+    await sleep(pollIntervalMs);
+  }
+  const result = await getCommandResult({ apiKey, apiBaseUrl, commandId, debug });
+  return { commandId, sessionId: newSessionId, status, result, budgetExpired: false };
+}
+async function executeJoeCommand(params) {
+  const projectId = await resolveProjectId({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    project: params.project,
+    orgId: params.orgId,
+    debug: params.debug
+  });
+  let sessionId;
+  if (params.newSession) {
+    clearStoredSessionId(projectId, params.sessionDir);
+    sessionId = null;
+  } else if (params.session) {
+    sessionId = String(params.session);
+  } else {
+    sessionId = readStoredSessionId(projectId, params.sessionDir);
+  }
+  const outcome = await runCommand({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    command: params.command,
+    projectId,
+    sql: params.sql,
+    args: params.args,
+    sessionId,
+    budgetMs: params.budgetMs,
+    pollIntervalMs: params.pollIntervalMs,
+    debug: params.debug,
+    now: params.now,
+    sleep: params.sleep
+  });
+  if (outcome.sessionId) {
+    writeStoredSessionId(projectId, outcome.sessionId, params.sessionDir);
+  }
+  return { ...outcome, command: params.command, projectId };
+}
+
+// lib/dblab.ts
+function isNumericProjectRef2(ref) {
+  return /^[0-9]+$/.test(ref.trim());
+}
+async function resolveDblabInstanceId(params) {
+  const { apiKey, apiBaseUrl, orgId, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  const ref = String(params.project ?? "").trim();
+  if (!ref) {
+    throw new Error("project is required (--project <id|alias>)");
+  }
+  let projects;
+  try {
+    projects = await listProjects({ apiKey, apiBaseUrl, orgId, debug });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to resolve project's DBLab instance: ${message}`);
+  }
+  const numeric = isNumericProjectRef2(ref);
+  const needle = ref.toLowerCase();
+  const match = projects.find((p) => {
+    if (numeric) {
+      return String(p.project_id) === ref;
+    }
+    return p.alias !== null && p.alias.toLowerCase() === needle || p.name !== null && p.name.toLowerCase() === needle || p.label !== null && p.label.toLowerCase() === needle;
+  });
+  if (!match) {
+    throw new Error(`No DBLab instance found for project '${ref}'. Run 'pgai projects' to see available projects.`);
+  }
+  if (match.dblab_instance_id == null) {
+    throw new Error(`Project '${ref}' has no active DBLab instance. Register a DBLab instance for it in the Console first.`);
+  }
+  return String(match.dblab_instance_id);
+}
+async function callDblabApi(params) {
+  const { apiKey, apiBaseUrl, instanceId, action, method, data, operation, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!instanceId) {
+    throw new Error("instanceId is required");
+  }
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/dblab_api_call`);
+  const bodyObj = {
+    instance_id: instanceId,
+    action,
+    method
+  };
+  if (data !== undefined) {
+    bodyObj.data = data;
+  }
+  const body = JSON.stringify(bodyObj);
+  const headers = {
+    "access-token": apiKey,
+    "Content-Type": "application/json",
+    Connection: "close"
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.error(`Debug: POST URL: ${url.toString()}`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Request body: ${redactSecretsForLog(body)}`);
+  }
+  let response;
+  try {
+    response = await fetch(url.toString(), { method: "POST", headers, body });
+  } catch (err) {
+    throw new Error(describeFetchError(operation, base, err));
+  }
+  const text = await response.text();
+  if (debug) {
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response body: ${redactSecretsForLog(text)}`);
+  }
+  if (!response.ok) {
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
+  }
+  if (text.trim() === "") {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${operation}: failed to parse response: ${text}`);
+  }
+}
+async function createClone(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, branch, snapshotId, dbUser, dbPassword, isProtected, debug } = params;
+  const data = { protected: Boolean(isProtected) };
+  if (cloneId)
+    data.id = cloneId;
+  if (branch)
+    data.branch = branch;
+  if (snapshotId)
+    data.snapshot = { id: snapshotId };
+  if (dbUser && dbPassword)
+    data.db = { username: dbUser, password: dbPassword };
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: "/clone",
+    method: "post",
+    data,
+    operation: "Failed to create clone",
+    debug
+  });
+}
+async function listClones(params) {
+  const { apiKey, apiBaseUrl, instanceId, debug } = params;
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: "/clones",
+    method: "get",
+    operation: "Failed to list clones",
+    debug
+  });
+}
+async function getClone(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, debug } = params;
+  if (!cloneId)
+    throw new Error("cloneId is required");
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: `/clone/${encodeURIComponent(cloneId)}`,
+    method: "get",
+    operation: "Failed to get clone",
+    debug
+  });
+}
+async function resetClone(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, snapshotId, latest, debug } = params;
+  if (!cloneId)
+    throw new Error("cloneId is required");
+  const data = { latest: latest ?? !snapshotId };
+  if (snapshotId)
+    data.snapshotID = snapshotId;
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: `/clone/${encodeURIComponent(cloneId)}/reset`,
+    method: "post",
+    data,
+    operation: "Failed to reset clone",
+    debug
+  });
+}
+async function destroyClone(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, debug } = params;
+  if (!cloneId)
+    throw new Error("cloneId is required");
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: `/clone/${encodeURIComponent(cloneId)}`,
+    method: "delete",
+    operation: "Failed to destroy clone",
+    debug
+  });
+}
+async function listBranches(params) {
+  const { apiKey, apiBaseUrl, instanceId, debug } = params;
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: "/branches",
+    method: "get",
+    operation: "Failed to list branches",
+    debug
+  });
+}
+async function createBranch(params) {
+  const { apiKey, apiBaseUrl, instanceId, branchName, baseBranch, snapshotId, debug } = params;
+  if (!branchName)
+    throw new Error("branchName is required");
+  const data = { branchName };
+  if (baseBranch)
+    data.baseBranch = baseBranch;
+  if (snapshotId)
+    data.snapshotID = snapshotId;
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: "/branch",
+    method: "post",
+    data,
+    operation: "Failed to create branch",
+    debug
+  });
+}
+async function deleteBranch(params) {
+  const { apiKey, apiBaseUrl, instanceId, branchName, debug } = params;
+  if (!branchName)
+    throw new Error("branchName is required");
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: `/branch/${encodeURIComponent(branchName)}`,
+    method: "delete",
+    operation: "Failed to delete branch",
+    debug
+  });
+}
+async function branchLog(params) {
+  const { apiKey, apiBaseUrl, instanceId, branchName, debug } = params;
+  if (!branchName)
+    throw new Error("branchName is required");
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: `/branch/${encodeURIComponent(branchName)}/log`,
+    method: "get",
+    operation: "Failed to fetch branch log",
+    debug
+  });
+}
+async function listSnapshots(params) {
+  const { apiKey, apiBaseUrl, instanceId, branchName, dataset, debug } = params;
+  const qs = new URLSearchParams;
+  const branch = branchName?.trim();
+  if (branch)
+    qs.append("branch", branch);
+  if (dataset)
+    qs.append("dataset", dataset);
+  const action = `/snapshots${qs.toString() ? `?${qs.toString()}` : ""}`;
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action,
+    method: "get",
+    operation: "Failed to list snapshots",
+    debug
+  });
+}
+async function createSnapshot(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, message, debug } = params;
+  if (!cloneId)
+    throw new Error("cloneId is required");
+  const data = { cloneID: cloneId };
+  if (message)
+    data.message = message;
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: "/branch/snapshot",
+    method: "post",
+    data,
+    operation: "Failed to create snapshot",
+    debug
+  });
+}
+async function destroySnapshot(params) {
+  const { apiKey, apiBaseUrl, instanceId, snapshotId, force, debug } = params;
+  if (!snapshotId)
+    throw new Error("snapshotId is required");
+  const action = `/snapshot/${snapshotId}?force=${Boolean(force)}`;
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action,
+    method: "delete",
+    operation: "Failed to destroy snapshot",
+    debug
+  });
+}
+
+// lib/storage.ts
+import * as fs4 from "fs";
+import * as path4 from "path";
 var MAX_UPLOAD_SIZE = 500 * 1024 * 1024;
 var MAX_DOWNLOAD_SIZE = 500 * 1024 * 1024;
 var MIME_TYPES = {
@@ -17310,11 +18008,11 @@ async function uploadFile(params) {
   if (!filePath) {
     throw new Error("filePath is required");
   }
-  const resolvedPath = path3.resolve(filePath);
-  if (!fs3.existsSync(resolvedPath)) {
+  const resolvedPath = path4.resolve(filePath);
+  if (!fs4.existsSync(resolvedPath)) {
     throw new Error(`File not found: ${resolvedPath}`);
   }
-  const stat = fs3.statSync(resolvedPath);
+  const stat = fs4.statSync(resolvedPath);
   if (!stat.isFile()) {
     throw new Error(`Not a file: ${resolvedPath}`);
   }
@@ -17326,9 +18024,9 @@ async function uploadFile(params) {
     console.error("Warning: storage URL uses HTTP — API key will be sent unencrypted");
   }
   const url = `${base}/upload`;
-  const fileBuffer = fs3.readFileSync(resolvedPath);
-  const fileName = path3.basename(resolvedPath);
-  const ext = path3.extname(fileName).toLowerCase();
+  const fileBuffer = fs4.readFileSync(resolvedPath);
+  const fileName = path4.basename(resolvedPath);
+  const ext = path4.extname(fileName).toLowerCase();
   const mimeType = MIME_TYPES[ext] || "application/octet-stream";
   const formData = new FormData;
   formData.append("file", new Blob([fileBuffer], { type: mimeType }), fileName);
@@ -17387,15 +18085,15 @@ async function downloadFile(params) {
     const relativePath = fileUrl.startsWith("/") ? fileUrl : `/${fileUrl}`;
     fullUrl = `${base}${relativePath}`;
   }
-  const urlFilename = path3.basename(new URL(fullUrl).pathname);
+  const urlFilename = path4.basename(new URL(fullUrl).pathname);
   if (!urlFilename) {
     throw new Error("Cannot derive filename from URL; please specify --output");
   }
-  const saveTo = outputPath ? path3.resolve(outputPath) : path3.resolve(urlFilename);
+  const saveTo = outputPath ? path4.resolve(outputPath) : path4.resolve(urlFilename);
   if (!outputPath) {
-    const normalizedSave = path3.normalize(saveTo);
-    const cwd = path3.normalize(process.cwd());
-    if (normalizedSave !== cwd && !normalizedSave.startsWith(cwd + path3.sep)) {
+    const normalizedSave = path4.normalize(saveTo);
+    const cwd = path4.normalize(process.cwd());
+    if (normalizedSave !== cwd && !normalizedSave.startsWith(cwd + path4.sep)) {
       throw new Error("Derived output path escapes current directory; please specify --output");
     }
   }
@@ -17427,11 +18125,11 @@ async function downloadFile(params) {
   }
   const arrayBuffer = await response.arrayBuffer();
   const buffer = Buffer.from(arrayBuffer);
-  const parentDir = path3.dirname(saveTo);
-  if (!fs3.existsSync(parentDir)) {
-    fs3.mkdirSync(parentDir, { recursive: true });
+  const parentDir = path4.dirname(saveTo);
+  if (!fs4.existsSync(parentDir)) {
+    fs4.mkdirSync(parentDir, { recursive: true });
   }
-  fs3.writeFileSync(saveTo, buffer);
+  fs4.writeFileSync(saveTo, buffer);
   return {
     savedTo: saveTo,
     size: buffer.length,
@@ -17443,9 +18141,9 @@ function buildMarkdownLink(fileUrl, storageBaseUrl, filename) {
   const base = normalizeBaseUrl(storageBaseUrl);
   const normalizedFileUrl = fileUrl.startsWith("/") ? fileUrl : `/${fileUrl}`;
   const fullUrl = fileUrl.startsWith("http://") || fileUrl.startsWith("https://") ? fileUrl : `${base}${normalizedFileUrl}`;
-  const name = filename || path3.basename(new URL(fullUrl).pathname);
+  const name = filename || path4.basename(new URL(fullUrl).pathname);
   const safeName = name.replace(/[\[\]()]/g, "\\$&");
-  const ext = path3.extname(name).toLowerCase();
+  const ext = path4.extname(name).toLowerCase();
   if (IMAGE_EXTENSIONS.has(ext)) {
     return `![${safeName}](${fullUrl})`;
   }
@@ -17733,10 +18431,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema2) {
   return mergeDefs(schema2._zod.def);
 }
-function getElementAtPath(obj, path4) {
-  if (!path4)
+function getElementAtPath(obj, path5) {
+  if (!path5)
     return obj;
-  return path4.reduce((acc, key) => acc?.[key], obj);
+  return path5.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -18100,11 +18798,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path4, issues) {
+function prefixIssues(path5, issues) {
   return issues.map((iss) => {
     var _a;
     (_a = iss).path ?? (_a.path = []);
-    iss.path.unshift(path4);
+    iss.path.unshift(path5);
     return iss;
   });
 }
@@ -24376,14 +25074,219 @@ class StdioServerTransport {
 // lib/mcp-server.ts
 var interpretEscapes = (str2) => (str2 || "").replace(/\\n/g, `
 `).replace(/\\t/g, "\t").replace(/\\r/g, "\r").replace(/\\"/g, '"').replace(/\\'/g, "'");
-async function handleToolCall(req, rootOpts, extra) {
-  const toolName = req.params.name;
-  const args = req.params.arguments || {};
-  const cfg = readConfig2();
-  const apiKey = (rootOpts?.apiKey || process.env.PGAI_API_KEY || cfg.apiKey || "").toString();
-  const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
-  const debug = Boolean(args.debug ?? extra?.debug);
-  if (!apiKey) {
+var JOE_TOOL_TO_COMMAND = {
+  plan_query: "plan",
+  explain_query: "explain",
+  exec_sql: "exec",
+  hypo_index: "hypo",
+  activity: "activity",
+  terminate_backend: "terminate",
+  reset_clone: "reset",
+  describe: "describe"
+};
+function joeToolDefinitions() {
+  const sessionProps = {
+    project_id: {
+      type: "string",
+      description: "Target project by numeric id OR alias/name (id-or-alias). --project 12 ≡ main-db."
+    },
+    session_id: {
+      type: "string",
+      description: "Run on a specific session's clone (64-bit id as a string). Auto-reused per project when omitted."
+    },
+    new_session: { type: "boolean", description: "Force a fresh session/clone (null session)." },
+    timeout_ms: { type: "number", description: "One-shot poll budget in ms (≤ 25000); on expiry returns a command_id to resume." },
+    debug: { type: "boolean", description: "Enable verbose debug logs." }
+  };
+  return [
+    {
+      name: "plan_query",
+      description: "Plan a query (EXPLAIN, plan-only — NEVER executes; the fast/safe default). Returns a sanitized plan tree (literals redacted). LLM-facing: feeds the plan/stats to your LLM when the org's AI features are enabled. Requires joe:plan.",
+      inputSchema: {
+        type: "object",
+        properties: { sql: { type: "string", description: "The query to plan (one explainable statement)." }, ...sessionProps },
+        required: ["sql", "project_id"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "explain_query",
+      description: "EXPLAIN ANALYZE a query — EXECUTES it on the hardened, ephemeral DBLab clone and returns the measured, annotated plan (node types, costs, actual-rows/timings, buffers — literals redacted), NOT raw SELECT result rows. LLM-facing: feeds the measured plan/stats to your LLM when AI features are enabled. Requires joe:exec; subject to the org execution policy (read_only allows SELECT-only).",
+      inputSchema: {
+        type: "object",
+        properties: { sql: { type: "string", description: "The query to EXPLAIN ANALYZE (executes on the clone)." }, ...sessionProps },
+        required: ["sql", "project_id"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "exec_sql",
+      description: "WARNING: executes arbitrary SQL (DDL/DML) on the disposable clone and CAN RETURN REAL (own-data) TABLE ROWS that will enter this agent's LLM context (subject to the agent row-cap / metadata-only minimization). Prefer plan_query (non-executing) when you only need a plan. Requires an explicit joe:exec grant and is subject to the org's joe_execution_policy.",
+      inputSchema: {
+        type: "object",
+        properties: { sql: { type: "string", description: "Arbitrary DDL/DML to run on the clone (e.g. create index, analyze)." }, ...sessionProps },
+        required: ["sql", "project_id"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "hypo_index",
+      description: "HypoPG hypothetical index + re-plan (no real index built, no data change) — would the planner switch to it? LLM-facing. Requires joe:plan.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          sql: { type: "string", description: "Candidate index DDL (e.g. create index on orders (customer_id))." },
+          query: { type: "string", description: "Target query the hypothetical index is evaluated against." },
+          ...sessionProps
+        },
+        required: ["sql", "query", "project_id"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "activity",
+      description: "pg_stat_activity snapshot on the clone (query text redacted). LLM-facing. Requires joe:plan.",
+      inputSchema: { type: "object", properties: { ...sessionProps }, required: ["project_id"], additionalProperties: false }
+    },
+    {
+      name: "terminate_backend",
+      description: "pg_terminate_backend(pid) on the clone. Status-only (no data to the LLM). Requires joe:admin.",
+      inputSchema: {
+        type: "object",
+        properties: { pid: { type: "number", description: "Backend pid to terminate." }, ...sessionProps },
+        required: ["pid", "project_id"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "reset_clone",
+      description: "Reset/recreate the session's thin clone. Status-only (no data to the LLM). Requires joe:admin.",
+      inputSchema: { type: "object", properties: { ...sessionProps }, required: ["project_id"], additionalProperties: false }
+    },
+    {
+      name: "describe",
+      description: "\\d-family schema/relation/index/db/view metadata introspection. LLM-facing (metadata). Requires joe:plan.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          object: { type: "string", description: "Object to describe (e.g. users)." },
+          variant: { type: "string", description: "\\d-family variant (e.g. \\d+, \\di, \\dt)." },
+          ...sessionProps
+        },
+        required: ["object", "project_id"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "list_projects",
+      description: "List the org's projects and which have Joe ready (org-level discovery — NOT a Joe endpoint; mirrors `pgai projects`). Use it to find the project_ids/aliases you may address with the Joe command tools.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          org_id: { type: "number", description: "Organization ID (optional, falls back to config)." },
+          debug: { type: "boolean", description: "Enable verbose debug logs." }
+        },
+        additionalProperties: false
+      }
+    }
+  ];
+}
+function sanitizeBudgetMs(value) {
+  if (value === undefined || value === null) {
+    return;
+  }
+  const n = Number(value);
+  return Number.isFinite(n) ? n : undefined;
+}
+async function runJoeTool(params) {
+  const command = JOE_TOOL_TO_COMMAND[params.toolName];
+  const a = params.args;
+  const project = String(a.project_id ?? "").trim();
+  if (!project) {
+    return { content: [{ type: "text", text: "project_id is required" }], isError: true };
+  }
+  let sql = null;
+  let cmdArgs = null;
+  if (command === "plan" || command === "explain" || command === "exec" || command === "hypo") {
+    sql = String(a.sql ?? "").trim();
+    if (!sql) {
+      return { content: [{ type: "text", text: "sql is required" }], isError: true };
+    }
+  }
+  if (command === "hypo") {
+    const query = String(a.query ?? "").trim();
+    if (!query) {
+      return { content: [{ type: "text", text: "query is required for hypo_index" }], isError: true };
+    }
+    cmdArgs = { query };
+  }
+  if (command === "terminate") {
+    const raw = a.pid;
+    const pid = typeof raw === "number" ? raw : typeof raw === "string" && /^[0-9]+$/.test(raw.trim()) ? Number(raw.trim()) : Number.NaN;
+    if (!Number.isInteger(pid) || pid <= 0) {
+      return {
+        content: [{ type: "text", text: "pid must be a strict positive integer (backend pid) for terminate_backend" }],
+        isError: true
+      };
+    }
+    cmdArgs = { pid };
+  }
+  if (command === "describe") {
+    const object4 = String(a.object ?? "").trim();
+    if (!object4) {
+      return { content: [{ type: "text", text: "object is required for describe" }], isError: true };
+    }
+    cmdArgs = { object: object4 };
+    if (a.variant !== undefined)
+      cmdArgs.variant = String(a.variant);
+  }
+  const session = a.session_id !== undefined && a.session_id !== null ? String(a.session_id) : null;
+  const newSession = a.new_session === true;
+  const budgetMs = sanitizeBudgetMs(a.timeout_ms);
+  const outcome = await executeJoeCommand({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    command,
+    project,
+    sql,
+    args: cmdArgs,
+    session,
+    newSession,
+    orgId: params.orgId,
+    budgetMs,
+    debug: params.debug
+  });
+  const payload = {
+    command,
+    command_id: outcome.commandId,
+    session_id: outcome.sessionId,
+    status: outcome.status,
+    budget_expired: outcome.budgetExpired,
+    resume: outcome.budgetExpired ? `pgai joe result ${outcome.commandId}` : undefined,
+    result: outcome.result
+  };
+  const isError = outcome.status === "error" || outcome.status === "timed_out";
+  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], isError };
+}
+async function resolveDblabInstanceForTool(apiKey, apiBaseUrl, args, cfgOrgId, debug) {
+  const project = String(args.project || "").trim();
+  if (!project) {
+    throw new Error("project is required (project id or alias)");
+  }
+  const orgId = args.org_id !== undefined ? Number(args.org_id) : cfgOrgId ?? undefined;
+  return resolveDblabInstanceId({ apiKey, apiBaseUrl, project, orgId, debug });
+}
+function optStr(v) {
+  return v !== undefined && v !== null && String(v).length > 0 ? String(v) : undefined;
+}
+async function handleToolCall(req, rootOpts, extra) {
+  const toolName = req.params.name;
+  const args = req.params.arguments || {};
+  const cfg = readConfig2();
+  const apiKey = (rootOpts?.apiKey || process.env.PGAI_API_KEY || cfg.apiKey || "").toString();
+  const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+  const debug = Boolean(args.debug ?? extra?.debug);
+  if (!apiKey) {
     return {
       content: [
         {
@@ -24653,6 +25556,147 @@ async function handleToolCall(req, rootOpts, extra) {
       const files = await fetchReportFileData({ apiKey, apiBaseUrl, reportId, type: type2, checkId, debug });
       return { content: [{ type: "text", text: JSON.stringify(files, null, 2) }] };
     }
+    if (toolName === "list_projects") {
+      const orgId = args.org_id !== undefined ? Number(args.org_id) : cfg.orgId ?? undefined;
+      const projects = await listProjects({ apiKey, apiBaseUrl, orgId, debug });
+      return { content: [{ type: "text", text: JSON.stringify(projects, null, 2) }] };
+    }
+    if (toolName in JOE_TOOL_TO_COMMAND) {
+      const orgId = cfg.orgId ?? undefined;
+      return await runJoeTool({ toolName, apiKey, apiBaseUrl, orgId, args, debug });
+    }
+    if (toolName === "clone_create") {
+      const instanceId = await resolveDblabInstanceForTool(apiKey, apiBaseUrl, args, cfg.orgId, debug);
+      const result = await createClone({
+        apiKey,
+        apiBaseUrl,
+        instanceId,
+        cloneId: optStr(args.clone_id),
+        branch: optStr(args.branch),
+        snapshotId: optStr(args.snapshot_id),
+        dbUser: optStr(args.db_user),
+        dbPassword: optStr(args.db_password),
+        isProtected: args.protected === true,
+        debug
+      });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    if (toolName === "clone_list") {
+      const instanceId = await resolveDblabInstanceForTool(apiKey, apiBaseUrl, args, cfg.orgId, debug);
+      const result = await listClones({ apiKey, apiBaseUrl, instanceId, debug });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    if (toolName === "clone_status") {
+      const cloneId = String(args.clone_id || "").trim();
+      if (!cloneId)
+        return { content: [{ type: "text", text: "clone_id is required" }], isError: true };
+      const instanceId = await resolveDblabInstanceForTool(apiKey, apiBaseUrl, args, cfg.orgId, debug);
+      const result = await getClone({ apiKey, apiBaseUrl, instanceId, cloneId, debug });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    if (toolName === "clone_reset") {
+      const cloneId = String(args.clone_id || "").trim();
+      if (!cloneId)
+        return { content: [{ type: "text", text: "clone_id is required" }], isError: true };
+      const instanceId = await resolveDblabInstanceForTool(apiKey, apiBaseUrl, args, cfg.orgId, debug);
+      const result = await resetClone({
+        apiKey,
+        apiBaseUrl,
+        instanceId,
+        cloneId,
+        snapshotId: optStr(args.snapshot_id),
+        latest: args.latest === true ? true : undefined,
+        debug
+      });
+      return { content: [{ type: "text", text: JSON.stringify(result ?? { reset: true, cloneId }, null, 2) }] };
+    }
+    if (toolName === "clone_destroy") {
+      const cloneId = String(args.clone_id || "").trim();
+      if (!cloneId)
+        return { content: [{ type: "text", text: "clone_id is required" }], isError: true };
+      const instanceId = await resolveDblabInstanceForTool(apiKey, apiBaseUrl, args, cfg.orgId, debug);
+      const result = await destroyClone({ apiKey, apiBaseUrl, instanceId, cloneId, debug });
+      return { content: [{ type: "text", text: JSON.stringify(result ?? { destroyed: true, cloneId }, null, 2) }] };
+    }
+    if (toolName === "branch_list") {
+      const instanceId = await resolveDblabInstanceForTool(apiKey, apiBaseUrl, args, cfg.orgId, debug);
+      const result = await listBranches({ apiKey, apiBaseUrl, instanceId, debug });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    if (toolName === "branch_create") {
+      const branchName = String(args.name || "").trim();
+      if (!branchName)
+        return { content: [{ type: "text", text: "name is required" }], isError: true };
+      const instanceId = await resolveDblabInstanceForTool(apiKey, apiBaseUrl, args, cfg.orgId, debug);
+      const result = await createBranch({
+        apiKey,
+        apiBaseUrl,
+        instanceId,
+        branchName,
+        baseBranch: optStr(args.base_branch),
+        snapshotId: optStr(args.snapshot_id),
+        debug
+      });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    if (toolName === "branch_delete") {
+      const branchName = String(args.name || "").trim();
+      if (!branchName)
+        return { content: [{ type: "text", text: "name is required" }], isError: true };
+      const instanceId = await resolveDblabInstanceForTool(apiKey, apiBaseUrl, args, cfg.orgId, debug);
+      const result = await deleteBranch({ apiKey, apiBaseUrl, instanceId, branchName, debug });
+      return { content: [{ type: "text", text: JSON.stringify(result ?? { deleted: true, branch: branchName }, null, 2) }] };
+    }
+    if (toolName === "branch_log") {
+      const branchName = String(args.name || "").trim();
+      if (!branchName)
+        return { content: [{ type: "text", text: "name is required" }], isError: true };
+      const instanceId = await resolveDblabInstanceForTool(apiKey, apiBaseUrl, args, cfg.orgId, debug);
+      const result = await branchLog({ apiKey, apiBaseUrl, instanceId, branchName, debug });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    if (toolName === "snapshot_list") {
+      const instanceId = await resolveDblabInstanceForTool(apiKey, apiBaseUrl, args, cfg.orgId, debug);
+      const result = await listSnapshots({
+        apiKey,
+        apiBaseUrl,
+        instanceId,
+        branchName: optStr(args.branch),
+        dataset: optStr(args.dataset),
+        debug
+      });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    if (toolName === "snapshot_create") {
+      const cloneId = String(args.clone_id || "").trim();
+      if (!cloneId)
+        return { content: [{ type: "text", text: "clone_id is required" }], isError: true };
+      const instanceId = await resolveDblabInstanceForTool(apiKey, apiBaseUrl, args, cfg.orgId, debug);
+      const result = await createSnapshot({
+        apiKey,
+        apiBaseUrl,
+        instanceId,
+        cloneId,
+        message: optStr(args.message),
+        debug
+      });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    if (toolName === "snapshot_destroy") {
+      const snapshotId = String(args.snapshot_id || "").trim();
+      if (!snapshotId)
+        return { content: [{ type: "text", text: "snapshot_id is required" }], isError: true };
+      const instanceId = await resolveDblabInstanceForTool(apiKey, apiBaseUrl, args, cfg.orgId, debug);
+      const result = await destroySnapshot({
+        apiKey,
+        apiBaseUrl,
+        instanceId,
+        snapshotId,
+        force: args.force === true,
+        debug
+      });
+      return { content: [{ type: "text", text: JSON.stringify(result ?? { destroyed: true, snapshot: snapshotId }, null, 2) }] };
+    }
     throw new Error(`Unknown tool: ${toolName}`);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -24929,6 +25973,197 @@ async function startMcpServer(rootOpts, extra) {
             },
             additionalProperties: false
           }
+        },
+        ...joeToolDefinitions(),
+        {
+          name: "clone_create",
+          description: "Create a DBLab thin clone of the project's database (same as CLI 'pgai dblab clone create'). Requires the joe:plan scope.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: { type: "string", description: "Project id or alias" },
+              branch: { type: "string", description: "Branch to clone from" },
+              snapshot_id: { type: "string", description: "Snapshot id to clone from" },
+              clone_id: { type: "string", description: "Clone id (DBLab generates one when omitted)" },
+              db_user: { type: "string", description: "Clone DB user" },
+              db_password: { type: "string", description: "Clone DB password" },
+              protected: { type: "boolean", description: "Protect the clone from auto-deletion" },
+              org_id: { type: "number", description: "Organization id (optional, falls back to config)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["project"],
+            additionalProperties: false
+          }
+        },
+        {
+          name: "clone_list",
+          description: "List the project's DBLab thin clones (same as CLI 'pgai dblab clone list').",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: { type: "string", description: "Project id or alias" },
+              org_id: { type: "number", description: "Organization id (optional, falls back to config)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["project"],
+            additionalProperties: false
+          }
+        },
+        {
+          name: "clone_status",
+          description: "Show a DBLab clone's status (same as CLI 'pgai dblab clone status').",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: { type: "string", description: "Project id or alias" },
+              clone_id: { type: "string", description: "Clone id" },
+              org_id: { type: "number", description: "Organization id (optional, falls back to config)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["project", "clone_id"],
+            additionalProperties: false
+          }
+        },
+        {
+          name: "clone_reset",
+          description: "Reset a DBLab clone to a pristine snapshot (same as CLI 'pgai dblab clone reset'). Requires the joe:admin scope.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: { type: "string", description: "Project id or alias" },
+              clone_id: { type: "string", description: "Clone id" },
+              snapshot_id: { type: "string", description: "Snapshot id to reset to (default: latest)" },
+              latest: { type: "boolean", description: "Reset to the latest snapshot" },
+              org_id: { type: "number", description: "Organization id (optional, falls back to config)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["project", "clone_id"],
+            additionalProperties: false
+          }
+        },
+        {
+          name: "clone_destroy",
+          description: "Destroy a DBLab clone (same as CLI 'pgai dblab clone destroy'). Requires the joe:admin scope.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: { type: "string", description: "Project id or alias" },
+              clone_id: { type: "string", description: "Clone id" },
+              org_id: { type: "number", description: "Organization id (optional, falls back to config)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["project", "clone_id"],
+            additionalProperties: false
+          }
+        },
+        {
+          name: "branch_list",
+          description: "List the project's DBLab branches (same as CLI 'pgai dblab branch list').",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: { type: "string", description: "Project id or alias" },
+              org_id: { type: "number", description: "Organization id (optional, falls back to config)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["project"],
+            additionalProperties: false
+          }
+        },
+        {
+          name: "branch_create",
+          description: "Create a DBLab branch (same as CLI 'pgai dblab branch create'). Requires the joe:plan scope.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: { type: "string", description: "Project id or alias" },
+              name: { type: "string", description: "Branch name" },
+              snapshot_id: { type: "string", description: "Snapshot id to base the branch on" },
+              base_branch: { type: "string", description: "Parent branch to fork from" },
+              org_id: { type: "number", description: "Organization id (optional, falls back to config)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["project", "name"],
+            additionalProperties: false
+          }
+        },
+        {
+          name: "branch_delete",
+          description: "Delete a DBLab branch (same as CLI 'pgai dblab branch delete'). Requires the joe:admin scope.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: { type: "string", description: "Project id or alias" },
+              name: { type: "string", description: "Branch name" },
+              org_id: { type: "number", description: "Organization id (optional, falls back to config)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["project", "name"],
+            additionalProperties: false
+          }
+        },
+        {
+          name: "branch_log",
+          description: "Show a DBLab branch's snapshot log (same as CLI 'pgai dblab branch log').",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: { type: "string", description: "Project id or alias" },
+              name: { type: "string", description: "Branch name" },
+              org_id: { type: "number", description: "Organization id (optional, falls back to config)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["project", "name"],
+            additionalProperties: false
+          }
+        },
+        {
+          name: "snapshot_list",
+          description: "List the project's DBLab snapshots (same as CLI 'pgai dblab snapshot list').",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: { type: "string", description: "Project id or alias" },
+              branch: { type: "string", description: "Filter by branch" },
+              dataset: { type: "string", description: "Filter by dataset" },
+              org_id: { type: "number", description: "Organization id (optional, falls back to config)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["project"],
+            additionalProperties: false
+          }
+        },
+        {
+          name: "snapshot_create",
+          description: "Create a DBLab snapshot from a clone (same as CLI 'pgai dblab snapshot create'). Requires the joe:plan scope.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: { type: "string", description: "Project id or alias" },
+              clone_id: { type: "string", description: "Clone id to snapshot" },
+              message: { type: "string", description: "Snapshot message" },
+              org_id: { type: "number", description: "Organization id (optional, falls back to config)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["project", "clone_id"],
+            additionalProperties: false
+          }
+        },
+        {
+          name: "snapshot_destroy",
+          description: "Destroy a DBLab snapshot (same as CLI 'pgai dblab snapshot destroy'). Requires the joe:admin scope.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: { type: "string", description: "Project id or alias" },
+              snapshot_id: { type: "string", description: "Snapshot id" },
+              force: { type: "boolean", description: "Force-delete even when dependent clones exist" },
+              org_id: { type: "number", description: "Organization id (optional, falls back to config)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["project", "snapshot_id"],
+            additionalProperties: false
+          }
         }
       ]
     };
@@ -25801,11 +27036,699 @@ function renderMarkdownForTerminal(md) {
 `);
 }
 
+// lib/joe.ts
+import * as fs5 from "fs";
+import * as path5 from "path";
+import * as crypto2 from "node:crypto";
+var JOE_COMMANDS2 = [
+  "plan",
+  "explain",
+  "exec",
+  "hypo",
+  "activity",
+  "terminate",
+  "reset",
+  "describe"
+];
+var TERMINAL_STATES2 = new Set([
+  "done",
+  "error",
+  "timed_out"
+]);
+var AI_ENABLED_COMMANDS2 = new Set([
+  "plan",
+  "explain",
+  "exec",
+  "hypo",
+  "activity",
+  "describe"
+]);
+var EXECUTING_COMMANDS2 = new Set([
+  "exec",
+  "explain"
+]);
+var DEFAULT_BUDGET_MS2 = 25000;
+var DEFAULT_POLL_INTERVAL_MS2 = 800;
+async function callRpc2(params) {
+  const { apiKey, apiBaseUrl, fn, body, operation, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/${fn}`);
+  const payload = JSON.stringify(body);
+  const headers = {
+    "access-token": apiKey,
+    "Content-Type": "application/json",
+    Connection: "close"
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.error(`Debug: POST URL: ${url.toString()}`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Request body: ${redactSecretsForLog(payload)}`);
+  }
+  let response;
+  try {
+    response = await fetch(url.toString(), {
+      method: "POST",
+      headers,
+      body: payload
+    });
+  } catch (err) {
+    throw new Error(describeFetchError(operation, base, err));
+  }
+  const text = await response.text();
+  if (debug) {
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response body: ${redactSecretsForLog(text)}`);
+  }
+  if (!response.ok) {
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${operation}: failed to parse response: ${text}`);
+  }
+}
+async function submitCommand2(params) {
+  const { apiKey, apiBaseUrl, command, projectId, sql, args, sessionId, idempotencyKey, debug } = params;
+  if (!JOE_COMMANDS2.includes(command)) {
+    throw new Error(`Unknown Joe command: ${command}`);
+  }
+  const body = {
+    project_id: projectId,
+    command,
+    sql: sql ?? null,
+    args: args ?? null,
+    session_id: sessionId ?? null
+  };
+  if (idempotencyKey) {
+    body.idempotency_key = idempotencyKey;
+  }
+  return callRpc2({
+    apiKey,
+    apiBaseUrl,
+    fn: "joe_command_submit",
+    body,
+    operation: `Failed to submit ${command} command`,
+    debug
+  });
+}
+async function getCommandStatus2(params) {
+  const { apiKey, apiBaseUrl, commandId, debug } = params;
+  if (!commandId) {
+    throw new Error("commandId is required");
+  }
+  return callRpc2({
+    apiKey,
+    apiBaseUrl,
+    fn: "joe_command_status",
+    body: { command_id: commandId },
+    operation: "Failed to fetch command status",
+    debug
+  });
+}
+async function getCommandResult2(params) {
+  const { apiKey, apiBaseUrl, commandId, debug } = params;
+  if (!commandId) {
+    throw new Error("commandId is required");
+  }
+  return callRpc2({
+    apiKey,
+    apiBaseUrl,
+    fn: "joe_command_result",
+    body: { command_id: commandId },
+    operation: "Failed to fetch command result",
+    debug
+  });
+}
+function normalizeProjectRow2(row) {
+  const projectId = row.project_id ?? row.id ?? 0;
+  return {
+    project_id: Number(projectId),
+    alias: row.alias ?? null,
+    name: row.name ?? null,
+    label: row.label ?? null,
+    joe_ready: Boolean(row.joe_ready ?? row.joe_api_v2_enabled ?? false),
+    tunnel: Boolean(row.tunnel ?? row.tunnel_ready ?? false),
+    instance_id: row.instance_id == null ? null : Number(row.instance_id),
+    dblab_instance_id: row.dblab_instance_id == null ? null : Number(row.dblab_instance_id)
+  };
+}
+async function listProjects2(params) {
+  const { apiKey, apiBaseUrl, orgId, debug } = params;
+  const body = {};
+  if (typeof orgId === "number") {
+    body.org_id = orgId;
+  }
+  const rows = await callRpc2({
+    apiKey,
+    apiBaseUrl,
+    fn: "projects_list",
+    body,
+    operation: "Failed to list projects",
+    debug
+  });
+  if (!Array.isArray(rows)) {
+    return [];
+  }
+  return rows.map(normalizeProjectRow2);
+}
+function isNumericProjectRef3(ref) {
+  return /^[0-9]+$/.test(ref.trim());
+}
+async function resolveProjectId2(params) {
+  const ref = String(params.project ?? "").trim();
+  if (!ref) {
+    throw new Error("project is required (--project <id|alias>)");
+  }
+  if (isNumericProjectRef3(ref)) {
+    return Number(ref);
+  }
+  const projects = await listProjects2({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    orgId: params.orgId,
+    debug: params.debug
+  });
+  const needle = ref.toLowerCase();
+  const match = projects.find((p) => p.alias !== null && p.alias.toLowerCase() === needle || p.name !== null && p.name.toLowerCase() === needle || p.label !== null && p.label.toLowerCase() === needle);
+  if (!match) {
+    throw new Error(`Project not found for alias/name '${ref}'. Run 'pgai projects' to see available projects.`);
+  }
+  return match.project_id;
+}
+function sessionStorePath2(dir) {
+  return path5.join(dir ?? getConfigDir2(), "joe-sessions.json");
+}
+function readSessionStore2(dir) {
+  const file = sessionStorePath2(dir);
+  if (!fs5.existsSync(file)) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(fs5.readFileSync(file, "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {}
+  return {};
+}
+function readStoredSessionId2(projectId, dir) {
+  const store = readSessionStore2(dir);
+  const value = store[String(projectId)];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function writeStoredSessionId2(projectId, sessionId, dir) {
+  const baseDir = dir ?? getConfigDir2();
+  if (!fs5.existsSync(baseDir)) {
+    fs5.mkdirSync(baseDir, { recursive: true, mode: 448 });
+  }
+  const store = readSessionStore2(dir);
+  store[String(projectId)] = sessionId;
+  fs5.writeFileSync(sessionStorePath2(dir), JSON.stringify(store, null, 2) + `
+`, { mode: 384 });
+}
+function clearStoredSessionId2(projectId, dir) {
+  const file = sessionStorePath2(dir);
+  if (!fs5.existsSync(file)) {
+    return;
+  }
+  const store = readSessionStore2(dir);
+  if (String(projectId) in store) {
+    delete store[String(projectId)];
+    fs5.writeFileSync(file, JSON.stringify(store, null, 2) + `
+`, { mode: 384 });
+  }
+}
+function computeIdempotencyKey2(command, projectId, sql, args) {
+  if (EXECUTING_COMMANDS2.has(command)) {
+    const canonical = `${projectId}
+${command}
+${sql ?? ""}
+${JSON.stringify(args ?? null)}`;
+    return `joe-${crypto2.createHash("sha256").update(canonical).digest("hex")}`;
+  }
+  return `joe-${crypto2.randomUUID()}`;
+}
+var defaultSleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+async function runCommand2(params) {
+  const {
+    apiKey,
+    apiBaseUrl,
+    command,
+    projectId,
+    sql,
+    args,
+    sessionId,
+    debug
+  } = params;
+  const budgetMs = typeof params.budgetMs === "number" && Number.isFinite(params.budgetMs) ? params.budgetMs : DEFAULT_BUDGET_MS2;
+  const pollIntervalMs = params.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS2;
+  const now = params.now ?? Date.now;
+  const sleep = params.sleep ?? defaultSleep2;
+  const idempotencyKey = params.idempotencyKey ?? computeIdempotencyKey2(command, projectId, sql, args);
+  const submitted = await submitCommand2({
+    apiKey,
+    apiBaseUrl,
+    command,
+    projectId,
+    sql,
+    args,
+    sessionId,
+    idempotencyKey,
+    debug
+  });
+  const commandId = submitted.command_id;
+  const newSessionId = submitted.session_id ?? sessionId ?? null;
+  const deadline = now() + budgetMs;
+  let status = submitted.status;
+  while (true) {
+    const statusResp = await getCommandStatus2({ apiKey, apiBaseUrl, commandId, debug });
+    status = statusResp.status;
+    if (TERMINAL_STATES2.has(status)) {
+      break;
+    }
+    if (now() >= deadline) {
+      return { commandId, sessionId: newSessionId, status, result: null, budgetExpired: true };
+    }
+    await sleep(pollIntervalMs);
+  }
+  const result = await getCommandResult2({ apiKey, apiBaseUrl, commandId, debug });
+  return { commandId, sessionId: newSessionId, status, result, budgetExpired: false };
+}
+async function executeJoeCommand2(params) {
+  const projectId = await resolveProjectId2({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    project: params.project,
+    orgId: params.orgId,
+    debug: params.debug
+  });
+  let sessionId;
+  if (params.newSession) {
+    clearStoredSessionId2(projectId, params.sessionDir);
+    sessionId = null;
+  } else if (params.session) {
+    sessionId = String(params.session);
+  } else {
+    sessionId = readStoredSessionId2(projectId, params.sessionDir);
+  }
+  const outcome = await runCommand2({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    command: params.command,
+    projectId,
+    sql: params.sql,
+    args: params.args,
+    sessionId,
+    budgetMs: params.budgetMs,
+    pollIntervalMs: params.pollIntervalMs,
+    debug: params.debug,
+    now: params.now,
+    sleep: params.sleep
+  });
+  if (outcome.sessionId) {
+    writeStoredSessionId2(projectId, outcome.sessionId, params.sessionDir);
+  }
+  return { ...outcome, command: params.command, projectId };
+}
+function clientSidePlanFlags(planJson) {
+  const flags = [];
+  const walk = (node) => {
+    if (!node || typeof node !== "object") {
+      return;
+    }
+    const nodeType = node["Node Type"];
+    if (nodeType === "Seq Scan") {
+      const rel = node["Relation Name"];
+      flags.push(`client-side: Seq Scan${rel ? ` on ${rel}` : ""} — no index serves this predicate; consider adding one.`);
+    }
+    if (Array.isArray(node.Plans)) {
+      for (const child of node.Plans) {
+        walk(child);
+      }
+    }
+  };
+  if (planJson && typeof planJson === "object") {
+    const root = planJson;
+    walk(root.Plan ?? planJson);
+  }
+  return flags;
+}
+function formatJoeResult(command, result) {
+  const lines = [];
+  switch (command) {
+    case "plan":
+    case "explain": {
+      if (result.plan_text) {
+        lines.push(result.plan_text);
+      }
+      for (const flag of clientSidePlanFlags(result.plan_json)) {
+        lines.push(`⚑ ${flag}`);
+      }
+      if (result.queryid || result.plan_fingerprint) {
+        lines.push(`(queryid ${result.queryid ?? "?"} · plan_fp ${result.plan_fingerprint ?? "?"})`);
+      }
+      break;
+    }
+    case "exec": {
+      const notices = result.notices ?? [];
+      const rowCount = result.row_count ?? 0;
+      lines.push(`${notices.join(" ") || "OK"} · ${rowCount} row${rowCount === 1 ? "" : "s"}`);
+      if (result.result_rows && result.result_rows.length > 0) {
+        lines.push(JSON.stringify(result.result_rows, null, 2));
+      }
+      break;
+    }
+    case "hypo": {
+      lines.push(result.hypo_used ? "hypothetical index would be used" : "hypothetical index would NOT be used");
+      if (result.hypo_plan !== undefined) {
+        lines.push(JSON.stringify(result.hypo_plan, null, 2));
+      }
+      break;
+    }
+    case "activity":
+    case "describe": {
+      lines.push(JSON.stringify(result.snapshot ?? null, null, 2));
+      break;
+    }
+    case "terminate": {
+      lines.push(`terminated ${result.terminated ? "yes" : "no"} · pid ${result.pid ?? "?"}`);
+      break;
+    }
+    case "reset": {
+      lines.push(`reset ${result.reset ? "ok" : "no"}`);
+      break;
+    }
+  }
+  return lines.join(`
+`);
+}
+function formatProjectsTable(projects) {
+  const header = ["PROJECT_ID", "ALIAS", "PROJECT", "JOE", "TUNNEL"];
+  const rows = projects.map((p) => [
+    String(p.project_id),
+    p.alias ?? "-",
+    p.name ?? "-",
+    p.joe_ready ? "ready" : "no",
+    p.tunnel ? "yes" : "no"
+  ]);
+  const widths = header.map((h, i2) => Math.max(h.length, ...rows.map((r) => r[i2].length), 0));
+  const pad = (cells) => cells.map((c, i2) => c.padEnd(i2 === cells.length - 1 ? 0 : widths[i2])).join("  ").trimEnd();
+  return [pad(header), ...rows.map(pad)].join(`
+`);
+}
+
+// lib/dblab.ts
+function isNumericProjectRef4(ref) {
+  return /^[0-9]+$/.test(ref.trim());
+}
+async function resolveDblabInstanceId2(params) {
+  const { apiKey, apiBaseUrl, orgId, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  const ref = String(params.project ?? "").trim();
+  if (!ref) {
+    throw new Error("project is required (--project <id|alias>)");
+  }
+  let projects;
+  try {
+    projects = await listProjects({ apiKey, apiBaseUrl, orgId, debug });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to resolve project's DBLab instance: ${message}`);
+  }
+  const numeric = isNumericProjectRef4(ref);
+  const needle = ref.toLowerCase();
+  const match = projects.find((p) => {
+    if (numeric) {
+      return String(p.project_id) === ref;
+    }
+    return p.alias !== null && p.alias.toLowerCase() === needle || p.name !== null && p.name.toLowerCase() === needle || p.label !== null && p.label.toLowerCase() === needle;
+  });
+  if (!match) {
+    throw new Error(`No DBLab instance found for project '${ref}'. Run 'pgai projects' to see available projects.`);
+  }
+  if (match.dblab_instance_id == null) {
+    throw new Error(`Project '${ref}' has no active DBLab instance. Register a DBLab instance for it in the Console first.`);
+  }
+  return String(match.dblab_instance_id);
+}
+async function callDblabApi2(params) {
+  const { apiKey, apiBaseUrl, instanceId, action, method, data, operation, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!instanceId) {
+    throw new Error("instanceId is required");
+  }
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/dblab_api_call`);
+  const bodyObj = {
+    instance_id: instanceId,
+    action,
+    method
+  };
+  if (data !== undefined) {
+    bodyObj.data = data;
+  }
+  const body = JSON.stringify(bodyObj);
+  const headers = {
+    "access-token": apiKey,
+    "Content-Type": "application/json",
+    Connection: "close"
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.error(`Debug: POST URL: ${url.toString()}`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Request body: ${redactSecretsForLog(body)}`);
+  }
+  let response;
+  try {
+    response = await fetch(url.toString(), { method: "POST", headers, body });
+  } catch (err) {
+    throw new Error(describeFetchError(operation, base, err));
+  }
+  const text = await response.text();
+  if (debug) {
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response body: ${redactSecretsForLog(text)}`);
+  }
+  if (!response.ok) {
+    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
+  }
+  if (text.trim() === "") {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${operation}: failed to parse response: ${text}`);
+  }
+}
+async function createClone2(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, branch, snapshotId, dbUser, dbPassword, isProtected, debug } = params;
+  const data = { protected: Boolean(isProtected) };
+  if (cloneId)
+    data.id = cloneId;
+  if (branch)
+    data.branch = branch;
+  if (snapshotId)
+    data.snapshot = { id: snapshotId };
+  if (dbUser && dbPassword)
+    data.db = { username: dbUser, password: dbPassword };
+  return callDblabApi2({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: "/clone",
+    method: "post",
+    data,
+    operation: "Failed to create clone",
+    debug
+  });
+}
+async function listClones2(params) {
+  const { apiKey, apiBaseUrl, instanceId, debug } = params;
+  return callDblabApi2({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: "/clones",
+    method: "get",
+    operation: "Failed to list clones",
+    debug
+  });
+}
+async function getClone2(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, debug } = params;
+  if (!cloneId)
+    throw new Error("cloneId is required");
+  return callDblabApi2({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: `/clone/${encodeURIComponent(cloneId)}`,
+    method: "get",
+    operation: "Failed to get clone",
+    debug
+  });
+}
+async function resetClone2(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, snapshotId, latest, debug } = params;
+  if (!cloneId)
+    throw new Error("cloneId is required");
+  const data = { latest: latest ?? !snapshotId };
+  if (snapshotId)
+    data.snapshotID = snapshotId;
+  return callDblabApi2({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: `/clone/${encodeURIComponent(cloneId)}/reset`,
+    method: "post",
+    data,
+    operation: "Failed to reset clone",
+    debug
+  });
+}
+async function destroyClone2(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, debug } = params;
+  if (!cloneId)
+    throw new Error("cloneId is required");
+  return callDblabApi2({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: `/clone/${encodeURIComponent(cloneId)}`,
+    method: "delete",
+    operation: "Failed to destroy clone",
+    debug
+  });
+}
+async function listBranches2(params) {
+  const { apiKey, apiBaseUrl, instanceId, debug } = params;
+  return callDblabApi2({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: "/branches",
+    method: "get",
+    operation: "Failed to list branches",
+    debug
+  });
+}
+async function createBranch2(params) {
+  const { apiKey, apiBaseUrl, instanceId, branchName, baseBranch, snapshotId, debug } = params;
+  if (!branchName)
+    throw new Error("branchName is required");
+  const data = { branchName };
+  if (baseBranch)
+    data.baseBranch = baseBranch;
+  if (snapshotId)
+    data.snapshotID = snapshotId;
+  return callDblabApi2({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: "/branch",
+    method: "post",
+    data,
+    operation: "Failed to create branch",
+    debug
+  });
+}
+async function deleteBranch2(params) {
+  const { apiKey, apiBaseUrl, instanceId, branchName, debug } = params;
+  if (!branchName)
+    throw new Error("branchName is required");
+  return callDblabApi2({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: `/branch/${encodeURIComponent(branchName)}`,
+    method: "delete",
+    operation: "Failed to delete branch",
+    debug
+  });
+}
+async function branchLog2(params) {
+  const { apiKey, apiBaseUrl, instanceId, branchName, debug } = params;
+  if (!branchName)
+    throw new Error("branchName is required");
+  return callDblabApi2({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: `/branch/${encodeURIComponent(branchName)}/log`,
+    method: "get",
+    operation: "Failed to fetch branch log",
+    debug
+  });
+}
+async function listSnapshots2(params) {
+  const { apiKey, apiBaseUrl, instanceId, branchName, dataset, debug } = params;
+  const qs = new URLSearchParams;
+  const branch = branchName?.trim();
+  if (branch)
+    qs.append("branch", branch);
+  if (dataset)
+    qs.append("dataset", dataset);
+  const action = `/snapshots${qs.toString() ? `?${qs.toString()}` : ""}`;
+  return callDblabApi2({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action,
+    method: "get",
+    operation: "Failed to list snapshots",
+    debug
+  });
+}
+async function createSnapshot2(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, message, debug } = params;
+  if (!cloneId)
+    throw new Error("cloneId is required");
+  const data = { cloneID: cloneId };
+  if (message)
+    data.message = message;
+  return callDblabApi2({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: "/branch/snapshot",
+    method: "post",
+    data,
+    operation: "Failed to create snapshot",
+    debug
+  });
+}
+async function destroySnapshot2(params) {
+  const { apiKey, apiBaseUrl, instanceId, snapshotId, force, debug } = params;
+  if (!snapshotId)
+    throw new Error("snapshotId is required");
+  const action = `/snapshot/${snapshotId}?force=${Boolean(force)}`;
+  return callDblabApi2({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action,
+    method: "delete",
+    operation: "Failed to destroy snapshot",
+    debug
+  });
+}
+
 // bin/postgres-ai.ts
 init_util();
 
 // lib/instances.ts
-import * as fs4 from "fs";
+import * as fs6 from "fs";
 
 // node_modules/js-yaml/dist/js-yaml.mjs
 /*! js-yaml 4.1.1 https://github.com/nodeca/js-yaml @license MIT */
@@ -28470,11 +30393,11 @@ class InstancesParseError extends Error {
   }
 }
 function loadInstances(file) {
-  if (!fs4.existsSync(file))
+  if (!fs6.existsSync(file))
     return [];
-  if (fs4.lstatSync(file).isDirectory())
+  if (fs6.lstatSync(file).isDirectory())
     return [];
-  const text = fs4.readFileSync(file, "utf8");
+  const text = fs6.readFileSync(file, "utf8");
   if (text.trim() === "")
     return [];
   let parsed;
@@ -28652,8 +30575,8 @@ async function registerAasCollection(apiKey, instanceId, opts) {
 }
 
 // lib/storage.ts
-import * as fs5 from "fs";
-import * as path4 from "path";
+import * as fs7 from "fs";
+import * as path6 from "path";
 var MAX_UPLOAD_SIZE2 = 500 * 1024 * 1024;
 var MAX_DOWNLOAD_SIZE2 = 500 * 1024 * 1024;
 var MIME_TYPES2 = {
@@ -28694,11 +30617,11 @@ async function uploadFile2(params) {
   if (!filePath) {
     throw new Error("filePath is required");
   }
-  const resolvedPath = path4.resolve(filePath);
-  if (!fs5.existsSync(resolvedPath)) {
+  const resolvedPath = path6.resolve(filePath);
+  if (!fs7.existsSync(resolvedPath)) {
     throw new Error(`File not found: ${resolvedPath}`);
   }
-  const stat = fs5.statSync(resolvedPath);
+  const stat = fs7.statSync(resolvedPath);
   if (!stat.isFile()) {
     throw new Error(`Not a file: ${resolvedPath}`);
   }
@@ -28710,9 +30633,9 @@ async function uploadFile2(params) {
     console.error("Warning: storage URL uses HTTP — API key will be sent unencrypted");
   }
   const url = `${base}/upload`;
-  const fileBuffer = fs5.readFileSync(resolvedPath);
-  const fileName = path4.basename(resolvedPath);
-  const ext = path4.extname(fileName).toLowerCase();
+  const fileBuffer = fs7.readFileSync(resolvedPath);
+  const fileName = path6.basename(resolvedPath);
+  const ext = path6.extname(fileName).toLowerCase();
   const mimeType = MIME_TYPES2[ext] || "application/octet-stream";
   const formData = new FormData;
   formData.append("file", new Blob([fileBuffer], { type: mimeType }), fileName);
@@ -28771,15 +30694,15 @@ async function downloadFile2(params) {
     const relativePath = fileUrl.startsWith("/") ? fileUrl : `/${fileUrl}`;
     fullUrl = `${base}${relativePath}`;
   }
-  const urlFilename = path4.basename(new URL(fullUrl).pathname);
+  const urlFilename = path6.basename(new URL(fullUrl).pathname);
   if (!urlFilename) {
     throw new Error("Cannot derive filename from URL; please specify --output");
   }
-  const saveTo = outputPath ? path4.resolve(outputPath) : path4.resolve(urlFilename);
+  const saveTo = outputPath ? path6.resolve(outputPath) : path6.resolve(urlFilename);
   if (!outputPath) {
-    const normalizedSave = path4.normalize(saveTo);
-    const cwd = path4.normalize(process.cwd());
-    if (normalizedSave !== cwd && !normalizedSave.startsWith(cwd + path4.sep)) {
+    const normalizedSave = path6.normalize(saveTo);
+    const cwd = path6.normalize(process.cwd());
+    if (normalizedSave !== cwd && !normalizedSave.startsWith(cwd + path6.sep)) {
       throw new Error("Derived output path escapes current directory; please specify --output");
     }
   }
@@ -28811,11 +30734,11 @@ async function downloadFile2(params) {
   }
   const arrayBuffer = await response.arrayBuffer();
   const buffer = Buffer.from(arrayBuffer);
-  const parentDir = path4.dirname(saveTo);
-  if (!fs5.existsSync(parentDir)) {
-    fs5.mkdirSync(parentDir, { recursive: true });
+  const parentDir = path6.dirname(saveTo);
+  if (!fs7.existsSync(parentDir)) {
+    fs7.mkdirSync(parentDir, { recursive: true });
   }
-  fs5.writeFileSync(saveTo, buffer);
+  fs7.writeFileSync(saveTo, buffer);
   return {
     savedTo: saveTo,
     size: buffer.length,
@@ -28827,9 +30750,9 @@ function buildMarkdownLink2(fileUrl, storageBaseUrl, filename) {
   const base = normalizeBaseUrl(storageBaseUrl);
   const normalizedFileUrl = fileUrl.startsWith("/") ? fileUrl : `/${fileUrl}`;
   const fullUrl = fileUrl.startsWith("http://") || fileUrl.startsWith("https://") ? fileUrl : `${base}${normalizedFileUrl}`;
-  const name = filename || path4.basename(new URL(fullUrl).pathname);
+  const name = filename || path6.basename(new URL(fullUrl).pathname);
   const safeName = name.replace(/[\[\]()]/g, "\\$&");
-  const ext = path4.extname(name).toLowerCase();
+  const ext = path6.extname(name).toLowerCase();
   if (IMAGE_EXTENSIONS2.has(ext)) {
     return `![${safeName}](${fullUrl})`;
   }
@@ -28875,8 +30798,8 @@ ${links}`;
 // lib/init.ts
 import { randomBytes } from "crypto";
 import { URL as URL2, fileURLToPath } from "url";
-import * as fs6 from "fs";
-import * as path5 from "path";
+import * as fs8 from "fs";
+import * as path7 from "path";
 var DEFAULT_MONITORING_USER = "postgres_ai_mon";
 var KNOWN_PROVIDERS = ["self-managed", "supabase"];
 var SKIP_ROLE_CREATION_PROVIDERS = ["supabase"];
@@ -28968,21 +30891,21 @@ async function connectWithSslFallback(ClientClass, adminConn, verbose) {
 }
 function sqlDir() {
   const currentFile = fileURLToPath(import.meta.url);
-  const currentDir = path5.dirname(currentFile);
+  const currentDir = path7.dirname(currentFile);
   const candidates = [
-    path5.resolve(currentDir, "..", "sql"),
-    path5.resolve(currentDir, "..", "..", "sql")
+    path7.resolve(currentDir, "..", "sql"),
+    path7.resolve(currentDir, "..", "..", "sql")
   ];
   for (const candidate of candidates) {
-    if (fs6.existsSync(candidate)) {
+    if (fs8.existsSync(candidate)) {
       return candidate;
     }
   }
   throw new Error(`SQL directory not found. Searched: ${candidates.join(", ")}`);
 }
 function loadSqlTemplate(filename) {
-  const p = path5.join(sqlDir(), filename);
-  return fs6.readFileSync(p, "utf8");
+  const p = path7.join(sqlDir(), filename);
+  return fs8.readFileSync(p, "utf8");
 }
 function applyTemplate(sql, vars) {
   return sql.replace(/\{\{([A-Z0-9_]+)\}\}/g, (_, key) => {
@@ -29452,10 +31375,6 @@ async function verifyInitSetup(params) {
         }
       }
     }
-    const explainFnRes = await params.client.query("select has_function_privilege($1, 'postgres_ai.explain_generic(text, text, text)', 'EXECUTE') as ok", [role]);
-    if (!explainFnRes.rows?.[0]?.ok) {
-      missingRequired.push("EXECUTE on postgres_ai.explain_generic(text, text, text)");
-    }
     const tableDescribeFnRes = await params.client.query("select has_function_privilege($1, 'postgres_ai.table_describe(text)', 'EXECUTE') as ok", [role]);
     if (!tableDescribeFnRes.rows?.[0]?.ok) {
       missingRequired.push("EXECUTE on postgres_ai.table_describe(text)");
@@ -29974,15 +31893,6 @@ async function verifyInitSetupViaSupabase(params) {
       missingRequired.push("role search_path includes postgres_ai, public and pg_catalog");
     }
   }
-  const explainFnExistsRes = await params.client.query("SELECT oid FROM pg_proc WHERE proname = 'explain_generic' AND pronamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'postgres_ai')", true);
-  if (explainFnExistsRes.rowCount === 0) {
-    missingRequired.push("function postgres_ai.explain_generic exists");
-  } else {
-    const explainFnRes = await params.client.query(`SELECT has_function_privilege('${escapeLiteral2(role)}', 'postgres_ai.explain_generic(text, text, text)', 'EXECUTE') as ok`, true);
-    if (!explainFnRes.rows?.[0]?.ok) {
-      missingRequired.push("EXECUTE on postgres_ai.explain_generic(text, text, text)");
-    }
-  }
   const tableDescribeFnExistsRes = await params.client.query("SELECT oid FROM pg_proc WHERE proname = 'table_describe' AND pronamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'postgres_ai')", true);
   if (tableDescribeFnExistsRes.rowCount === 0) {
     missingRequired.push("function postgres_ai.table_describe exists");
@@ -30040,9 +31950,9 @@ function escapeLiteral2(value) {
 }
 
 // lib/pkce.ts
-import * as crypto from "crypto";
+import * as crypto3 from "crypto";
 function generateRandomString(length = 64) {
-  const bytes = crypto.randomBytes(length);
+  const bytes = crypto3.randomBytes(length);
   return base64URLEncode(bytes);
 }
 function base64URLEncode(buffer) {
@@ -30052,7 +31962,7 @@ function generateCodeVerifier() {
   return generateRandomString(32);
 }
 function generateCodeChallenge(verifier) {
-  const hash = crypto.createHash("sha256").update(verifier).digest();
+  const hash = crypto3.createHash("sha256").update(verifier).digest();
   return base64URLEncode(hash);
 }
 function generateState() {
@@ -30281,8 +32191,8 @@ import { createInterface } from "readline";
 import * as childProcess from "child_process";
 
 // lib/checkup.ts
-import * as fs7 from "fs";
-import * as path6 from "path";
+import * as fs9 from "fs";
+import * as path8 from "path";
 
 // lib/metrics-embedded.ts
 var METRICS = {
@@ -32013,7 +33923,7 @@ function buildCheckInfoMap() {
 }
 
 // lib/checkup.ts
-var __dirname = "/builds/postgres-ai/postgresai/cli/lib";
+var __dirname = "/home/agent/workspace/postgresai-joe-v2/cli/lib";
 var SECONDS_PER_DAY = 86400;
 var SECONDS_PER_HOUR = 3600;
 var SECONDS_PER_MINUTE = 60;
@@ -32499,7 +34409,7 @@ function createBaseReport(checkId, checkTitle, nodeName) {
 }
 function readTextFileSafe(p) {
   try {
-    const value = fs7.readFileSync(p, "utf8").trim();
+    const value = fs9.readFileSync(p, "utf8").trim();
     return value || null;
   } catch {
     return null;
@@ -32512,8 +34422,8 @@ function resolveBuildTs() {
   if (fromFile)
     return fromFile;
   try {
-    const pkgRoot = path6.resolve(__dirname, "..");
-    const fromPkgFile = readTextFileSafe(path6.join(pkgRoot, "BUILD_TS"));
+    const pkgRoot = path8.resolve(__dirname, "..");
+    const fromPkgFile = readTextFileSafe(path8.join(pkgRoot, "BUILD_TS"));
     if (fromPkgFile)
       return fromPkgFile;
   } catch (err) {
@@ -32521,8 +34431,8 @@ function resolveBuildTs() {
     console.warn(`[resolveBuildTs] Warning: path resolution failed: ${errorMsg}`);
   }
   try {
-    const pkgJsonPath = path6.resolve(__dirname, "..", "package.json");
-    const st = fs7.statSync(pkgJsonPath);
+    const pkgJsonPath = path8.resolve(__dirname, "..", "package.json");
+    const st = fs9.statSync(pkgJsonPath);
     return st.mtime.toISOString();
   } catch (err) {
     if (process.env.DEBUG) {
@@ -33803,7 +35713,7 @@ function summarizeG003(nodeData) {
 }
 
 // lib/instances.ts
-import * as fs8 from "fs";
+import * as fs10 from "fs";
 class InstancesParseError2 extends Error {
   constructor(file, cause) {
     const causeMsg = cause instanceof Error ? cause.message : String(cause);
@@ -33812,11 +35722,11 @@ class InstancesParseError2 extends Error {
   }
 }
 function loadInstances2(file) {
-  if (!fs8.existsSync(file))
+  if (!fs10.existsSync(file))
     return [];
-  if (fs8.lstatSync(file).isDirectory())
+  if (fs10.lstatSync(file).isDirectory())
     return [];
-  const text = fs8.readFileSync(file, "utf8");
+  const text = fs10.readFileSync(file, "utf8");
   if (text.trim() === "")
     return [];
   let parsed;
@@ -33849,22 +35759,22 @@ function buildInstance(name, connStr) {
   };
 }
 function addInstanceToFile(file, instance) {
-  if (fs8.existsSync(file) && fs8.lstatSync(file).isDirectory()) {
-    fs8.rmSync(file, { recursive: true, force: true });
+  if (fs10.existsSync(file) && fs10.lstatSync(file).isDirectory()) {
+    fs10.rmSync(file, { recursive: true, force: true });
   }
   const existing = loadInstances2(file);
   if (existing.some((i3) => i3.name === instance.name)) {
     throw new Error(`Monitoring target '${instance.name}' already exists`);
   }
   existing.push(instance);
-  fs8.writeFileSync(file, dump2(existing), "utf8");
+  fs10.writeFileSync(file, dump2(existing), "utf8");
 }
 function removeInstanceFromFile(file, name) {
   const instances = loadInstances2(file);
   const filtered = instances.filter((i3) => i3.name !== name);
   if (filtered.length === instances.length)
     return false;
-  fs8.writeFileSync(file, dump2(filtered), "utf8");
+  fs10.writeFileSync(file, dump2(filtered), "utf8");
   return true;
 }
 function extractSslmode(connStr) {
@@ -33959,13 +35869,13 @@ function stripMatchingQuotes(value) {
   return trimmed;
 }
 var REQUIRED_ENV_KEYS = [
-  { key: "REPLICATOR_PASSWORD", defaultValue: () => crypto2.randomBytes(32).toString("hex"), introducedIn: "0.13" },
+  { key: "REPLICATOR_PASSWORD", defaultValue: () => crypto4.randomBytes(32).toString("hex"), introducedIn: "0.13" },
   { key: "VM_AUTH_USERNAME", defaultValue: () => "vmauth", introducedIn: "0.15" },
-  { key: "VM_AUTH_PASSWORD", defaultValue: () => crypto2.randomBytes(18).toString("base64"), introducedIn: "0.15" }
+  { key: "VM_AUTH_PASSWORD", defaultValue: () => crypto4.randomBytes(18).toString("base64"), introducedIn: "0.15" }
 ];
 function ensureRequiredEnvVars(projectDir) {
-  const envFile = path7.resolve(projectDir, ".env");
-  const existing = fs9.existsSync(envFile) ? fs9.readFileSync(envFile, "utf8") : "";
+  const envFile = path9.resolve(projectDir, ".env");
+  const existing = fs11.existsSync(envFile) ? fs11.readFileSync(envFile, "utf8") : "";
   const added = [];
   const appendLines = [];
   for (const spec of REQUIRED_ENV_KEYS) {
@@ -33984,7 +35894,7 @@ function ensureRequiredEnvVars(projectDir) {
 ` : "") + appendLines.join(`
 `) + `
 `;
-  fs9.writeFileSync(envFile, newContent, { encoding: "utf8", mode: 384 });
+  fs11.writeFileSync(envFile, newContent, { encoding: "utf8", mode: 384 });
   return added;
 }
 async function execFilePromise(file, args) {
@@ -34049,7 +35959,7 @@ function expandHomePath(p) {
   if (s === "~")
     return os3.homedir();
   if (s.startsWith("~/") || s.startsWith("~\\")) {
-    return path7.join(os3.homedir(), s.slice(2));
+    return path9.join(os3.homedir(), s.slice(2));
   }
   return s;
 }
@@ -34098,10 +36008,10 @@ function prepareOutputDirectory(outputOpt) {
   if (!outputOpt)
     return;
   const outputDir = expandHomePath(outputOpt);
-  const outputPath = path7.isAbsolute(outputDir) ? outputDir : path7.resolve(process.cwd(), outputDir);
-  if (!fs9.existsSync(outputPath)) {
+  const outputPath = path9.isAbsolute(outputDir) ? outputDir : path9.resolve(process.cwd(), outputDir);
+  if (!fs11.existsSync(outputPath)) {
     try {
-      fs9.mkdirSync(outputPath, { recursive: true });
+      fs11.mkdirSync(outputPath, { recursive: true });
     } catch (e) {
       const errAny = e;
       const code = typeof errAny?.code === "string" ? errAny.code : "";
@@ -34137,7 +36047,7 @@ function prepareUploadConfig(opts, rootOpts, shouldUpload, uploadExplicitlyReque
   let project = (opts.project || cfg.defaultProject || "").trim();
   let projectWasGenerated = false;
   if (!project) {
-    project = `project_${crypto2.randomBytes(6).toString("hex")}`;
+    project = `project_${crypto4.randomBytes(6).toString("hex")}`;
     projectWasGenerated = true;
     try {
       writeConfig({ defaultProject: project });
@@ -34183,8 +36093,8 @@ async function uploadCheckupReports(uploadCfg, reports, spinner, logUpload) {
 }
 function writeReportFiles(reports, outputPath) {
   for (const [checkId, report] of Object.entries(reports)) {
-    const filePath = path7.join(outputPath, `${checkId}.json`);
-    fs9.writeFileSync(filePath, JSON.stringify(report, null, 2), "utf8");
+    const filePath = path9.join(outputPath, `${checkId}.json`);
+    fs11.writeFileSync(filePath, JSON.stringify(report, null, 2), "utf8");
     const title = report.checkTitle || checkId;
     console.log(`\u2713 ${checkId} ${title}: ${filePath}`);
   }
@@ -34229,7 +36139,7 @@ function getDefaultMonitoringProjectDir() {
   const override = process.env.PGAI_PROJECT_DIR;
   if (override && override.trim())
     return override.trim();
-  return path7.join(getConfigDir(), "monitoring");
+  return path9.join(getConfigDir(), "monitoring");
 }
 async function downloadText(url) {
   const controller = new AbortController;
@@ -34246,12 +36156,12 @@ async function downloadText(url) {
 }
 async function ensureDefaultMonitoringProject() {
   const projectDir = getDefaultMonitoringProjectDir();
-  const composeFile = path7.resolve(projectDir, "docker-compose.yml");
-  const instancesFile = path7.resolve(projectDir, "instances.yml");
-  if (!fs9.existsSync(projectDir)) {
-    fs9.mkdirSync(projectDir, { recursive: true, mode: 448 });
+  const composeFile = path9.resolve(projectDir, "docker-compose.yml");
+  const instancesFile = path9.resolve(projectDir, "instances.yml");
+  if (!fs11.existsSync(projectDir)) {
+    fs11.mkdirSync(projectDir, { recursive: true, mode: 448 });
   }
-  if (!fs9.existsSync(composeFile)) {
+  if (!fs11.existsSync(composeFile)) {
     const refs = [
       process.env.PGAI_PROJECT_REF,
       package_default.version,
@@ -34263,39 +36173,39 @@ async function ensureDefaultMonitoringProject() {
       const url = `https://gitlab.com/postgres-ai/postgres_ai/-/raw/${encodeURIComponent(ref)}/docker-compose.yml`;
       try {
         const text = await downloadText(url);
-        fs9.writeFileSync(composeFile, text, { encoding: "utf8", mode: 384 });
+        fs11.writeFileSync(composeFile, text, { encoding: "utf8", mode: 384 });
         break;
       } catch (err) {
         lastErr = err;
       }
     }
-    if (!fs9.existsSync(composeFile)) {
+    if (!fs11.existsSync(composeFile)) {
       const msg = lastErr instanceof Error ? lastErr.message : String(lastErr);
       throw new Error(`Failed to bootstrap docker-compose.yml: ${msg}`);
     }
   }
-  if (fs9.existsSync(instancesFile) && fs9.lstatSync(instancesFile).isDirectory()) {
-    fs9.rmSync(instancesFile, { recursive: true, force: true });
+  if (fs11.existsSync(instancesFile) && fs11.lstatSync(instancesFile).isDirectory()) {
+    fs11.rmSync(instancesFile, { recursive: true, force: true });
   }
-  if (!fs9.existsSync(instancesFile)) {
+  if (!fs11.existsSync(instancesFile)) {
     const header = `# PostgreSQL instances to monitor
 ` + `# Add your instances using: pgai mon targets add <connection-string> <name>
 
 `;
-    fs9.writeFileSync(instancesFile, header, { encoding: "utf8", mode: 384 });
+    fs11.writeFileSync(instancesFile, header, { encoding: "utf8", mode: 384 });
   }
-  const pgwatchConfig = path7.resolve(projectDir, ".pgwatch-config");
-  if (!fs9.existsSync(pgwatchConfig)) {
-    fs9.writeFileSync(pgwatchConfig, "", { encoding: "utf8", mode: 384 });
+  const pgwatchConfig = path9.resolve(projectDir, ".pgwatch-config");
+  if (!fs11.existsSync(pgwatchConfig)) {
+    fs11.writeFileSync(pgwatchConfig, "", { encoding: "utf8", mode: 384 });
   }
-  const envFile = path7.resolve(projectDir, ".env");
-  if (!fs9.existsSync(envFile)) {
+  const envFile = path9.resolve(projectDir, ".env");
+  if (!fs11.existsSync(envFile)) {
     const envText = `PGAI_TAG=${package_default.version}
 # PGAI_REGISTRY=registry.gitlab.com/postgres-ai/postgres_ai
 `;
-    fs9.writeFileSync(envFile, envText, { encoding: "utf8", mode: 384 });
+    fs11.writeFileSync(envFile, envText, { encoding: "utf8", mode: 384 });
   }
-  return { fs: fs9, path: path7, projectDir, composeFile, instancesFile };
+  return { fs: fs11, path: path9, projectDir, composeFile, instancesFile };
 }
 function sanitizeTagForBackup(tag) {
   if (tag == null)
@@ -34304,10 +36214,10 @@ function sanitizeTagForBackup(tag) {
   return /^[A-Za-z0-9._-]{1,64}$/.test(stripped) ? stripped : null;
 }
 function readDeployedTag(projectDir) {
-  const envFile = path7.resolve(projectDir, ".env");
-  if (!fs9.existsSync(envFile))
+  const envFile = path9.resolve(projectDir, ".env");
+  if (!fs11.existsSync(envFile))
     return null;
-  const m = fs9.readFileSync(envFile, "utf8").match(/^PGAI_TAG=(.+)$/m);
+  const m = fs11.readFileSync(envFile, "utf8").match(/^PGAI_TAG=(.+)$/m);
   return m ? sanitizeTagForBackup(m[1]) : null;
 }
 function isValidComposeYaml(text) {
@@ -34344,10 +36254,10 @@ function composeContentEqual(a, b) {
   return a.replace(/\s+$/, "") === b.replace(/\s+$/, "");
 }
 async function refreshBundledComposeIfStale(projectDir, oldTag) {
-  if (fs9.existsSync(path7.resolve(projectDir, ".git")))
+  if (fs11.existsSync(path9.resolve(projectDir, ".git")))
     return false;
-  const composeFile = path7.resolve(projectDir, "docker-compose.yml");
-  if (!fs9.existsSync(composeFile))
+  const composeFile = path9.resolve(projectDir, "docker-compose.yml");
+  if (!fs11.existsSync(composeFile))
     return false;
   const refs = [
     process.env.PGAI_PROJECT_REF,
@@ -34360,24 +36270,24 @@ async function refreshBundledComposeIfStale(projectDir, oldTag) {
     console.error("  Keeping the existing compose. If dashboards are blank after upgrade, re-run this command once network is available.");
     return false;
   }
-  const existing = fs9.readFileSync(composeFile, "utf8");
+  const existing = fs11.readFileSync(composeFile, "utf8");
   if (composeContentEqual(existing, fetched))
     return false;
   const deployedTag = sanitizeTagForBackup(oldTag ?? readDeployedTag(projectDir));
   const tagPart = deployedTag ?? new Date().toISOString().replace(/[:.]/g, "-");
-  const oldHash = crypto2.createHash("sha256").update(existing).digest("hex").slice(0, 8);
-  const backup = path7.resolve(projectDir, `docker-compose.yml.bak-${tagPart}-${oldHash}`);
+  const oldHash = crypto4.createHash("sha256").update(existing).digest("hex").slice(0, 8);
+  const backup = path9.resolve(projectDir, `docker-compose.yml.bak-${tagPart}-${oldHash}`);
   let backupName = null;
   try {
-    fs9.writeFileSync(backup, existing, { encoding: "utf8", mode: 384, flag: "wx" });
-    backupName = path7.basename(backup);
+    fs11.writeFileSync(backup, existing, { encoding: "utf8", mode: 384, flag: "wx" });
+    backupName = path9.basename(backup);
   } catch (err) {
     const e = err;
     if (e && e.code === "EEXIST") {
-      backupName = path7.basename(backup);
+      backupName = path9.basename(backup);
     }
   }
-  fs9.writeFileSync(composeFile, fetched, { encoding: "utf8", mode: 384 });
+  fs11.writeFileSync(composeFile, fetched, { encoding: "utf8", mode: 384 });
   const backupNote = backupName ? ` (backup: ${backupName})` : "";
   console.log(`\u2713 Refreshed docker-compose.yml to ${package_default.version}${backupNote}`);
   return true;
@@ -35611,12 +37521,12 @@ function resolvePaths() {
   const startDir = process.cwd();
   let currentDir = startDir;
   while (true) {
-    const composeFile = path7.resolve(currentDir, "docker-compose.yml");
-    if (fs9.existsSync(composeFile)) {
-      const instancesFile = path7.resolve(currentDir, "instances.yml");
-      return { fs: fs9, path: path7, projectDir: currentDir, composeFile, instancesFile };
+    const composeFile = path9.resolve(currentDir, "docker-compose.yml");
+    if (fs11.existsSync(composeFile)) {
+      const instancesFile = path9.resolve(currentDir, "instances.yml");
+      return { fs: fs11, path: path9, projectDir: currentDir, composeFile, instancesFile };
     }
-    const parentDir = path7.dirname(currentDir);
+    const parentDir = path9.dirname(currentDir);
     if (parentDir === currentDir)
       break;
     currentDir = parentDir;
@@ -35659,6 +37569,16 @@ function checkRunningContainers() {
     return { running: false, containers: [] };
   }
 }
+function planMonitoringRegistration(args) {
+  const projectName = args.project?.trim() || undefined;
+  if (args.instanceId) {
+    return { kind: "adopt", projectName };
+  }
+  if (!projectName) {
+    return { kind: "error-missing-project", projectName: undefined };
+  }
+  return { kind: "self-register", projectName };
+}
 async function registerMonitoringInstance(apiKey, projectName, opts) {
   const { apiBaseUrl } = resolveBaseUrls2(opts);
   const url = `${apiBaseUrl}/rpc/monitoring_instance_register`;
@@ -35666,16 +37586,19 @@ async function registerMonitoringInstance(apiKey, projectName, opts) {
   const instanceId = opts?.instanceId;
   const retries = opts?.retries ?? (instanceId ? 1 : 0);
   const retryDelayMs = opts?.retryDelayMs ?? 400;
+  const hasProjectName = !!(projectName && projectName.trim());
   if (debug) {
     console.error(`
 Debug: Registering monitoring instance...`);
     console.error(`Debug: POST ${url}`);
-    console.error(`Debug: project_name=${projectName}${instanceId ? ` instance_id=${instanceId}` : ""}`);
+    console.error(`Debug: ${hasProjectName ? `project_name=${projectName}` : "project_name=(omitted)"}${instanceId ? ` instance_id=${instanceId}` : ""}`);
   }
   const requestBody = {
-    api_token: apiKey,
-    project_name: projectName
+    api_token: apiKey
   };
+  if (hasProjectName) {
+    requestBody.project_name = projectName;
+  }
   if (instanceId) {
     requestBody.instance_id = instanceId;
   }
@@ -35735,10 +37658,10 @@ function resolveAdoptedProject(reg) {
 }
 function updatePgwatchConfig(configPath, updates) {
   let lines = [];
-  if (fs9.existsSync(configPath)) {
-    const stats = fs9.statSync(configPath);
+  if (fs11.existsSync(configPath)) {
+    const stats = fs11.statSync(configPath);
     if (!stats.isDirectory()) {
-      const content = fs9.readFileSync(configPath, "utf8");
+      const content = fs11.readFileSync(configPath, "utf8");
       lines = content.split(/\r?\n/).filter((l) => l.trim() !== "");
     }
   }
@@ -35750,7 +37673,7 @@ function updatePgwatchConfig(configPath, updates) {
       lines.push(`${key}=${value}`);
     }
   }
-  fs9.writeFileSync(configPath, lines.join(`
+  fs11.writeFileSync(configPath, lines.join(`
 `) + `
 `, { encoding: "utf8", mode: 384 });
 }
@@ -35788,12 +37711,12 @@ async function runCompose(args, grafanaPassword) {
   if (grafanaPassword) {
     env.GF_SECURITY_ADMIN_PASSWORD = grafanaPassword;
   } else {
-    const cfgPath = path7.resolve(projectDir, ".pgwatch-config");
-    if (fs9.existsSync(cfgPath)) {
+    const cfgPath = path9.resolve(projectDir, ".pgwatch-config");
+    if (fs11.existsSync(cfgPath)) {
       try {
-        const stats = fs9.statSync(cfgPath);
+        const stats = fs11.statSync(cfgPath);
         if (!stats.isDirectory()) {
-          const content = fs9.readFileSync(cfgPath, "utf8");
+          const content = fs11.readFileSync(cfgPath, "utf8");
           const match = content.match(/^grafana_password=([^\r\n]+)/m);
           if (match) {
             env.GF_SECURITY_ADMIN_PASSWORD = match[1].trim();
@@ -35806,10 +37729,10 @@ async function runCompose(args, grafanaPassword) {
       }
     }
   }
-  const envFilePath = path7.resolve(projectDir, ".env");
-  if (fs9.existsSync(envFilePath)) {
+  const envFilePath = path9.resolve(projectDir, ".env");
+  if (fs11.existsSync(envFilePath)) {
     try {
-      const envContent = fs9.readFileSync(envFilePath, "utf8");
+      const envContent = fs11.readFileSync(envFilePath, "utf8");
       if (!env.VM_AUTH_USERNAME) {
         const m = envContent.match(/^VM_AUTH_USERNAME=([^\r\n]+)/m);
         if (m)
@@ -35866,20 +37789,20 @@ mon.command("local-install").description("install local monitoring stack (genera
   console.log(`Project directory: ${projectDir}
 `);
   if (opts.project) {
-    const cfgPath2 = path7.resolve(projectDir, ".pgwatch-config");
+    const cfgPath2 = path9.resolve(projectDir, ".pgwatch-config");
     updatePgwatchConfig(cfgPath2, { project_name: opts.project });
     console.log(`Using project name: ${opts.project}
 `);
   }
-  const envFile = path7.resolve(projectDir, ".env");
+  const envFile = path9.resolve(projectDir, ".env");
   let existingRegistry = null;
   let existingPassword = null;
   let existingReplicatorPassword = null;
   let existingVmAuthUsername = null;
   let existingVmAuthPassword = null;
   let previousTag = null;
-  if (fs9.existsSync(envFile)) {
-    const existingEnv = fs9.readFileSync(envFile, "utf8");
+  if (fs11.existsSync(envFile)) {
+    const existingEnv = fs11.readFileSync(envFile, "utf8");
     const previousTagMatch = existingEnv.match(/^PGAI_TAG=(.+)$/m);
     if (previousTagMatch)
       previousTag = previousTagMatch[1].trim();
@@ -35907,10 +37830,10 @@ mon.command("local-install").description("install local monitoring stack (genera
   if (existingPassword) {
     envLines.push(`GF_SECURITY_ADMIN_PASSWORD=${existingPassword}`);
   }
-  envLines.push(`REPLICATOR_PASSWORD=${existingReplicatorPassword || crypto2.randomBytes(32).toString("hex")}`);
+  envLines.push(`REPLICATOR_PASSWORD=${existingReplicatorPassword || crypto4.randomBytes(32).toString("hex")}`);
   envLines.push(`VM_AUTH_USERNAME=${existingVmAuthUsername || "vmauth"}`);
-  envLines.push(`VM_AUTH_PASSWORD=${existingVmAuthPassword || crypto2.randomBytes(18).toString("base64")}`);
-  fs9.writeFileSync(envFile, envLines.join(`
+  envLines.push(`VM_AUTH_PASSWORD=${existingVmAuthPassword || crypto4.randomBytes(18).toString("base64")}`);
+  fs11.writeFileSync(envFile, envLines.join(`
 `) + `
 `, { encoding: "utf8", mode: 384 });
   await refreshBundledComposeIfStale(projectDir, previousTag);
@@ -35947,7 +37870,7 @@ Use demo mode without API key: postgres-ai mon local-install --demo`);
     if (apiKey) {
       console.log("Using API key provided via --api-key parameter");
       writeConfig({ apiKey });
-      updatePgwatchConfig(path7.resolve(projectDir, ".pgwatch-config"), { api_key: apiKey });
+      updatePgwatchConfig(path9.resolve(projectDir, ".pgwatch-config"), { api_key: apiKey });
       console.log(`\u2713 API key saved
 `);
     } else if (opts.yes) {
@@ -35964,7 +37887,7 @@ Use demo mode without API key: postgres-ai mon local-install --demo`);
           const trimmedKey = inputApiKey.trim();
           if (trimmedKey) {
             writeConfig({ apiKey: trimmedKey });
-            updatePgwatchConfig(path7.resolve(projectDir, ".pgwatch-config"), { api_key: trimmedKey });
+            updatePgwatchConfig(path9.resolve(projectDir, ".pgwatch-config"), { api_key: trimmedKey });
             apiKey = trimmedKey;
             console.log(`\u2713 API key saved
 `);
@@ -35998,7 +37921,7 @@ Use demo mode without API key: postgres-ai mon local-install --demo`);
 # Add your instances using: postgres-ai mon targets add
 
 `;
-    fs9.writeFileSync(instancesPath2, emptyInstancesContent, "utf8");
+    fs11.writeFileSync(instancesPath2, emptyInstancesContent, "utf8");
     console.log(`Instances file: ${instancesPath2}`);
     console.log(`Project directory: ${projectDir2}
 `);
@@ -36102,17 +38025,17 @@ You can provide either:`);
     }
   } else {
     console.log("Step 2: Demo mode enabled - using included demo PostgreSQL database");
-    const currentDir = path7.dirname(fileURLToPath2(import.meta.url));
+    const currentDir = path9.dirname(fileURLToPath2(import.meta.url));
     const demoCandidates = [
-      path7.resolve(currentDir, "..", "..", "instances.demo.yml"),
-      path7.resolve(currentDir, "..", "..", "..", "instances.demo.yml")
+      path9.resolve(currentDir, "..", "..", "instances.demo.yml"),
+      path9.resolve(currentDir, "..", "..", "..", "instances.demo.yml")
     ];
-    const demoSrc = demoCandidates.find((p) => fs9.existsSync(p));
+    const demoSrc = demoCandidates.find((p) => fs11.existsSync(p));
     if (demoSrc) {
-      if (fs9.existsSync(instancesPath) && fs9.lstatSync(instancesPath).isDirectory()) {
-        fs9.rmSync(instancesPath, { recursive: true, force: true });
+      if (fs11.existsSync(instancesPath) && fs11.lstatSync(instancesPath).isDirectory()) {
+        fs11.rmSync(instancesPath, { recursive: true, force: true });
       }
-      fs9.copyFileSync(demoSrc, instancesPath);
+      fs11.copyFileSync(demoSrc, instancesPath);
       console.log(`\u2713 Demo monitoring target configured
 `);
     } else {
@@ -36131,15 +38054,15 @@ Searched: ${demoCandidates.join(", ")}
   console.log(`\u2713 Configuration updated
 `);
   console.log(opts.demo ? "Step 4: Configuring Grafana security..." : "Step 4: Configuring Grafana security...");
-  const cfgPath = path7.resolve(projectDir, ".pgwatch-config");
+  const cfgPath = path9.resolve(projectDir, ".pgwatch-config");
   let grafanaPassword = "";
   let vmAuthUsername = "";
   let vmAuthPassword = "";
   try {
-    if (fs9.existsSync(cfgPath)) {
-      const stats = fs9.statSync(cfgPath);
+    if (fs11.existsSync(cfgPath)) {
+      const stats = fs11.statSync(cfgPath);
       if (!stats.isDirectory()) {
-        const content = fs9.readFileSync(cfgPath, "utf8");
+        const content = fs11.readFileSync(cfgPath, "utf8");
         const match = content.match(/^grafana_password=([^\r\n]+)/m);
         if (match) {
           grafanaPassword = match[1].trim();
@@ -36151,15 +38074,15 @@ Searched: ${demoCandidates.join(", ")}
       const { stdout: password } = await execFilePromise("openssl", ["rand", "-base64", "12"]);
       grafanaPassword = password.trim().replace(/\n/g, "");
       let configContent = "";
-      if (fs9.existsSync(cfgPath)) {
-        const stats = fs9.statSync(cfgPath);
+      if (fs11.existsSync(cfgPath)) {
+        const stats = fs11.statSync(cfgPath);
         if (!stats.isDirectory()) {
-          configContent = fs9.readFileSync(cfgPath, "utf8");
+          configContent = fs11.readFileSync(cfgPath, "utf8");
         }
       }
       const lines = configContent.split(/\r?\n/).filter((l) => !/^grafana_password=/.test(l));
       lines.push(`grafana_password=${grafanaPassword}`);
-      fs9.writeFileSync(cfgPath, lines.filter(Boolean).join(`
+      fs11.writeFileSync(cfgPath, lines.filter(Boolean).join(`
 `) + `
 `, "utf8");
     }
@@ -36172,9 +38095,9 @@ Searched: ${demoCandidates.join(", ")}
     grafanaPassword = "demo";
   }
   try {
-    const envFile2 = path7.resolve(projectDir, ".env");
-    if (fs9.existsSync(envFile2)) {
-      const envContent = fs9.readFileSync(envFile2, "utf8");
+    const envFile2 = path9.resolve(projectDir, ".env");
+    if (fs11.existsSync(envFile2)) {
+      const envContent = fs11.readFileSync(envFile2, "utf8");
       const userMatch = envContent.match(/^VM_AUTH_USERNAME=([^\r\n]+)/m);
       const passMatch = envContent.match(/^VM_AUTH_PASSWORD=([^\r\n]+)/m);
       if (userMatch)
@@ -36190,13 +38113,13 @@ Searched: ${demoCandidates.join(", ")}
         vmAuthPassword = vmPass.trim().replace(/\n/g, "");
       }
       let envContent = "";
-      if (fs9.existsSync(envFile2)) {
-        envContent = fs9.readFileSync(envFile2, "utf8");
+      if (fs11.existsSync(envFile2)) {
+        envContent = fs11.readFileSync(envFile2, "utf8");
       }
       const envLines2 = envContent.split(/\r?\n/).filter((l) => !/^VM_AUTH_USERNAME=/.test(l) && !/^VM_AUTH_PASSWORD=/.test(l)).filter((l, i3, arr) => !(i3 === arr.length - 1 && l === ""));
       envLines2.push(`VM_AUTH_USERNAME=${vmAuthUsername}`);
       envLines2.push(`VM_AUTH_PASSWORD=${vmAuthPassword}`);
-      fs9.writeFileSync(envFile2, envLines2.join(`
+      fs11.writeFileSync(envFile2, envLines2.join(`
 `) + `
 `, { encoding: "utf8", mode: 384 });
     }
@@ -36218,8 +38141,9 @@ Searched: ${demoCandidates.join(", ")}
   console.log(`\u2713 Services started
 `);
   if (apiKey && !opts.demo) {
-    const projectName = opts.project || "postgres-ai-monitoring";
     const instanceId = opts.instanceId || process.env.PGAI_INSTANCE_ID;
+    const plan = planMonitoringRegistration({ project: opts.project, instanceId });
+    const projectName = plan.projectName;
     if (instanceId) {
       const reg = await registerMonitoringInstance(apiKey, projectName, {
         apiBaseUrl: globalOpts.apiBaseUrl,
@@ -36228,16 +38152,16 @@ Searched: ${demoCandidates.join(", ")}
       });
       const adoptedProject = resolveAdoptedProject(reg);
       if (adoptedProject != null) {
-        updatePgwatchConfig(path7.resolve(projectDir, ".pgwatch-config"), {
+        updatePgwatchConfig(path9.resolve(projectDir, ".pgwatch-config"), {
           project_name: adoptedProject
         });
         const verb = reg?.created ? "Registered" : "Adopted";
         console.log(`\u2713 ${verb} monitoring instance (project: ${adoptedProject})
 `);
       } else if (reg) {
-        console.error(`\u26A0 Adopted provisioned instance ${instanceId} but the platform returned no project \u2014 reports will use project '${projectName}'`);
+        console.error(`\u26A0 Adopted provisioned instance ${instanceId} but the platform returned no project` + (projectName ? ` \u2014 reports will use project '${projectName}'` : ` \u2014 reports will have no project until 'postgresai mon local-install' is re-run with --project <name>`));
       } else {
-        console.error(`\u26A0 Could not adopt provisioned instance ${instanceId} \u2014 reports will use project '${projectName}' until 'postgresai mon local-install' is re-run`);
+        console.error(`\u26A0 Could not adopt provisioned instance ${instanceId}` + (projectName ? ` \u2014 reports will use project '${projectName}' until 'postgresai mon local-install' is re-run` : ` \u2014 reports will have no project until 'postgresai mon local-install' is re-run with --project <name>`));
       }
       const aas = await registerAasCollection(apiKey, instanceId, {
         grafanaPassword,
@@ -36253,6 +38177,9 @@ Searched: ${demoCandidates.join(", ")}
         console.error(`\u26A0 AAS auto-collection not registered (${aas.reason}); it can be enabled later by re-running 'postgresai mon local-install'
 `);
       }
+    } else if (plan.kind === "error-missing-project") {
+      console.error("\u2717 A project name is required for self-registration (the 'postgres-ai-monitoring' default was removed). " + "Re-run with --project <name>, or adopt a console-provisioned instance with --instance-id <uuid>.");
+      process.exitCode = 1;
     } else {
       registerMonitoringInstance(apiKey, projectName, {
         apiBaseUrl: globalOpts.apiBaseUrl,
@@ -36441,11 +38368,11 @@ mon.command("config").description("show monitoring services configuration").acti
   console.log(`Project Directory: ${projectDir}`);
   console.log(`Docker Compose File: ${composeFile}`);
   console.log(`Instances File: ${instancesFile}`);
-  if (fs9.existsSync(instancesFile) && !fs9.lstatSync(instancesFile).isDirectory()) {
+  if (fs11.existsSync(instancesFile) && !fs11.lstatSync(instancesFile).isDirectory()) {
     console.log(`
 Instances configuration:
 `);
-    const text = fs9.readFileSync(instancesFile, "utf8");
+    const text = fs11.readFileSync(instancesFile, "utf8");
     process.stdout.write(text);
     if (!/\n$/.test(text))
       console.log();
@@ -36494,8 +38421,8 @@ mon.command("update").description("update monitoring stack (migrate .env, pull i
       console.log("\u2713 .env is up to date");
     }
     console.log();
-    const gitDir = path7.resolve(projectDir, ".git");
-    if (fs9.existsSync(gitDir)) {
+    const gitDir = path9.resolve(projectDir, ".git");
+    if (fs11.existsSync(gitDir)) {
       console.log("Fetching latest changes...");
       await execFilePromise("git", ["fetch", "origin"]);
       const { stdout: branch } = await execFilePromise("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
@@ -36650,7 +38577,7 @@ mon.command("check").description("monitoring services system readiness check").a
 var targets = mon.command("targets").description("manage databases to monitor");
 targets.command("list").description("list monitoring target databases").action(async () => {
   const { instancesFile: instancesPath, projectDir } = await resolveOrInitPaths();
-  if (!fs9.existsSync(instancesPath) || fs9.lstatSync(instancesPath).isDirectory()) {
+  if (!fs11.existsSync(instancesPath) || fs11.lstatSync(instancesPath).isDirectory()) {
     console.error(`instances.yml not found in ${projectDir}`);
     process.exitCode = 1;
     return;
@@ -36713,7 +38640,7 @@ targets.command("add [connStr] [name]").description("add monitoring target datab
 });
 targets.command("remove <name>").description("remove monitoring target database").action(async (name) => {
   const { instancesFile: file } = await resolveOrInitPaths();
-  if (!fs9.existsSync(file) || fs9.lstatSync(file).isDirectory()) {
+  if (!fs11.existsSync(file) || fs11.lstatSync(file).isDirectory()) {
     console.error("instances.yml not found");
     process.exitCode = 1;
     return;
@@ -36741,7 +38668,7 @@ targets.command("remove <name>").description("remove monitoring target database"
 });
 targets.command("test <name>").description("test monitoring target database connectivity").action(async (name) => {
   const { instancesFile: instancesPath } = await resolveOrInitPaths();
-  if (!fs9.existsSync(instancesPath) || fs9.lstatSync(instancesPath).isDirectory()) {
+  if (!fs11.existsSync(instancesPath) || fs11.lstatSync(instancesPath).isDirectory()) {
     console.error("instances.yml not found");
     process.exitCode = 1;
     return;
@@ -37003,15 +38930,15 @@ To authenticate, run: pgai auth`);
 });
 auth.command("remove-key").description("remove API key").action(async () => {
   const newConfigPath = getConfigPath();
-  const hasNewConfig = fs9.existsSync(newConfigPath);
+  const hasNewConfig = fs11.existsSync(newConfigPath);
   let legacyPath;
   try {
     const { projectDir } = await resolveOrInitPaths();
-    legacyPath = path7.resolve(projectDir, ".pgwatch-config");
+    legacyPath = path9.resolve(projectDir, ".pgwatch-config");
   } catch {
-    legacyPath = path7.resolve(process.cwd(), ".pgwatch-config");
+    legacyPath = path9.resolve(process.cwd(), ".pgwatch-config");
   }
-  const hasLegacyConfig = fs9.existsSync(legacyPath) && fs9.statSync(legacyPath).isFile();
+  const hasLegacyConfig = fs11.existsSync(legacyPath) && fs11.statSync(legacyPath).isFile();
   if (!hasNewConfig && !hasLegacyConfig) {
     console.log("No API key configured");
     return;
@@ -37021,11 +38948,11 @@ auth.command("remove-key").description("remove API key").action(async () => {
   }
   if (hasLegacyConfig) {
     try {
-      const content = fs9.readFileSync(legacyPath, "utf8");
+      const content = fs11.readFileSync(legacyPath, "utf8");
       const filtered = content.split(/\r?\n/).filter((l) => !/^api_key=/.test(l)).join(`
 `).replace(/\n+$/g, `
 `);
-      fs9.writeFileSync(legacyPath, filtered, "utf8");
+      fs11.writeFileSync(legacyPath, filtered, "utf8");
     } catch (err) {
       console.warn(`Warning: Could not update legacy config: ${err instanceof Error ? err.message : String(err)}`);
     }
@@ -37036,7 +38963,7 @@ To authenticate again, run: pgai auth`);
 });
 mon.command("generate-grafana-password").description("generate Grafana password for monitoring services").action(async () => {
   const { projectDir } = await resolveOrInitPaths();
-  const cfgPath = path7.resolve(projectDir, ".pgwatch-config");
+  const cfgPath = path9.resolve(projectDir, ".pgwatch-config");
   try {
     const { stdout: password } = await execFilePromise("openssl", ["rand", "-base64", "12"]);
     const newPassword = password.trim().replace(/\n/g, "");
@@ -37046,17 +38973,17 @@ mon.command("generate-grafana-password").description("generate Grafana password
       return;
     }
     let configContent = "";
-    if (fs9.existsSync(cfgPath)) {
-      const stats = fs9.statSync(cfgPath);
+    if (fs11.existsSync(cfgPath)) {
+      const stats = fs11.statSync(cfgPath);
       if (stats.isDirectory()) {
         console.error(".pgwatch-config is a directory, expected a file. Skipping read.");
       } else {
-        configContent = fs9.readFileSync(cfgPath, "utf8");
+        configContent = fs11.readFileSync(cfgPath, "utf8");
       }
     }
     const lines = configContent.split(/\r?\n/).filter((l) => !/^grafana_password=/.test(l));
     lines.push(`grafana_password=${newPassword}`);
-    fs9.writeFileSync(cfgPath, lines.filter(Boolean).join(`
+    fs11.writeFileSync(cfgPath, lines.filter(Boolean).join(`
 `) + `
 `, "utf8");
     console.log("\u2713 New Grafana password generated and saved");
@@ -37078,19 +39005,19 @@ Note: This command requires 'openssl' to be installed`);
 });
 mon.command("show-grafana-credentials").description("show Grafana credentials for monitoring services").action(async () => {
   const { projectDir } = await resolveOrInitPaths();
-  const cfgPath = path7.resolve(projectDir, ".pgwatch-config");
-  if (!fs9.existsSync(cfgPath)) {
+  const cfgPath = path9.resolve(projectDir, ".pgwatch-config");
+  if (!fs11.existsSync(cfgPath)) {
     console.error("Configuration file not found. Run 'postgres-ai mon local-install' first.");
     process.exitCode = 1;
     return;
   }
-  const stats = fs9.statSync(cfgPath);
+  const stats = fs11.statSync(cfgPath);
   if (stats.isDirectory()) {
     console.error(".pgwatch-config is a directory, expected a file. Cannot read credentials.");
     process.exitCode = 1;
     return;
   }
-  const content = fs9.readFileSync(cfgPath, "utf8");
+  const content = fs11.readFileSync(cfgPath, "utf8");
   const lines = content.split(/\r?\n/);
   let password = "";
   for (const line of lines) {
@@ -37110,9 +39037,9 @@ Grafana credentials:`);
   console.log("  URL:      http://localhost:3000");
   console.log("  Username: monitor");
   console.log(`  Password: ${password}`);
-  const envFile = path7.resolve(projectDir, ".env");
-  if (fs9.existsSync(envFile)) {
-    const envContent = fs9.readFileSync(envFile, "utf8");
+  const envFile = path9.resolve(projectDir, ".env");
+  if (fs11.existsSync(envFile)) {
+    const envContent = fs11.readFileSync(envFile, "utf8");
     const vmUser = envContent.match(/^VM_AUTH_USERNAME=([^\r\n]+)/m);
     const vmPass = envContent.match(/^VM_AUTH_PASSWORD=([^\r\n]+)/m);
     if (vmUser && vmPass) {
@@ -37838,13 +39765,13 @@ reports.command("data [reportId]").description("get checkup report file data (in
     });
     spinner.stop();
     if (opts.output) {
-      const dir = path7.resolve(opts.output);
-      fs9.mkdirSync(dir, { recursive: true });
+      const dir = path9.resolve(opts.output);
+      fs11.mkdirSync(dir, { recursive: true });
       for (const f of result) {
-        const safeName = path7.basename(f.filename);
-        const filePath = path7.join(dir, safeName);
+        const safeName = path9.basename(f.filename);
+        const filePath = path9.join(dir, safeName);
         const content = f.type === "json" ? JSON.stringify(tryParseJson(f.data), null, 2) : f.data;
-        fs9.writeFileSync(filePath, content, "utf-8");
+        fs11.writeFileSync(filePath, content, "utf-8");
         console.log(filePath);
       }
     } else if (opts.json) {
@@ -37889,6 +39816,419 @@ function tryParseJson(s) {
     return s;
   }
 }
+function inferCommandFromResult(r) {
+  if (r.command)
+    return r.command;
+  if (r.plan_text !== undefined || r.plan_json !== undefined)
+    return "plan";
+  if (r.row_count !== undefined || r.result_rows !== undefined)
+    return "exec";
+  if (r.hypo_used !== undefined)
+    return "hypo";
+  if (r.terminated !== undefined)
+    return "terminate";
+  if (r.reset !== undefined)
+    return "reset";
+  if (r.snapshot !== undefined)
+    return "activity";
+  return null;
+}
+function printJoeOutcome(command, outcome, json3, budgetMs) {
+  const effectiveBudgetMs = typeof budgetMs === "number" && Number.isFinite(budgetMs) ? budgetMs : DEFAULT_BUDGET_MS2;
+  const budgetSeconds = Math.round(effectiveBudgetMs / 1000);
+  if (outcome.budgetExpired) {
+    if (json3) {
+      console.log(JSON.stringify({
+        command_id: outcome.commandId,
+        status: outcome.status,
+        session_id: outcome.sessionId,
+        budget_expired: true,
+        resume: `pgai joe result ${outcome.commandId}`
+      }, null, 2));
+    } else {
+      console.log(`submitted ${outcome.commandId} \xB7 ${outcome.status} \xB7 budget ${budgetSeconds}s reached \u2014 resume:  pgai joe result ${outcome.commandId}`);
+    }
+    return;
+  }
+  const result = outcome.result;
+  if (outcome.status === "done" && result) {
+    if (json3) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`submitted ${outcome.commandId} \xB7 done`);
+      const body = formatJoeResult(command, result);
+      if (body)
+        console.log(body);
+    }
+    return;
+  }
+  if (outcome.status === "error") {
+    const msg = result?.error ?? "command failed";
+    console.error(`command ${outcome.commandId} error: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.error(`command ${outcome.commandId} timed out on the server \u2014 resume:  pgai joe result ${outcome.commandId}`);
+  process.exitCode = 1;
+}
+async function runJoeCli(command, sql, args, opts) {
+  try {
+    const rootOpts = program2.opts();
+    const cfg = readConfig();
+    const { apiKey } = getConfig(rootOpts);
+    if (!apiKey) {
+      console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+      process.exitCode = 1;
+      return;
+    }
+    const projectRef = (opts.project ?? cfg.defaultProject ?? "").toString().trim();
+    if (!projectRef) {
+      console.error("Project is required. Pass --project <id|alias>.");
+      process.exitCode = 1;
+      return;
+    }
+    const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+    const budgetMs = typeof opts.budget === "number" && !Number.isNaN(opts.budget) ? opts.budget * 1000 : undefined;
+    const outcome = await executeJoeCommand2({
+      apiKey,
+      apiBaseUrl,
+      command,
+      project: projectRef,
+      sql,
+      args,
+      session: opts.session ?? null,
+      newSession: !!opts.newSession,
+      orgId: cfg.orgId ?? undefined,
+      budgetMs,
+      debug: !!opts.debug
+    });
+    printJoeOutcome(command, outcome, !!opts.json, budgetMs);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    process.exitCode = 1;
+  }
+}
+function withJoeOptions(cmd) {
+  return cmd.option("--project <id|alias>", "target project by numeric id OR alias/name").option("--session <id>", "run on a specific session's clone").option("--new-session", "start a fresh session/clone (null session)").option("--budget <seconds>", "one-shot poll budget in seconds (default 25)", (v) => parseInt(v, 10)).option("--debug", "enable debug output").option("--json", "output raw JSON");
+}
+var joe = program2.command("joe").description("Joe API v2 \u2014 plan/EXPLAIN/exec queries on ephemeral DBLab clones");
+withJoeOptions(joe.command("plan <sql>").description("plan a query (EXPLAIN, plan-only \u2014 no execution; the fast/safe default)")).action(async (sql, opts) => {
+  await runJoeCli("plan", sql, null, opts);
+});
+withJoeOptions(joe.command("explain <sql>").description("EXPLAIN ANALYZE a query (EXECUTES on the hardened, ephemeral clone)")).action(async (sql, opts) => {
+  await runJoeCli("explain", sql, null, opts);
+});
+withJoeOptions(joe.command("exec <sql>").description("run arbitrary DDL/DML on the clone (e.g. create index, analyze)")).action(async (sql, opts) => {
+  await runJoeCli("exec", sql, null, opts);
+});
+withJoeOptions(joe.command("hypo <indexSql>").description("HypoPG hypothetical index + re-plan (no real index, no data change)").requiredOption("--query <sql>", "target query the hypothetical index is evaluated against")).action(async (indexSql, opts) => {
+  await runJoeCli("hypo", indexSql, { query: opts.query }, opts);
+});
+withJoeOptions(joe.command("activity").description("running-activity snapshot (pg_stat_activity; query text redacted)")).action(async (opts) => {
+  await runJoeCli("activity", null, null, opts);
+});
+withJoeOptions(joe.command("terminate <pid>").description("pg_terminate_backend(pid) on the clone")).action(async (pid, opts) => {
+  const pidStr = (pid ?? "").trim();
+  if (!/^[0-9]+$/.test(pidStr)) {
+    console.error("pid must be a number");
+    process.exitCode = 1;
+    return;
+  }
+  await runJoeCli("terminate", null, { pid: parseInt(pidStr, 10) }, opts);
+});
+withJoeOptions(joe.command("reset").description("reset/recreate the session's thin clone")).action(async (opts) => {
+  await runJoeCli("reset", null, null, opts);
+});
+withJoeOptions(joe.command("describe <object>").description("\\d-family schema/relation/index metadata").option("--variant <variant>", "\\d-family variant (e.g. \\d+, \\di, \\dt)")).action(async (object4, opts) => {
+  const args = { object: object4 };
+  if (opts.variant)
+    args.variant = opts.variant;
+  await runJoeCli("describe", null, args, opts);
+});
+withJoeOptions(joe.command("history <terms>").description("search prior Joe analyses, metadata-only (M1b \u2014 not yet available)")).action(async (_terms, _opts) => {
+  console.error("Joe history search is not available yet \u2014 it is planned for M1b. " + "No history-search backend is deployed; this command is a placeholder until then.");
+  process.exitCode = 1;
+});
+program2.command("projects").description("list the org's projects (shows which have Joe ready) \u2014 org-level, not a Joe endpoint").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
+  try {
+    const rootOpts = program2.opts();
+    const cfg = readConfig();
+    const { apiKey } = getConfig(rootOpts);
+    if (!apiKey) {
+      console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+      process.exitCode = 1;
+      return;
+    }
+    const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+    const projects = await listProjects2({
+      apiKey,
+      apiBaseUrl,
+      orgId: cfg.orgId ?? undefined,
+      debug: !!opts.debug
+    });
+    if (opts.json) {
+      console.log(JSON.stringify(projects, null, 2));
+    } else {
+      console.log(formatProjectsTable(projects));
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    process.exitCode = 1;
+  }
+});
+async function resolveDblabTarget(project, debug) {
+  const rootOpts = program2.opts();
+  const cfg = readConfig();
+  const { apiKey } = getConfig(rootOpts);
+  if (!apiKey) {
+    throw new Error("API key is required. Run 'pgai auth' first or set --api-key.");
+  }
+  const ref = (project ?? "").trim();
+  if (!ref) {
+    throw new Error("--project <id|alias> is required");
+  }
+  const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+  const orgId = cfg.orgId ?? undefined;
+  const instanceId = await resolveDblabInstanceId2({ apiKey, apiBaseUrl, project: ref, orgId, debug });
+  return { apiKey, apiBaseUrl, orgId, instanceId };
+}
+var dblab = program2.command("dblab").description("DBLab thin-clone / branch / snapshot management (proxies the Platform DBLab API)");
+var clone2 = dblab.command("clone").description("DBLab thin-clone management (proxies the Platform DBLab API)");
+clone2.command("create").description("create a thin clone of the project's database").requiredOption("--project <id|alias>", "project id or alias").option("--branch <branch>", "branch to clone from").option("--snapshot <id>", "snapshot id to clone from").option("--id <id>", "clone id (DBLab generates one when omitted)").option("--db-user <user>", "clone DB user").option("--db-password <password>", "clone DB password").option("--protected", "protect the clone from auto-deletion").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
+  try {
+    const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
+    const result = await createClone2({
+      apiKey,
+      apiBaseUrl,
+      instanceId,
+      cloneId: opts.id,
+      branch: opts.branch,
+      snapshotId: opts.snapshot,
+      dbUser: opts.dbUser,
+      dbPassword: opts.dbPassword,
+      isProtected: !!opts.protected,
+      debug: !!opts.debug
+    });
+    printResult(result, opts.json);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+joe.command("status <commandId>").description("show a Joe command's status (metadata only)").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (commandId, opts) => {
+  try {
+    const rootOpts = program2.opts();
+    const cfg = readConfig();
+    const { apiKey } = getConfig(rootOpts);
+    if (!apiKey) {
+      console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+      process.exitCode = 1;
+      return;
+    }
+    const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+    const status = await getCommandStatus2({ apiKey, apiBaseUrl, commandId, debug: !!opts.debug });
+    if (opts.json) {
+      console.log(JSON.stringify(status, null, 2));
+    } else {
+      console.log(`command ${status.command_id} \xB7 ${status.status}${status.error ? ` \xB7 ${status.error}` : ""}`);
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    process.exitCode = 1;
+  }
+});
+clone2.command("list").description("list the project's thin clones").requiredOption("--project <id|alias>", "project id or alias").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
+  try {
+    const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
+    const result = await listClones2({ apiKey, apiBaseUrl, instanceId, debug: !!opts.debug });
+    printResult(result, opts.json);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+joe.command("result <commandId>").description("fetch a Joe command's result by id (resume a timed-out one-shot)").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (commandId, opts) => {
+  try {
+    const rootOpts = program2.opts();
+    const cfg = readConfig();
+    const { apiKey } = getConfig(rootOpts);
+    if (!apiKey) {
+      console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+      process.exitCode = 1;
+      return;
+    }
+    const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+    const result = await getCommandResult2({ apiKey, apiBaseUrl, commandId, debug: !!opts.debug });
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      if (result.status === "error" || result.status === "timed_out") {
+        process.exitCode = 1;
+      }
+      return;
+    }
+    const inferred = inferCommandFromResult(result);
+    if (result.status === "done" && inferred) {
+      console.log(`command ${result.command_id} \xB7 done`);
+      const body = formatJoeResult(inferred, result);
+      if (body)
+        console.log(body);
+    } else if (result.status === "error") {
+      console.error(`command ${result.command_id} error: ${result.error ?? "command failed"}`);
+      process.exitCode = 1;
+    } else if (result.status === "timed_out") {
+      console.error(`command ${result.command_id} timed out on the server`);
+      process.exitCode = 1;
+    } else {
+      console.log(`command ${result.command_id} \xB7 ${result.status}`);
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    process.exitCode = 1;
+  }
+});
+clone2.command("status <cloneId>").description("show a clone's status").requiredOption("--project <id|alias>", "project id or alias").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (cloneId, opts) => {
+  try {
+    const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
+    const result = await getClone2({ apiKey, apiBaseUrl, instanceId, cloneId, debug: !!opts.debug });
+    printResult(result, opts.json);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+clone2.command("reset <cloneId>").description("reset a clone to a pristine snapshot").requiredOption("--project <id|alias>", "project id or alias").option("--snapshot <id>", "snapshot id to reset to (default: latest)").option("--latest", "reset to the latest snapshot").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (cloneId, opts) => {
+  try {
+    const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
+    const result = await resetClone2({
+      apiKey,
+      apiBaseUrl,
+      instanceId,
+      cloneId,
+      snapshotId: opts.snapshot,
+      latest: opts.latest,
+      debug: !!opts.debug
+    });
+    printResult(result ?? { reset: true, cloneId }, opts.json);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+clone2.command("destroy <cloneId>").description("destroy a clone (requires joe:admin)").requiredOption("--project <id|alias>", "project id or alias").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (cloneId, opts) => {
+  try {
+    const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
+    const result = await destroyClone2({ apiKey, apiBaseUrl, instanceId, cloneId, debug: !!opts.debug });
+    printResult(result ?? { destroyed: true, cloneId }, opts.json);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+var branch = dblab.command("branch").description("DBLab branch management (proxies the Platform DBLab API)");
+branch.command("list").description("list the project's branches").requiredOption("--project <id|alias>", "project id or alias").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
+  try {
+    const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
+    const result = await listBranches2({ apiKey, apiBaseUrl, instanceId, debug: !!opts.debug });
+    printResult(result, opts.json);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+branch.command("create <name>").description("create a branch").requiredOption("--project <id|alias>", "project id or alias").option("--snapshot <id>", "snapshot id to base the branch on").option("--base-branch <branch>", "parent branch to fork from").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (name, opts) => {
+  try {
+    const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
+    const result = await createBranch2({
+      apiKey,
+      apiBaseUrl,
+      instanceId,
+      branchName: name,
+      baseBranch: opts.baseBranch,
+      snapshotId: opts.snapshot,
+      debug: !!opts.debug
+    });
+    printResult(result, opts.json);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+branch.command("delete <name>").description("delete a branch (requires joe:admin)").requiredOption("--project <id|alias>", "project id or alias").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (name, opts) => {
+  try {
+    const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
+    const result = await deleteBranch2({ apiKey, apiBaseUrl, instanceId, branchName: name, debug: !!opts.debug });
+    printResult(result ?? { deleted: true, branch: name }, opts.json);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+branch.command("log <name>").description("show a branch's snapshot log").requiredOption("--project <id|alias>", "project id or alias").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (name, opts) => {
+  try {
+    const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
+    const result = await branchLog2({ apiKey, apiBaseUrl, instanceId, branchName: name, debug: !!opts.debug });
+    printResult(result, opts.json);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+var snapshot = dblab.command("snapshot").description("DBLab snapshot management (proxies the Platform DBLab API)");
+snapshot.command("list").description("list the project's snapshots").requiredOption("--project <id|alias>", "project id or alias").option("--branch <branch>", "filter by branch").option("--dataset <dataset>", "filter by dataset").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
+  try {
+    const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
+    const result = await listSnapshots2({
+      apiKey,
+      apiBaseUrl,
+      instanceId,
+      branchName: opts.branch,
+      dataset: opts.dataset,
+      debug: !!opts.debug
+    });
+    printResult(result, opts.json);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+snapshot.command("create").description("create a snapshot from a clone").requiredOption("--project <id|alias>", "project id or alias").requiredOption("--clone <id>", "clone id to snapshot").option("--message <message>", "snapshot message").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
+  try {
+    const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
+    const result = await createSnapshot2({
+      apiKey,
+      apiBaseUrl,
+      instanceId,
+      cloneId: opts.clone,
+      message: opts.message,
+      debug: !!opts.debug
+    });
+    printResult(result, opts.json);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
+snapshot.command("destroy <snapshotId>").description("destroy a snapshot (requires joe:admin)").requiredOption("--project <id|alias>", "project id or alias").option("--force", "force-delete even when dependent clones exist").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (snapshotId, opts) => {
+  try {
+    const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
+    const result = await destroySnapshot2({
+      apiKey,
+      apiBaseUrl,
+      instanceId,
+      snapshotId,
+      force: !!opts.force,
+      debug: !!opts.debug
+    });
+    printResult(result ?? { destroyed: true, snapshot: snapshotId }, opts.json);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
 var mcp = program2.command("mcp").description("MCP server integration");
 mcp.command("start").description("start MCP stdio server").option("--debug", "enable debug output").action(async (opts) => {
   const rootOpts = program2.opts();
@@ -37962,29 +40302,29 @@ mcp.command("install [client]").description("install MCP server configuration fo
     let configDir;
     switch (client) {
       case "cursor":
-        configPath = path7.join(homeDir, ".cursor", "mcp.json");
-        configDir = path7.dirname(configPath);
+        configPath = path9.join(homeDir, ".cursor", "mcp.json");
+        configDir = path9.dirname(configPath);
         break;
       case "windsurf":
-        configPath = path7.join(homeDir, ".windsurf", "mcp.json");
-        configDir = path7.dirname(configPath);
+        configPath = path9.join(homeDir, ".windsurf", "mcp.json");
+        configDir = path9.dirname(configPath);
         break;
       case "codex":
-        configPath = path7.join(homeDir, ".codex", "mcp.json");
-        configDir = path7.dirname(configPath);
+        configPath = path9.join(homeDir, ".codex", "mcp.json");
+        configDir = path9.dirname(configPath);
         break;
       default:
         console.error(`Configuration not implemented for: ${client}`);
         process.exitCode = 1;
         return;
     }
-    if (!fs9.existsSync(configDir)) {
-      fs9.mkdirSync(configDir, { recursive: true });
+    if (!fs11.existsSync(configDir)) {
+      fs11.mkdirSync(configDir, { recursive: true });
     }
     let config2 = { mcpServers: {} };
-    if (fs9.existsSync(configPath)) {
+    if (fs11.existsSync(configPath)) {
       try {
-        const content = fs9.readFileSync(configPath, "utf8");
+        const content = fs11.readFileSync(configPath, "utf8");
         config2 = JSON.parse(content);
         if (!config2.mcpServers) {
           config2.mcpServers = {};
@@ -37997,7 +40337,7 @@ mcp.command("install [client]").description("install MCP server configuration fo
       command: pgaiPath,
       args: ["mcp", "start"]
     };
-    fs9.writeFileSync(configPath, JSON.stringify(config2, null, 2), "utf8");
+    fs11.writeFileSync(configPath, JSON.stringify(config2, null, 2), "utf8");
     console.log(`\u2713 PostgresAI MCP server configured for ${client}`);
     console.log(`  Config file: ${configPath}`);
     console.log("");
@@ -38018,5 +40358,7 @@ export {
   registerMonitoringInstance,
   refreshBundledComposeIfStale,
   readDeployedTag,
-  isValidComposeYaml
+  planMonitoringRegistration,
+  isValidComposeYaml,
+  inferCommandFromResult
 };