postgresai 0.16.0-rc.4 → 0.16.0

package/dist/bin/postgres-ai.js

@@ -13323,43 +13323,92 @@ var require_dist2 = __commonJS((exports, module) => {
 var exports_util2 = {};
 __export(exports_util2, {
   resolveBaseUrls: () => resolveBaseUrls2,
+  requestTimeoutSignal: () => requestTimeoutSignal2,
+  redactTextSecrets: () => redactTextSecrets2,
+  redactSecretsForLog: () => redactSecretsForLog2,
+  redactSecrets: () => redactSecrets2,
   normalizeBaseUrl: () => normalizeBaseUrl2,
   maskSecret: () => maskSecret2,
-  formatHttpError: () => formatHttpError2
+  isRetryableHttpStatus: () => isRetryableHttpStatus2,
+  isFetchTimeout: () => isFetchTimeout2,
+  formatHttpError: () => formatHttpError2,
+  describeFetchError: () => describeFetchError2,
+  HttpStatusError: () => HttpStatusError2,
+  HttpRequestTimeoutError: () => HttpRequestTimeoutError2,
+  DEFAULT_HTTP_REQUEST_TIMEOUT_MS: () => DEFAULT_HTTP_REQUEST_TIMEOUT_MS2
 });
 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;
+  let bodyCode;
+  let bodyHint;
+  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 = redactTextSecrets2(message.trim());
+      }
+      const details = errObj.details ?? errObj.detail;
+      if (typeof details === "string" && details.trim().length > 0) {
+        bodyDetails = redactTextSecrets2(details.trim());
+      }
+      if (typeof errObj.code === "string" && errObj.code.trim().length > 0) {
+        bodyCode = errObj.code.trim();
+      }
+      if (typeof errObj.hint === "string" && errObj.hint.trim().length > 0) {
+        bodyHint = redactTextSecrets2(errObj.hint.trim());
+      }
+      if (bodyMessage === undefined && bodyDetails === undefined && bodyCode === undefined && bodyHint === undefined) {
+        bodyDetails = redactSecretsForLog2(JSON.stringify(errObj));
       }
     } catch {
       const trimmed = responseBody.trim();
       if (trimmed.length > 0 && trimmed.length < 500) {
-        errMsg += `
-${trimmed}`;
+        bodyDetails = redactTextSecrets2(trimmed);
       }
     }
   }
+  const trimmedReason = statusText?.trim();
+  const reasonPhrase = trimmedReason && trimmedReason !== STANDARD_REASON_PHRASES2[status] && trimmedReason !== generic ? trimmedReason : undefined;
+  const safeReasonPhrase = reasonPhrase ? redactTextSecrets2(reasonPhrase) : undefined;
+  const headline = bodyMessage ?? safeReasonPhrase ?? generic;
+  const codeSuffix = bodyCode && !headline.includes(bodyCode) ? ` (${bodyCode})` : "";
+  let errMsg = `${operation}: HTTP ${status} - ${headline}${codeSuffix}`;
+  if (bodyDetails && bodyDetails !== headline) {
+    errMsg += `
+${bodyDetails}`;
+  }
+  if (bodyHint) {
+    errMsg += `
+Hint: ${bodyHint}`;
+  }
   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 isRetryableHttpStatus2(status) {
+  return status >= 500 || status === 429;
+}
+function requestTimeoutSignal2(timeoutMs) {
+  const requested = typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_HTTP_REQUEST_TIMEOUT_MS2;
+  const bounded = Math.max(1, Math.min(DEFAULT_HTTP_REQUEST_TIMEOUT_MS2, Math.floor(requested)));
+  return { signal: AbortSignal.timeout(bounded), timeoutMs: bounded };
+}
+function isFetchTimeout2(err) {
+  const name = err?.name;
+  return name === "AbortError" || name === "TimeoutError";
+}
 function maskSecret2(secret) {
   if (!secret)
     return "";
@@ -13369,6 +13418,35 @@ 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 isSensitiveLogKey2(key) {
+  const normalized = key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toLowerCase();
+  return /^(?:password|passwd|db_(?:pass|password)|conn_?str|secret|token|api_key|private_key|access_key|access_token|refresh_token|auth|auth_key|auth_token|authorization|credentials?|dsn)$/.test(normalized);
+}
+function redactSecrets2(value) {
+  if (Array.isArray(value)) {
+    return value.map(redactSecrets2);
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      out[key] = isSensitiveLogKey2(key) && child != null ? "[REDACTED]" : redactSecrets2(child);
+    }
+    return out;
+  }
+  return value;
+}
+function redactSecretsForLog2(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return redactTextSecrets2(text);
+  }
+  return JSON.stringify(redactSecrets2(parsed));
+}
+function redactTextSecrets2(text) {
+  return text.replace(TEXT_URL_USERINFO2, "$1:[REDACTED]@").replace(TEXT_SENSITIVE_PAIR2, "$1[REDACTED]");
+}
 function normalizeBaseUrl2(value) {
   const trimmed = (value || "").replace(/\/$/, "");
   try {
@@ -13391,7 +13469,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, HttpStatusError2, DEFAULT_HTTP_REQUEST_TIMEOUT_MS2 = 25000, HttpRequestTimeoutError2, TEXT_URL_USERINFO2, TEXT_SENSITIVE_PAIR2;
 var init_util = __esm(() => {
   HTTP_STATUS_MESSAGES2 = {
     400: "Bad Request",
@@ -13405,6 +13483,36 @@ 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"
+  };
+  HttpStatusError2 = class HttpStatusError2 extends Error {
+    status;
+    constructor(message, status) {
+      super(message);
+      this.name = "HttpStatusError";
+      this.status = status;
+    }
+  };
+  HttpRequestTimeoutError2 = class HttpRequestTimeoutError2 extends Error {
+    constructor(operation, timeoutMs) {
+      super(`${operation}: request timed out after ${timeoutMs}ms`);
+      this.name = "HttpRequestTimeoutError";
+    }
+  };
+  TEXT_URL_USERINFO2 = /(\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+):[^\s/@]+@/gi;
+  TEXT_SENSITIVE_PAIR2 = /((?:password|passwd|db[-_]?pass|connstr|secret|token|api[-_]?key|private[-_]?key|access[-_]?key|cred(?:ential)?s?|dsn)["']?\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;&]+)/gi;
 });
 
 // node_modules/commander/esm.mjs
@@ -13425,7 +13533,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.16.0-rc.4",
+  version: "0.16.0",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -13443,8 +13551,15 @@ var package_default = {
   },
   exports: {
     ".": "./dist/bin/postgres-ai.js",
-    "./cli": "./dist/bin/postgres-ai.js"
+    "./cli": "./dist/bin/postgres-ai.js",
+    "./schemas/*.schema.json": "./schemas/*.schema.json"
   },
+  files: [
+    "dist/",
+    "instances.demo.yml",
+    "schemas/",
+    "sql/"
+  ],
   type: "module",
   engines: {
     node: ">=18"
@@ -13453,7 +13568,9 @@ var package_default = {
     "embed-metrics": "bun run scripts/embed-metrics.ts",
     "embed-checkup-dictionary": "bun run scripts/embed-checkup-dictionary.ts",
     "embed-all": "bun run embed-metrics && bun run embed-checkup-dictionary",
-    build: `bun run embed-all && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))" && cp -r ./sql ./dist/sql && cp ../instances.demo.yml ./instances.demo.yml`,
+    "sync-schemas": "node scripts/sync-schemas.mjs",
+    build: `bun run sync-schemas && bun run embed-all && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))" && cp -r ./sql ./dist/sql && cp ../instances.demo.yml ./instances.demo.yml`,
+    prepack: "npm run sync-schemas",
     prepublishOnly: "npm run build",
     start: "bun ./bin/postgres-ai.ts --help",
     "start:node": "node ./dist/bin/postgres-ai.js --help",
@@ -13504,7 +13621,8 @@ function readConfig() {
     storageBaseUrl: null,
     orgId: null,
     defaultProject: null,
-    projectName: null
+    projectName: null,
+    feedbackTipLastShownAt: null
   };
   const userConfigPath = getConfigPath();
   if (fs.existsSync(userConfigPath)) {
@@ -13517,6 +13635,7 @@ function readConfig() {
       config.orgId = parsed.orgId ?? null;
       config.defaultProject = parsed.defaultProject ?? null;
       config.projectName = parsed.projectName ?? null;
+      config.feedbackTipLastShownAt = parsed.feedbackTipLastShownAt ?? null;
       return config;
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -16256,7 +16375,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-rc.4";
+var version = "0.16.0";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -16277,8 +16396,15 @@ var package_default2 = {
   },
   exports: {
     ".": "./dist/bin/postgres-ai.js",
-    "./cli": "./dist/bin/postgres-ai.js"
+    "./cli": "./dist/bin/postgres-ai.js",
+    "./schemas/*.schema.json": "./schemas/*.schema.json"
   },
+  files: [
+    "dist/",
+    "instances.demo.yml",
+    "schemas/",
+    "sql/"
+  ],
   type: "module",
   engines: {
     node: ">=18"
@@ -16287,7 +16413,9 @@ var package_default2 = {
     "embed-metrics": "bun run scripts/embed-metrics.ts",
     "embed-checkup-dictionary": "bun run scripts/embed-checkup-dictionary.ts",
     "embed-all": "bun run embed-metrics && bun run embed-checkup-dictionary",
-    build: `bun run embed-all && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))" && cp -r ./sql ./dist/sql && cp ../instances.demo.yml ./instances.demo.yml`,
+    "sync-schemas": "node scripts/sync-schemas.mjs",
+    build: `bun run sync-schemas && bun run embed-all && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))" && cp -r ./sql ./dist/sql && cp ../instances.demo.yml ./instances.demo.yml`,
+    prepack: "npm run sync-schemas",
     prepublishOnly: "npm run build",
     start: "bun ./bin/postgres-ai.ts --help",
     "start:node": "node ./dist/bin/postgres-ai.js --help",
@@ -16338,7 +16466,8 @@ function readConfig2() {
     storageBaseUrl: null,
     orgId: null,
     defaultProject: null,
-    projectName: null
+    projectName: null,
+    feedbackTipLastShownAt: null
   };
   const userConfigPath = getConfigPath2();
   if (fs2.existsSync(userConfigPath)) {
@@ -16351,6 +16480,7 @@ function readConfig2() {
       config.orgId = parsed.orgId ?? null;
       config.defaultProject = parsed.defaultProject ?? null;
       config.projectName = parsed.projectName ?? null;
+      config.feedbackTipLastShownAt = parsed.feedbackTipLastShownAt ?? null;
       return config;
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -16379,6 +16509,28 @@ function readConfig2() {
   }
   return config;
 }
+function writeConfig2(config) {
+  const configDir = getConfigDir2();
+  const configPath = getConfigPath2();
+  if (!fs2.existsSync(configDir)) {
+    fs2.mkdirSync(configDir, { recursive: true, mode: 448 });
+  }
+  let existingConfig = {};
+  if (fs2.existsSync(configPath)) {
+    try {
+      const content = fs2.readFileSync(configPath, "utf8");
+      existingConfig = JSON.parse(content);
+    } catch (err) {}
+  }
+  const mergedConfig = {
+    ...existingConfig,
+    ...config
+  };
+  fs2.writeFileSync(configPath, JSON.stringify(mergedConfig, null, 2) + `
+`, {
+    mode: 384
+  });
+}
 
 // lib/util.ts
 var HTTP_STATUS_MESSAGES = {
@@ -16398,35 +16550,105 @@ 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;
+  let bodyCode;
+  let bodyHint;
+  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 = redactTextSecrets(message.trim());
+      }
+      const details = errObj.details ?? errObj.detail;
+      if (typeof details === "string" && details.trim().length > 0) {
+        bodyDetails = redactTextSecrets(details.trim());
+      }
+      if (typeof errObj.code === "string" && errObj.code.trim().length > 0) {
+        bodyCode = errObj.code.trim();
+      }
+      if (typeof errObj.hint === "string" && errObj.hint.trim().length > 0) {
+        bodyHint = redactTextSecrets(errObj.hint.trim());
+      }
+      if (bodyMessage === undefined && bodyDetails === undefined && bodyCode === undefined && bodyHint === undefined) {
+        bodyDetails = redactSecretsForLog(JSON.stringify(errObj));
       }
     } catch {
       const trimmed = responseBody.trim();
       if (trimmed.length > 0 && trimmed.length < 500) {
-        errMsg += `
-${trimmed}`;
+        bodyDetails = redactTextSecrets(trimmed);
       }
     }
   }
+  const trimmedReason = statusText?.trim();
+  const reasonPhrase = trimmedReason && trimmedReason !== STANDARD_REASON_PHRASES[status] && trimmedReason !== generic ? trimmedReason : undefined;
+  const safeReasonPhrase = reasonPhrase ? redactTextSecrets(reasonPhrase) : undefined;
+  const headline = bodyMessage ?? safeReasonPhrase ?? generic;
+  const codeSuffix = bodyCode && !headline.includes(bodyCode) ? ` (${bodyCode})` : "";
+  let errMsg = `${operation}: HTTP ${status} - ${headline}${codeSuffix}`;
+  if (bodyDetails && bodyDetails !== headline) {
+    errMsg += `
+${bodyDetails}`;
+  }
+  if (bodyHint) {
+    errMsg += `
+Hint: ${bodyHint}`;
+  }
   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})`;
+}
+
+class HttpStatusError extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "HttpStatusError";
+    this.status = status;
+  }
+}
+function isRetryableHttpStatus(status) {
+  return status >= 500 || status === 429;
+}
+var DEFAULT_HTTP_REQUEST_TIMEOUT_MS = 25000;
+
+class HttpRequestTimeoutError extends Error {
+  constructor(operation, timeoutMs) {
+    super(`${operation}: request timed out after ${timeoutMs}ms`);
+    this.name = "HttpRequestTimeoutError";
+  }
+}
+function requestTimeoutSignal(timeoutMs) {
+  const requested = typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_HTTP_REQUEST_TIMEOUT_MS;
+  const bounded = Math.max(1, Math.min(DEFAULT_HTTP_REQUEST_TIMEOUT_MS, Math.floor(requested)));
+  return { signal: AbortSignal.timeout(bounded), timeoutMs: bounded };
+}
+function isFetchTimeout(err) {
+  const name = err?.name;
+  return name === "AbortError" || name === "TimeoutError";
+}
 function maskSecret(secret) {
   if (!secret)
     return "";
@@ -16436,6 +16658,37 @@ 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)}`;
 }
+function isSensitiveLogKey(key) {
+  const normalized = key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toLowerCase();
+  return /^(?:password|passwd|db_(?:pass|password)|conn_?str|secret|token|api_key|private_key|access_key|access_token|refresh_token|auth|auth_key|auth_token|authorization|credentials?|dsn)$/.test(normalized);
+}
+function redactSecrets(value) {
+  if (Array.isArray(value)) {
+    return value.map(redactSecrets);
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      out[key] = isSensitiveLogKey(key) && child != null ? "[REDACTED]" : redactSecrets(child);
+    }
+    return out;
+  }
+  return value;
+}
+function redactSecretsForLog(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return redactTextSecrets(text);
+  }
+  return JSON.stringify(redactSecrets(parsed));
+}
+var TEXT_URL_USERINFO = /(\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+):[^\s/@]+@/gi;
+var TEXT_SENSITIVE_PAIR = /((?:password|passwd|db[-_]?pass|connstr|secret|token|api[-_]?key|private[-_]?key|access[-_]?key|cred(?:ential)?s?|dsn)["']?\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;&]+)/gi;
+function redactTextSecrets(text) {
+  return text.replace(TEXT_URL_USERINFO, "$1:[REDACTED]@").replace(TEXT_SENSITIVE_PAIR, "$1[REDACTED]");
+}
 function normalizeBaseUrl(value) {
   const trimmed = (value || "").replace(/\/$/, "");
   try {
@@ -25801,117 +26054,846 @@ function renderMarkdownForTerminal(md) {
 `);
 }
 
-// bin/postgres-ai.ts
-init_util();
-
-// lib/instances.ts
-import * as fs4 from "fs";
-
-// node_modules/js-yaml/dist/js-yaml.mjs
-/*! js-yaml 4.1.1 https://github.com/nodeca/js-yaml @license MIT */
-function isNothing2(subject) {
-  return typeof subject === "undefined" || subject === null;
-}
-function isObject3(subject) {
-  return typeof subject === "object" && subject !== null;
+// lib/joe.ts
+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;
+  const requestTimeout = requestTimeoutSignal(params.timeoutMs);
+  try {
+    response = await fetch(url.toString(), {
+      method: "POST",
+      headers,
+      body: payload,
+      signal: requestTimeout.signal
+    });
+  } catch (err) {
+    if (isFetchTimeout(err)) {
+      throw new HttpRequestTimeoutError(operation, requestTimeout.timeoutMs);
+    }
+    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 HttpStatusError(formatHttpError(operation, response.status, text, response.statusText), response.status);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${operation}: failed to parse response: ${redactSecretsForLog(text)}`);
+  }
 }
-function toArray2(sequence) {
-  if (Array.isArray(sequence))
-    return sequence;
-  else if (isNothing2(sequence))
-    return [];
-  return [sequence];
+async function startCommand(params) {
+  const { apiKey, apiBaseUrl, instanceId, command, debug, timeoutMs } = params;
+  if (!String(command ?? "").trim()) {
+    throw new Error("command text is required");
+  }
+  const commandId = await callRpc({
+    apiKey,
+    apiBaseUrl,
+    fn: "joe_command_run",
+    body: { instance_id: instanceId, command },
+    operation: "Failed to run Joe command",
+    debug,
+    timeoutMs
+  });
+  if (typeof commandId !== "string" || !/^[0-9]+$/.test(commandId)) {
+    throw new Error(`Failed to run Joe command: expected a command id string, got: ${redactSecretsForLog(JSON.stringify(commandId))}`);
+  }
+  return commandId;
 }
-function extend4(target, source) {
-  var index, length, key, sourceKeys;
-  if (source) {
-    sourceKeys = Object.keys(source);
-    for (index = 0, length = sourceKeys.length;index < length; index += 1) {
-      key = sourceKeys[index];
-      target[key] = source[key];
-    }
+async function getCommandOutput(params) {
+  const { apiKey, apiBaseUrl, commandId, debug, timeoutMs } = params;
+  if (!commandId) {
+    throw new Error("commandId is required");
   }
-  return target;
+  return callRpc({
+    apiKey,
+    apiBaseUrl,
+    fn: "joe_command_output",
+    body: { command_id: commandId },
+    operation: "Failed to fetch command output",
+    debug,
+    timeoutMs
+  });
 }
-function repeat2(string4, count) {
-  var result = "", cycle;
-  for (cycle = 0;cycle < count; cycle += 1) {
-    result += string4;
+function preserveIntegerId(value) {
+  if (typeof value === "number")
+    return value;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : value;
+}
+function normalizeProjectRow(row) {
+  return {
+    project_id: preserveIntegerId(row.project_id ?? 0),
+    alias: row.alias ?? null,
+    name: row.name ?? null,
+    joe_ready: Boolean(row.joe_ready ?? false),
+    tunnel: Boolean(row.tunnel ?? false),
+    instance_id: row.instance_id == null ? null : preserveIntegerId(row.instance_id),
+    dblab_instance_id: row.dblab_instance_id == null ? null : preserveIntegerId(row.dblab_instance_id)
+  };
+}
+async function listProjects(params) {
+  const { apiKey, apiBaseUrl, orgId, debug } = params;
+  const body = {};
+  if (typeof orgId === "number") {
+    body.org_id = orgId;
   }
-  return result;
+  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 isNegativeZero2(number4) {
-  return number4 === 0 && Number.NEGATIVE_INFINITY === 1 / number4;
+function isNumericProjectRef(ref) {
+  return /^[0-9]+$/.test(ref.trim());
 }
-var isNothing_12 = isNothing2;
-var isObject_12 = isObject3;
-var toArray_12 = toArray2;
-var repeat_12 = repeat2;
-var isNegativeZero_12 = isNegativeZero2;
-var extend_12 = extend4;
-var common2 = {
-  isNothing: isNothing_12,
-  isObject: isObject_12,
-  toArray: toArray_12,
-  repeat: repeat_12,
-  isNegativeZero: isNegativeZero_12,
-  extend: extend_12
-};
-function formatError3(exception2, compact) {
-  var where = "", message = exception2.reason || "(unknown reason)";
-  if (!exception2.mark)
-    return message;
-  if (exception2.mark.name) {
-    where += 'in "' + exception2.mark.name + '" ';
+async function resolveJoeInstanceId(params) {
+  const ref = String(params.project ?? "").trim();
+  if (!ref) {
+    throw new Error("project is required (--project <id|alias>)");
   }
-  where += "(" + (exception2.mark.line + 1) + ":" + (exception2.mark.column + 1) + ")";
-  if (!compact && exception2.mark.snippet) {
-    where += `
-
-` + exception2.mark.snippet;
+  const projects = await listProjects({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    orgId: params.orgId,
+    debug: params.debug
+  });
+  const needle = ref.toLowerCase();
+  const match = isNumericProjectRef(ref) ? projects.find((p) => String(p.project_id) === String(preserveIntegerId(ref))) : projects.find((p) => p.alias !== null && p.alias.toLowerCase() === needle || p.name !== null && p.name.toLowerCase() === needle);
+  if (!match) {
+    throw new Error(`Project not found for id/alias/name '${ref}'. Run 'pgai projects' to see available projects.`);
+  }
+  if (match.instance_id == null) {
+    throw new Error(`Project '${ref}' has no Joe instance. Run 'pgai projects' to see which projects have Joe ready.`);
+  }
+  return match.instance_id;
+}
+var DESCRIBE_VARIANTS = [
+  "\\d",
+  "\\d+",
+  "\\dt",
+  "\\dt+",
+  "\\di",
+  "\\di+",
+  "\\l",
+  "\\l+",
+  "\\dv",
+  "\\dv+",
+  "\\dm",
+  "\\dm+"
+];
+function buildJoeCommandText(command, input = {}) {
+  const arg = String(input.arg ?? "").trim();
+  switch (command) {
+    case "plan":
+    case "explain":
+    case "exec":
+    case "hypo": {
+      if (!arg) {
+        throw new Error(`${command} requires an argument`);
+      }
+      return `${command} ${arg}`;
+    }
+    case "activity":
+    case "reset":
+      return command;
+    case "terminate": {
+      if (!/^[1-9][0-9]*$/.test(arg)) {
+        throw new Error("pid must be a positive integer");
+      }
+      return `terminate ${arg}`;
+    }
+    case "describe": {
+      if (!arg) {
+        throw new Error("describe requires an object name");
+      }
+      const variant = String(input.variant ?? "\\d").trim();
+      if (!DESCRIBE_VARIANTS.includes(variant)) {
+        throw new Error(`Unsupported describe variant '${variant}'. Supported: ${DESCRIBE_VARIANTS.join(" ")}`);
+      }
+      return `${variant} ${arg}`;
+    }
+  }
+}
+var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function runCommand(params) {
+  const { apiKey, apiBaseUrl, instanceId, command, debug } = params;
+  const budgetMs = typeof params.budgetMs === "number" && Number.isFinite(params.budgetMs) && params.budgetMs >= 0 ? 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 commandId = await startCommand({ apiKey, apiBaseUrl, instanceId, command, debug });
+  const deadline = now() + budgetMs;
+  let status = "pending";
+  const remainingRequestMs = () => Math.max(1, Math.min(DEFAULT_HTTP_REQUEST_TIMEOUT_MS, deadline - now()));
+  if (now() >= deadline) {
+    return { commandId, status, output: null, budgetExpired: true };
+  }
+  for (;; ) {
+    let output;
+    try {
+      output = await getCommandOutput({
+        apiKey,
+        apiBaseUrl,
+        commandId,
+        debug,
+        timeoutMs: remainingRequestMs()
+      });
+    } catch (err) {
+      if (err instanceof HttpRequestTimeoutError) {
+        return { commandId, status, output: null, budgetExpired: true };
+      }
+      if (err instanceof HttpStatusError && isRetryableHttpStatus(err.status)) {
+        if (now() >= deadline) {
+          return { commandId, status, output: null, budgetExpired: true };
+        }
+        await sleep(pollIntervalMs);
+        continue;
+      }
+      throw err;
+    }
+    status = output.status;
+    if (status === "ok" || status === "error") {
+      return { commandId, status, output, budgetExpired: false };
+    }
+    if (now() >= deadline) {
+      return { commandId, status, output: null, budgetExpired: true };
+    }
+    await sleep(pollIntervalMs);
   }
-  return message + " " + where;
 }
-function YAMLException$12(reason, mark) {
-  Error.call(this);
-  this.name = "YAMLException";
-  this.reason = reason;
-  this.mark = mark;
-  this.message = formatError3(this, false);
-  if (Error.captureStackTrace) {
-    Error.captureStackTrace(this, this.constructor);
+async function executeJoeCommand(params) {
+  const commandText = buildJoeCommandText(params.command, params.input);
+  let instanceId;
+  const directRef = String(params.instanceId ?? "").trim();
+  if (directRef) {
+    if (!/^[0-9]+$/.test(directRef)) {
+      throw new Error("instanceId must be a numeric Joe instance id");
+    }
+    instanceId = directRef;
+  } else if (String(params.project ?? "").trim()) {
+    instanceId = await resolveJoeInstanceId({
+      apiKey: params.apiKey,
+      apiBaseUrl: params.apiBaseUrl,
+      project: String(params.project),
+      orgId: params.orgId,
+      debug: params.debug
+    });
   } else {
-    this.stack = new Error().stack || "";
-  }
+    throw new Error("either instanceId or project is required");
+  }
+  const outcome = await runCommand({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    instanceId,
+    command: commandText,
+    budgetMs: params.budgetMs,
+    pollIntervalMs: params.pollIntervalMs,
+    debug: params.debug,
+    now: params.now,
+    sleep: params.sleep
+  });
+  return { ...outcome, command: params.command, instanceId, commandText };
 }
-YAMLException$12.prototype = Object.create(Error.prototype);
-YAMLException$12.prototype.constructor = YAMLException$12;
-YAMLException$12.prototype.toString = function toString2(compact) {
-  return this.name + ": " + formatError3(this, compact);
-};
-var exception2 = YAMLException$12;
-function getLine2(buffer, lineStart, lineEnd, position, maxLineLength) {
-  var head = "";
-  var tail = "";
-  var maxHalfLength = Math.floor(maxLineLength / 2) - 1;
-  if (position - lineStart > maxHalfLength) {
-    head = " ... ";
-    lineStart = position - maxHalfLength + head.length;
+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 (Array.isArray(planJson)) {
+    for (const entry of planJson) {
+      if (entry && typeof entry === "object") {
+        walk(entry.Plan ?? entry);
+      }
+    }
+    return flags;
   }
-  if (lineEnd - position > maxHalfLength) {
-    tail = " ...";
-    lineEnd = position + maxHalfLength - tail.length;
+  if (planJson && typeof planJson === "object") {
+    const root = planJson;
+    walk(root.Plan ?? planJson);
   }
-  return {
-    str: head + buffer.slice(lineStart, lineEnd).replace(/\t/g, "→") + tail,
-    pos: position - lineStart + head.length
-  };
+  return flags;
 }
-function padStart2(string4, max) {
-  return common2.repeat(" ", max - string4.length) + string4;
+function formatJoeOutput(output) {
+  const lines = [];
+  const section = (value, label) => {
+    if (value == null || value.trim() === "")
+      return;
+    if (lines.length > 0)
+      lines.push("");
+    if (label)
+      lines.push(`${label}:`);
+    lines.push(value);
+  };
+  section(output.response);
+  section(output.plan_text, "plan");
+  const flags = clientSidePlanFlags(output.plan_json).map((flag) => `⚑ ${flag}`);
+  if (flags.length > 0) {
+    lines.push(...flags);
+  }
+  section(output.plan_execution_text, "execution plan (EXPLAIN ANALYZE)");
+  section(output.stats, "stats");
+  section(output.recommendations, "recommendations");
+  if (output.queryid) {
+    if (lines.length > 0)
+      lines.push("");
+    lines.push(`(queryid ${output.queryid})`);
+  }
+  return lines.join(`
+`);
 }
-function makeSnippet2(mark, options) {
-  options = Object.create(options || null);
+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/joe.ts
+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;
+  const requestTimeout = requestTimeoutSignal(params.timeoutMs);
+  try {
+    response = await fetch(url.toString(), {
+      method: "POST",
+      headers,
+      body: payload,
+      signal: requestTimeout.signal
+    });
+  } catch (err) {
+    if (isFetchTimeout(err)) {
+      throw new HttpRequestTimeoutError(operation, requestTimeout.timeoutMs);
+    }
+    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 HttpStatusError(formatHttpError(operation, response.status, text, response.statusText), response.status);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${operation}: failed to parse response: ${redactSecretsForLog(text)}`);
+  }
+}
+function preserveIntegerId2(value) {
+  if (typeof value === "number")
+    return value;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : value;
+}
+function normalizeProjectRow2(row) {
+  return {
+    project_id: preserveIntegerId2(row.project_id ?? 0),
+    alias: row.alias ?? null,
+    name: row.name ?? null,
+    joe_ready: Boolean(row.joe_ready ?? false),
+    tunnel: Boolean(row.tunnel ?? false),
+    instance_id: row.instance_id == null ? null : preserveIntegerId2(row.instance_id),
+    dblab_instance_id: row.dblab_instance_id == null ? null : preserveIntegerId2(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 isNumericProjectRef2(ref) {
+  return /^[0-9]+$/.test(ref.trim());
+}
+
+// lib/dblab.ts
+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 listProjects2({ 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;
+  });
+  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;
+  const requestTimeout = requestTimeoutSignal();
+  try {
+    response = await fetch(url.toString(), {
+      method: "POST",
+      headers,
+      body,
+      signal: requestTimeout.signal
+    });
+  } catch (err) {
+    if (isFetchTimeout(err)) {
+      throw new HttpRequestTimeoutError(operation, requestTimeout.timeoutMs);
+    }
+    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 HttpStatusError(formatHttpError(operation, response.status, text, response.statusText), response.status);
+  }
+  if (text.trim() === "") {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${operation}: failed to parse response: ${redactSecretsForLog(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");
+  if (!/^[a-zA-Z0-9_.@/:-]+$/.test(snapshotId)) {
+    throw new Error("snapshotId contains invalid characters");
+  }
+  if (snapshotId.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new Error("snapshotId contains an invalid path segment");
+  }
+  const action = `/snapshot/${snapshotId}?force=${Boolean(force)}`;
+  return callDblabApi({
+    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";
+
+// node_modules/js-yaml/dist/js-yaml.mjs
+/*! js-yaml 4.1.1 https://github.com/nodeca/js-yaml @license MIT */
+function isNothing2(subject) {
+  return typeof subject === "undefined" || subject === null;
+}
+function isObject3(subject) {
+  return typeof subject === "object" && subject !== null;
+}
+function toArray2(sequence) {
+  if (Array.isArray(sequence))
+    return sequence;
+  else if (isNothing2(sequence))
+    return [];
+  return [sequence];
+}
+function extend4(target, source) {
+  var index, length, key, sourceKeys;
+  if (source) {
+    sourceKeys = Object.keys(source);
+    for (index = 0, length = sourceKeys.length;index < length; index += 1) {
+      key = sourceKeys[index];
+      target[key] = source[key];
+    }
+  }
+  return target;
+}
+function repeat2(string4, count) {
+  var result = "", cycle;
+  for (cycle = 0;cycle < count; cycle += 1) {
+    result += string4;
+  }
+  return result;
+}
+function isNegativeZero2(number4) {
+  return number4 === 0 && Number.NEGATIVE_INFINITY === 1 / number4;
+}
+var isNothing_12 = isNothing2;
+var isObject_12 = isObject3;
+var toArray_12 = toArray2;
+var repeat_12 = repeat2;
+var isNegativeZero_12 = isNegativeZero2;
+var extend_12 = extend4;
+var common2 = {
+  isNothing: isNothing_12,
+  isObject: isObject_12,
+  toArray: toArray_12,
+  repeat: repeat_12,
+  isNegativeZero: isNegativeZero_12,
+  extend: extend_12
+};
+function formatError3(exception2, compact) {
+  var where = "", message = exception2.reason || "(unknown reason)";
+  if (!exception2.mark)
+    return message;
+  if (exception2.mark.name) {
+    where += 'in "' + exception2.mark.name + '" ';
+  }
+  where += "(" + (exception2.mark.line + 1) + ":" + (exception2.mark.column + 1) + ")";
+  if (!compact && exception2.mark.snippet) {
+    where += `
+
+` + exception2.mark.snippet;
+  }
+  return message + " " + where;
+}
+function YAMLException$12(reason, mark) {
+  Error.call(this);
+  this.name = "YAMLException";
+  this.reason = reason;
+  this.mark = mark;
+  this.message = formatError3(this, false);
+  if (Error.captureStackTrace) {
+    Error.captureStackTrace(this, this.constructor);
+  } else {
+    this.stack = new Error().stack || "";
+  }
+}
+YAMLException$12.prototype = Object.create(Error.prototype);
+YAMLException$12.prototype.constructor = YAMLException$12;
+YAMLException$12.prototype.toString = function toString2(compact) {
+  return this.name + ": " + formatError3(this, compact);
+};
+var exception2 = YAMLException$12;
+function getLine2(buffer, lineStart, lineEnd, position, maxLineLength) {
+  var head = "";
+  var tail = "";
+  var maxHalfLength = Math.floor(maxLineLength / 2) - 1;
+  if (position - lineStart > maxHalfLength) {
+    head = " ... ";
+    lineStart = position - maxHalfLength + head.length;
+  }
+  if (lineEnd - position > maxHalfLength) {
+    tail = " ...";
+    lineEnd = position + maxHalfLength - tail.length;
+  }
+  return {
+    str: head + buffer.slice(lineStart, lineEnd).replace(/\t/g, "→") + tail,
+    pos: position - lineStart + head.length
+  };
+}
+function padStart2(string4, max) {
+  return common2.repeat(" ", max - string4.length) + string4;
+}
+function makeSnippet2(mark, options) {
+  options = Object.create(options || null);
   if (!mark.buffer)
     return null;
   if (!options.maxLength)
@@ -28595,6 +29577,12 @@ async function registerAasCollection(apiKey, instanceId, opts) {
   try {
     if (!apiKey || !instanceId)
       return { ok: false, reason: "missing api key or instance id" };
+    if (!(opts.vcpus > 0)) {
+      return {
+        ok: false,
+        reason: "vcpus is unknown (0 or omitted); AAS collection stays off until a real value is set — re-run with --vcpus <n>"
+      };
+    }
     const labels = resolveAasLabels(opts.instancesPath);
     if (!labels)
       return { ok: false, reason: "could not determine a single (cluster, node_name) target" };
@@ -30281,16 +31269,93 @@ function createCallbackServer(port = 0, expectedState = null, timeoutMs = 300000
     }
     resolveReady(actualPort);
   });
-  return {
-    server: { stop: stopServer },
-    promise: promise2,
-    ready,
-    getPort: () => actualPort
-  };
+  return {
+    server: { stop: stopServer },
+    promise: promise2,
+    ready,
+    getPort: () => actualPort
+  };
+}
+
+// bin/postgres-ai.ts
+init_util();
+
+// lib/feedback.ts
+var FEEDBACK_URL = "https://gitlab.com/postgres-ai/postgresai/-/work_items/300";
+var FEEDBACK_SUPPRESS_ENV = "PGAI_NO_FEEDBACK_TIP";
+var FEEDBACK_TIP_MIN_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000;
+function feedbackTipSuppressed(suppress) {
+  if (suppress === undefined)
+    return false;
+  const value = suppress.trim().toLowerCase();
+  return value !== "" && value !== "0" && value !== "false" && value !== "no";
+}
+function feedbackTipAllowed(ctx) {
+  if (ctx.json)
+    return false;
+  if (!ctx.isTTY)
+    return false;
+  if (feedbackTipSuppressed(ctx.suppress))
+    return false;
+  return true;
+}
+function isFeedbackTipDue(lastShownMs, nowMs) {
+  if (lastShownMs === null || lastShownMs === undefined || !Number.isFinite(lastShownMs)) {
+    return true;
+  }
+  return nowMs - lastShownMs >= FEEDBACK_TIP_MIN_INTERVAL_MS;
+}
+function feedbackTipLine() {
+  return `\x1B[2m\uD83D\uDCA1 Ideas / feedback: ${FEEDBACK_URL}  (silence: ${FEEDBACK_SUPPRESS_ENV}=1)\x1B[0m`;
+}
+function readLastShown() {
+  const value = readConfig2().feedbackTipLastShownAt;
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function persistLastShown(nowMs) {
+  writeConfig2({ feedbackTipLastShownAt: nowMs });
+}
+function maybeEmitFeedbackTip(ctx, io = {}) {
+  if (!feedbackTipAllowed(ctx))
+    return false;
+  const now = (io.now ?? Date.now)();
+  const read = io.readLastShown ?? readLastShown;
+  const persist = io.persistLastShown ?? persistLastShown;
+  const write = io.write ?? ((line) => {
+    process.stderr.write(line);
+  });
+  let lastShown = null;
+  try {
+    lastShown = read();
+  } catch {
+    lastShown = null;
+  }
+  if (!isFeedbackTipDue(lastShown, now))
+    return false;
+  try {
+    persist(now);
+  } catch {}
+  write(feedbackTipLine() + `
+`);
+  return true;
+}
+function feedbackJson() {
+  return JSON.stringify({ url: FEEDBACK_URL }, null, 2);
+}
+function feedbackMessage() {
+  return [
+    "\uD83D\uDCA1 Help shape the PostgresAI CLI",
+    "",
+    "We read every idea and bug report. Share yours here:",
+    "",
+    `  ${FEEDBACK_URL}`,
+    "",
+    `Tip: set ${FEEDBACK_SUPPRESS_ENV}=1 to silence the occasional reminder.`
+  ].join(`
+`);
 }
 
 // bin/postgres-ai.ts
-init_util();
 import { createInterface } from "readline";
 import * as childProcess from "child_process";
 
@@ -30426,7 +31491,9 @@ where
   blk_read_time,
   blk_write_time,
   extract(epoch from (now() - pg_postmaster_start_time()))::int8 as postmaster_uptime_s,
-  extract(epoch from (now() - pg_backup_start_time()))::int8 as backup_duration_s,
+  case when to_regproc('aurora_version') is null
+    then extract(epoch from (now() - pg_backup_start_time()))::int8
+  end as backup_duration_s,
   checksum_failures,
   extract(epoch from (now() - checksum_last_failure))::int8 as checksum_last_failure_s,
   case when pg_is_in_recovery() then 1 else 0 end as in_recovery_int,
@@ -30464,7 +31531,9 @@ where
   blk_read_time,
   blk_write_time,
   extract(epoch from (now() - pg_postmaster_start_time()))::int8 as postmaster_uptime_s,
-  extract(epoch from (now() - pg_backup_start_time()))::int8 as backup_duration_s,
+  case when to_regproc('aurora_version') is null
+    then extract(epoch from (now() - pg_backup_start_time()))::int8
+  end as backup_duration_s,
   checksum_failures,
   extract(epoch from (now() - checksum_last_failure))::int8 as checksum_last_failure_s,
   case when pg_is_in_recovery() then 1 else 0 end as in_recovery_int,
@@ -31029,6 +32098,246 @@ where datname = current_database()
     gauges: ["stats_reset_epoch", "seconds_since_reset"],
     statement_timeout_seconds: 15
   },
+  pg_database_wraparound: {
+    sqls: {
+      11: `select /* pgwatch_generated */
+  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,
+  datname as tag_datname,
+  age(d.datfrozenxid) as age_datfrozenxid,
+  mxid_age(d.datminmxid) as age_datminmxid
+from
+  pg_catalog.pg_database d
+where
+  d.datallowconn
+`
+    },
+    gauges: ["age_datfrozenxid", "age_datminmxid"],
+    statement_timeout_seconds: 15
+  },
+  pg_settings_wraparound: {
+    description: "Snapshots wraparound-related pg_settings values so dashboards can plot threshold lines (soft autovacuum_freeze_max_age, failsafe age) that reflect actual cluster configuration instead of compiled defaults. pg_settings is cluster-global, so this metric is is_instance_level — pgwatch scrapes it once per cluster instead of once per database.",
+    sqls: {
+      11: `select /* pgwatch_generated */
+  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,
+  (select setting::int8 from pg_settings where name = 'autovacuum_freeze_max_age') as autovacuum_freeze_max_age,
+  (select setting::int8 from pg_settings where name = 'vacuum_freeze_min_age') as vacuum_freeze_min_age,
+  (select setting::int8 from pg_settings where name = 'vacuum_freeze_table_age') as vacuum_freeze_table_age,
+  (select setting::int8 from pg_settings where name = 'autovacuum_multixact_freeze_max_age') as autovacuum_multixact_freeze_max_age,
+  (select setting::int8 from pg_settings where name = 'vacuum_multixact_freeze_min_age') as vacuum_multixact_freeze_min_age,
+  (select setting::int8 from pg_settings where name = 'vacuum_multixact_freeze_table_age') as vacuum_multixact_freeze_table_age,
+  coalesce((select setting::int8 from pg_settings where name = 'vacuum_failsafe_age'), 0) as vacuum_failsafe_age,
+  coalesce((select setting::int8 from pg_settings where name = 'vacuum_multixact_failsafe_age'), 0) as vacuum_multixact_failsafe_age`
+    },
+    gauges: ["*"],
+    statement_timeout_seconds: 15
+  },
+  pg_table_wraparound: {
+    description: "Top relations at risk of transaction ID or MultiXact wraparound. Ranking reads pg_class only and is independently bounded to 50 relations for each age. Exact relation sizes are evaluated only after the bounded candidate set has been selected. Per-table freeze age overrides are exposed so F002 can evaluate the effective emergency threshold.",
+    sqls: {
+      11: `with candidates as ( /* pgwatch_generated */
+  select
+    c.oid,
+    n.nspname,
+    c.relname,
+    age(c.relfrozenxid)::int8 as xid_age,
+    mxid_age(c.relminmxid)::int8 as multixact_age,
+    coalesce(
+      -- Follow-up: toast.* overrides live on the parent heap's
+      -- reloptions, so relkind 't' currently uses the global value.
+      (select split_part(option, '=', 2)::int8
+       from unnest(coalesce(c.reloptions, '{}'::text[])) option
+       where split_part(option, '=', 1) = 'autovacuum_freeze_max_age'),
+      current_setting('autovacuum_freeze_max_age')::int8
+    ) as effective_freeze_max_age,
+    coalesce(
+      (select split_part(option, '=', 2)::int8
+       from unnest(coalesce(c.reloptions, '{}'::text[])) option
+       where split_part(option, '=', 1) = 'autovacuum_multixact_freeze_max_age'),
+      current_setting('autovacuum_multixact_freeze_max_age')::int8
+    ) as effective_multixact_freeze_max_age
+  from pg_catalog.pg_class c
+  join pg_catalog.pg_namespace n on n.oid = c.relnamespace
+  where c.relkind in ('r', 'm', 't')
+    and c.relpersistence <> 't'
+    and n.nspname <> 'information_schema'
+),
+ranked as (
+  (select *, 'xid'::text as ranked_by
+   from candidates
+   order by xid_age desc, nspname, relname
+   limit 50)
+  union all
+  (select *, 'multixact'::text as ranked_by
+   from candidates
+   order by multixact_age desc, nspname, relname
+   limit 50)
+),
+selected as (
+  select
+    oid, nspname, relname, xid_age, multixact_age,
+    effective_freeze_max_age, effective_multixact_freeze_max_age,
+    string_agg(ranked_by, ',' order by ranked_by) as ranked_by
+  from ranked
+  group by oid, nspname, relname, xid_age, multixact_age,
+           effective_freeze_max_age, effective_multixact_freeze_max_age
+)
+select
+  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,
+  current_database() as tag_datname,
+  s.nspname as tag_schema_name,
+  s.relname as tag_table_name,
+  s.ranked_by as tag_ranked_by,
+  s.xid_age,
+  s.multixact_age,
+  s.effective_freeze_max_age,
+  s.effective_multixact_freeze_max_age,
+  pg_catalog.pg_total_relation_size(s.oid)::int8 as table_size_bytes
+from selected s`
+    },
+    gauges: ["xid_age", "multixact_age", "effective_freeze_max_age", "effective_multixact_freeze_max_age", "table_size_bytes"],
+    statement_timeout_seconds: 15
+  },
+  multixact_size: {
+    sqls: {
+      11: `with env as ( /* pgwatch_generated */
+  select
+    exists (
+      select
+      from pg_proc p
+      join pg_namespace n on n.oid = p.pronamespace
+      where p.proname = 'pg_ls_multixactdir' and n.nspname = 'rds_tools'
+    ) as has_rds_fn,
+    exists (
+      select
+      from pg_proc p
+      join pg_namespace n on n.oid = p.pronamespace
+      where p.proname = 'aurora_stat_file' and n.nspname = 'pg_catalog'
+    ) as has_aurora_fn,
+    exists (select from pg_proc where proname = 'pg_ls_dir')    as has_pg_ls_dir_func,
+    exists (select from pg_proc where proname = 'pg_stat_file') as has_pg_stat_file_func
+),
+can_local as (
+  -- to_regprocedure returns NULL instead of erroring when the signature
+  -- does not exist, so this stays safe even on databases where
+  -- pg_stat_file has been dropped or has a different signature.
+  -- coalesce guards against NULL propagating through the AND chain.
+  -- The execute-privilege check prevents "permission denied" on
+  -- managed databases (Supabase etc.) where pg_stat_file is
+  -- restricted to superusers (#142).
+  select (has_pg_ls_dir_func and has_pg_stat_file_func
+    and coalesce(
+      has_function_privilege(
+        to_regprocedure('pg_stat_file(text,boolean)'), 'execute'),
+      false)
+  ) as ok from env
+),
+-- Use query_to_xml to safely execute Aurora-specific multixact query.
+-- Aurora uses aurora_stat_file() function instead of rds_tools.pg_ls_multixactdir().
+aurora_probe_xml as (
+  select query_to_xml($q$
+    with files as (
+      select filename, allocated_bytes, used_bytes
+      from aurora_stat_file()
+      where filename like 'pg_multixact/%'
+    ),
+    members as (
+      select sum(used_bytes)::bigint as sz from files where filename like 'pg_multixact/members%'
+    ),
+    offsets as (
+      select sum(used_bytes)::bigint as sz from files where filename like 'pg_multixact/offsets%'
+    ),
+    has_rows as (
+      select exists(select 1 from files) as any_rows
+    )
+    select
+      case when (select any_rows from has_rows) then coalesce((select sz from members), 0) end as members_bytes,
+      case when (select any_rows from has_rows) then coalesce((select sz from offsets), 0) end as offsets_bytes,
+      case when (select any_rows from has_rows) then 0 else 1 end as status_code
+  $q$, true, true, '') as x
+  where (select has_aurora_fn from env)
+),
+-- Use query_to_xml to safely execute RDS-specific multixact directory listing query.
+-- The XML wrapper allows the query to fail gracefully if rds_tools.pg_ls_multixactdir()
+-- is unavailable or returns errors, preventing the entire metric from failing.
+rds_probe_xml as (
+  select query_to_xml($q$
+    with files as (
+      select name, size
+      from rds_tools.pg_ls_multixactdir()
+    ),
+    members as (
+      select sum(size)::bigint as sz from files where name like 'pg_multixact/members%'
+    ),
+    offsets as (
+      select sum(size)::bigint as sz from files where name like 'pg_multixact/offsets%'
+    ),
+    has_rows as (
+      select exists(select 1 from files where name like 'pg_multixact/%') as any_rows
+    )
+    select
+      case when (select any_rows from has_rows) then coalesce((select sz from members), 0) end as members_bytes,
+      case when (select any_rows from has_rows) then coalesce((select sz from offsets), 0) end as offsets_bytes,
+      case when (select any_rows from has_rows) then 0 else 1 end as status_code
+  $q$, true, true, '') as x
+  where (select has_rds_fn from env) and not (select has_aurora_fn from env)
+),
+-- Use query_to_xml to safely execute standard Postgres multixact directory listing query.
+-- The XML wrapper allows the query to fail gracefully if pg_stat_file() or pg_ls_dir()
+-- are unavailable or return permission errors, preventing the entire metric from failing.
+local_probe_xml as (
+  select query_to_xml($q$
+    with dirs as (
+      select
+        (pg_stat_file('pg_multixact/members', true)).isdir as has_members,
+        (pg_stat_file('pg_multixact/offsets', true)).isdir as has_offsets
+    ),
+    flags as (
+      select ((select has_members from dirs) or (select has_offsets from dirs)) as has_any
+    ),
+    members as (
+      select sum((pg_stat_file(format('pg_multixact/members/%s', d), true)).size)::bigint as sz
+      from pg_ls_dir('pg_multixact/members') as d(d)
+      where (select has_members from dirs)
+    ),
+    offsets as (
+      select sum((pg_stat_file(format('pg_multixact/offsets/%s', d), true)).size)::bigint as sz
+      from pg_ls_dir('pg_multixact/offsets') as d(d)
+      where (select has_offsets from dirs)
+    )
+    select
+      case when (select has_any from flags) then coalesce((select sz from members), 0) end as members_bytes,
+      case when (select has_any from flags) then coalesce((select sz from offsets), 0) end as offsets_bytes,
+      case when (select has_any from flags) then 0 else 1 end as status_code
+  $q$, true, true, '') as x
+  where not (select has_rds_fn from env) and not (select has_aurora_fn from env) and (select ok from can_local)
+),
+picked as (
+  select * from aurora_probe_xml
+  union all
+  select * from rds_probe_xml
+  union all
+  select * from local_probe_xml
+  limit 1
+),
+parsed as (
+  select
+    (xpath('//members_bytes/text()',         x))[1]::text::bigint as members_bytes,
+    (xpath('//offsets_bytes/text()',         x))[1]::text::bigint as offsets_bytes,
+    (xpath('//status_code/text()',           x))[1]::text::int    as status_code
+  from picked
+)
+select * from parsed
+union all
+select
+  null::bigint as members_bytes,
+  null::bigint as offsets_bytes,
+  2::int       as status_code
+where not exists (select 1 from parsed);
+`
+    },
+    gauges: ["members_bytes", "offsets_bytes", "status_code"],
+    statement_timeout_seconds: 15
+  },
   pg_dead_tuples: {
     description: "Per-table dead-tuple accumulation and per-table autovacuum overrides for the F003 express check (\"Autovacuum: dead tuples\"). Reads the live counters in pg_stat_user_tables joined to pg_class for reloptions, so dead tuples that have NEVER been vacuumed are visible — unlike the statistical bloat estimators (F004/F005), which completely miss a table where autovacuum is disabled and dead tuples pile up unvacuumed. Returns relations that either carry dead tuples or have autovacuum disabled per-table, bounded to the top 100 by n_dead_tup so pathological schemas can't blow up the report. autovacuum_disabled recognises every boolean spelling Postgres accepts and stores verbatim in reloptions (false/off/no/0 and their unique prefixes; confirmed against PG13 and PG16 that `alter table .. set (autovacuum_enabled = false|off|0)` stores the literal text, so matching only 'autovacuum_enabled=off' misses the common '=false' spelling). Timestamps are exported as epoch seconds (0 = never) because Prometheus gauges must be numeric. The AccessExclusiveLock guard mirrors table_stats: pg_table_size() takes a lock and would block behind a fully locked relation. Compatible with all supported Postgres versions.",
     sqls: {
@@ -31361,6 +32670,200 @@ having count(*) > 0
     gauges: ["real_size_mib", "table_size_mib", "extra_size", "extra_pct", "fillfactor", "bloat_size", "bloat_pct", "is_na", "reltuples"],
     statement_timeout_seconds: 15
   },
+  xmin_horizon_snapshot: {
+    description: "Express-checkup single snapshot of xmin horizon ages and the oldest blocker for each holder class. Returns one row with component JSON, privilege/privacy metadata, and a pg_flight_recorder availability hint. Primary-only analysis is enforced in SQL; replicas return an informational skip row.",
+    sqls: {
+      12: `with context as materialized (
+  select
+    pg_is_in_recovery() as is_in_recovery,
+    case when pg_is_in_recovery() then null
+         else txid_snapshot_xmin(txid_current_snapshot())::int8 end as snapshot_xmin,
+    current_setting('autovacuum_freeze_max_age')::int8 as autovacuum_freeze_max_age,
+    coalesce(
+      (select rolsuper from pg_roles where rolname = current_user), false
+    ) or coalesce(
+      (select pg_has_role(current_user, oid, 'member') from pg_roles where rolname = 'pg_monitor'), false
+    ) or coalesce(
+      (select pg_has_role(current_user, oid, 'member') from pg_roles where rolname = 'pg_read_all_stats'), false
+    )
+      as has_full_visibility,
+    lower(coalesce(current_setting('postgresai.capture_query_preview', true), 'on'))
+      not in ('', 'off', 'false', '0') as query_preview_enabled,
+    to_regnamespace('pgfr_analyze') is not null as pg_flight_recorder_detected
+),
+activity_rows as materialized (
+  select
+    greatest(age(a.backend_xmin), age(a.backend_xid))::int8 as age_tx,
+    jsonb_strip_nulls(jsonb_build_object(
+      'pid', a.pid,
+      'database', a.datname,
+      'user', a.usename,
+      'application_name', a.application_name,
+      'state', a.state,
+      'backend_type', to_jsonb(a)->>'backend_type',
+      'queryid', to_jsonb(a)->>'query_id',
+      'xact_age_seconds', extract(epoch from now() - a.xact_start)::int8,
+      'state_age_seconds', extract(epoch from now() - a.state_change)::int8,
+      'query_age_seconds', extract(epoch from now() - a.query_start)::int8,
+      'query_preview', case
+        when c.has_full_visibility and c.query_preview_enabled
+        then left(regexp_replace(a.query, E'[\\\\r\\\\n\\\\t]+', ' ', 'g'), 500)
+        else null
+      end
+    )) as detail
+  from pg_stat_activity a
+  cross join context c
+  where not c.is_in_recovery
+    and a.pid <> pg_backend_pid()
+    and (a.backend_xmin is not null or a.backend_xid is not null)
+    and coalesce(to_jsonb(a)->>'leader_pid', '') = ''
+    and coalesce(to_jsonb(a)->>'backend_type', 'client backend')
+      in ('client backend', 'autovacuum worker')
+),
+activity as (
+  select
+    coalesce(max(age_tx), 0)::int8 as age_tx,
+    count(*)::int8 as count,
+    (array_agg(detail order by age_tx desc, (detail->>'pid')::int asc))[1] as top_blocker
+  from activity_rows
+),
+slot_rows as materialized (
+  select
+    age(s.xmin)::int8 as age_tx,
+    age(s.catalog_xmin)::int8 as catalog_age_tx,
+    jsonb_strip_nulls(jsonb_build_object(
+      'slot_name', s.slot_name,
+      'slot_type', s.slot_type,
+      'plugin', s.plugin,
+      'database', s.database,
+      'active', s.active,
+      'active_pid', s.active_pid,
+      'status', case
+        when coalesce(to_jsonb(s)->>'invalidation_reason', '') <> '' then 'invalidated'
+        when coalesce(to_jsonb(s)->>'conflicting', 'false') = 'true' then 'conflicting'
+        when not s.active and coalesce(to_jsonb(s)->>'inactive_since', '') <> '' then 'inactive'
+        when not s.active then 'unused'
+        else 'active'
+      end,
+      'inactive_since', to_jsonb(s)->>'inactive_since',
+      'wal_status', to_jsonb(s)->>'wal_status',
+      'conflicting', (to_jsonb(s)->>'conflicting')::boolean,
+      'invalidation_reason', to_jsonb(s)->>'invalidation_reason'
+    )) as detail
+  from pg_replication_slots s
+  cross join context c
+  where not c.is_in_recovery
+    and (s.xmin is not null or s.catalog_xmin is not null)
+),
+slots as (
+  select
+    coalesce(max(age_tx), 0)::int8 as age_tx,
+    count(*) filter (where age_tx is not null)::int8 as count,
+    (array_agg(detail order by age_tx desc nulls last, detail->>'slot_name')
+      filter (where age_tx is not null))[1] as top_blocker
+  from slot_rows
+),
+slots_catalog as (
+  select
+    coalesce(max(catalog_age_tx), 0)::int8 as age_tx,
+    count(*) filter (where catalog_age_tx is not null)::int8 as count,
+    (array_agg(detail order by catalog_age_tx desc nulls last, detail->>'slot_name')
+      filter (where catalog_age_tx is not null))[1] as top_blocker
+  from slot_rows
+),
+replication_rows as materialized (
+  select
+    age(r.backend_xmin)::int8 as age_tx,
+    jsonb_strip_nulls(jsonb_build_object(
+      'pid', r.pid,
+      'user', r.usename,
+      'application_name', r.application_name,
+      'client_addr', r.client_addr,
+      'state', r.state,
+      'sync_state', r.sync_state
+    )) as detail
+  from pg_stat_replication r
+  cross join context c
+  where not c.is_in_recovery and r.backend_xmin is not null
+),
+replication as (
+  select
+    coalesce(max(age_tx), 0)::int8 as age_tx,
+    count(*)::int8 as count,
+    (array_agg(detail order by age_tx desc, (detail->>'pid')::int asc))[1] as top_blocker
+  from replication_rows
+),
+prepared_rows as materialized (
+  select
+    age(p.transaction)::int8 as age_tx,
+    jsonb_strip_nulls(jsonb_build_object(
+      'gid', p.gid,
+      'owner', p.owner,
+      'database', p.database,
+      'prepared_at', p.prepared,
+      'prepared_age_seconds', extract(epoch from now() - p.prepared)::int8
+    )) as detail
+  from pg_prepared_xacts p
+  cross join context c
+  where not c.is_in_recovery
+),
+prepared as (
+  select
+    coalesce(max(age_tx), 0)::int8 as age_tx,
+    count(*)::int8 as count,
+    (array_agg(detail order by age_tx desc, detail->>'gid' asc))[1] as top_blocker
+  from prepared_rows
+)
+select /* pgwatch_generated xmin_horizon_snapshot */
+  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,
+  current_database() as tag_datname,
+  c.is_in_recovery,
+  case when c.is_in_recovery then 'replica: xmin horizon analysis is primary-only' end as skip_reason,
+  c.snapshot_xmin,
+  c.autovacuum_freeze_max_age,
+  c.has_full_visibility,
+  c.query_preview_enabled,
+  c.pg_flight_recorder_detected,
+  case when c.is_in_recovery then 0 else greatest(a.age_tx, s.age_tx, r.age_tx, p.age_tx) end
+    as data_horizon_age_tx,
+  case when c.is_in_recovery then 0 else sc.age_tx end as catalog_horizon_age_tx,
+  jsonb_build_object(
+    'pg_stat_activity', jsonb_build_object(
+      'age_tx', case when c.is_in_recovery then 0 else a.age_tx end,
+      'count', case when c.is_in_recovery then 0 else a.count end,
+      'top_blocker', case when c.is_in_recovery then null else a.top_blocker end
+    ),
+    'pg_replication_slots', jsonb_build_object(
+      'age_tx', case when c.is_in_recovery then 0 else s.age_tx end,
+      'count', case when c.is_in_recovery then 0 else s.count end,
+      'top_blocker', case when c.is_in_recovery then null else s.top_blocker end
+    ),
+    'pg_replication_slots_catalog', jsonb_build_object(
+      'age_tx', case when c.is_in_recovery then 0 else sc.age_tx end,
+      'count', case when c.is_in_recovery then 0 else sc.count end,
+      'top_blocker', case when c.is_in_recovery then null else sc.top_blocker end
+    ),
+    'pg_stat_replication', jsonb_build_object(
+      'age_tx', case when c.is_in_recovery then 0 else r.age_tx end,
+      'count', case when c.is_in_recovery then 0 else r.count end,
+      'top_blocker', case when c.is_in_recovery then null else r.top_blocker end
+    ),
+    'pg_prepared_xacts', jsonb_build_object(
+      'age_tx', case when c.is_in_recovery then 0 else p.age_tx end,
+      'count', case when c.is_in_recovery then 0 else p.count end,
+      'top_blocker', case when c.is_in_recovery then null else p.top_blocker end
+    )
+  ) as components
+from context c
+cross join activity a
+cross join slots s
+cross join slots_catalog sc
+cross join replication r
+cross join prepared p`
+    },
+    gauges: ["data_horizon_age_tx", "catalog_horizon_age_tx"],
+    statement_timeout_seconds: 15
+  },
   pg_stat_io: {
     description: "Collects I/O statistics from the PostgreSQL `pg_stat_io` view (available in PostgreSQL 16+). Provides insights into read and write operations by backend type, including the number of operations, MiB transferred (divided by 1048576), and time spent on I/O. This metric is essential for monitoring I/O performance and identifying potential bottlenecks in disk operations. The data is aggregated by backend type with a total row included via ROLLUP.",
     sqls: {
@@ -31439,9 +32942,14 @@ var METRIC_NAMES = {
   H001: "pg_invalid_indexes",
   H002: "unused_indexes",
   H004: "redundant_indexes",
+  F002Database: "pg_database_wraparound",
+  F002Settings: "pg_settings_wraparound",
+  F002Tables: "pg_table_wraparound",
+  F002MultixactSize: "multixact_size",
   F003: "pg_dead_tuples",
   F004: "pg_table_bloat",
   F005: "pg_btree_bloat",
+  F009: "xmin_horizon_snapshot",
   settings: "settings",
   dbStats: "db_stats",
   dbSize: "db_size",
@@ -32014,26 +33522,377 @@ var CHECKUP_DICTIONARY_DATA = [
     sort_order: null,
     is_system_report: false
   }
-];
-
-// lib/checkup-dictionary.ts
-var dictionaryByCode = new Map(CHECKUP_DICTIONARY_DATA.map((entry) => [entry.code.toUpperCase(), entry]));
-function buildCheckInfoMap() {
-  const result = {};
-  for (const entry of CHECKUP_DICTIONARY_DATA) {
-    result[entry.code] = entry.title;
+];
+
+// lib/checkup-dictionary.ts
+var dictionaryByCode = new Map(CHECKUP_DICTIONARY_DATA.map((entry) => [entry.code.toUpperCase(), entry]));
+function buildCheckInfoMap() {
+  const result = {};
+  for (const entry of CHECKUP_DICTIONARY_DATA) {
+    result[entry.code] = entry.title;
+  }
+  return result;
+}
+
+// lib/checkup-summary.ts
+function generateCheckSummary(checkId, report) {
+  const nodeIds = Object.keys(report.results || {});
+  if (nodeIds.length === 0) {
+    return { status: "info", message: "No data" };
+  }
+  const nodeData = report.results[nodeIds[0]];
+  switch (checkId) {
+    case "H001":
+      return summarizeH001(nodeData);
+    case "H002":
+      return summarizeH002(nodeData);
+    case "H004":
+      return summarizeH004(nodeData);
+    case "A002":
+      return summarizeA002(nodeData);
+    case "A013":
+      return summarizeA013(nodeData);
+    case "A003":
+      return summarizeA003(nodeData);
+    case "A004":
+      return summarizeA004(nodeData);
+    case "A007":
+      return summarizeA007(nodeData);
+    case "D001":
+      return summarizeD001(nodeData);
+    case "D004":
+      return summarizeD004(nodeData);
+    case "F001":
+      return summarizeF001(nodeData);
+    case "F002":
+      return summarizeF002(nodeData);
+    case "F003":
+      return summarizeF003(nodeData);
+    case "F004":
+      return summarizeBloat(nodeData, "table");
+    case "F005":
+      return summarizeBloat(nodeData, "index");
+    case "F009":
+      return summarizeF009(nodeData);
+    case "G001":
+      return summarizeG001(nodeData);
+    case "G003":
+      return summarizeG003(nodeData);
+    default:
+      return { status: "info", message: "Check completed" };
+  }
+}
+function summarizeA003(nodeData) {
+  const data = nodeData?.data || {};
+  const settingsCount = Object.keys(data).length;
+  if (settingsCount === 0) {
+    return { status: "info", message: "No settings found" };
+  }
+  return {
+    status: "info",
+    message: `${settingsCount} setting${settingsCount > 1 ? "s" : ""} collected`
+  };
+}
+function summarizeA004(nodeData) {
+  const data = nodeData?.data;
+  if (!data) {
+    return { status: "info", message: "Cluster information collected" };
+  }
+  const dbCount = Object.keys(data.database_sizes || {}).length;
+  if (dbCount > 0) {
+    return { status: "info", message: `${dbCount} database${dbCount > 1 ? "s" : ""} analyzed` };
+  }
+  return { status: "info", message: "Cluster information collected" };
+}
+function summarizeA007(nodeData) {
+  const data = nodeData?.data || {};
+  const alteredCount = Object.keys(data).length;
+  if (alteredCount === 0) {
+    return { status: "ok", message: "No altered settings" };
+  }
+  return {
+    status: "info",
+    message: `${alteredCount} setting${alteredCount > 1 ? "s" : ""} altered from defaults`
+  };
+}
+function formatBytes(bytes) {
+  if (bytes === 0)
+    return "0 B";
+  if (bytes < 1024)
+    return `${bytes} B`;
+  if (bytes < 1024 * 1024)
+    return `${(bytes / 1024).toFixed(0)} KiB`;
+  if (bytes < 1024 * 1024 * 1024)
+    return `${(bytes / (1024 * 1024)).toFixed(0)} MiB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GiB`;
+}
+function summarizeH001(nodeData) {
+  const data = nodeData?.data || {};
+  let totalCount = 0;
+  let totalSize = 0;
+  for (const dbData of Object.values(data)) {
+    const dbEntry = dbData;
+    totalCount += dbEntry.total_count || 0;
+    totalSize += dbEntry.total_size_bytes || 0;
+  }
+  if (totalCount === 0) {
+    return { status: "ok", message: "No invalid indexes" };
+  }
+  return {
+    status: "warning",
+    message: `Found ${totalCount} invalid index${totalCount > 1 ? "es" : ""} (${formatBytes(totalSize)})`
+  };
+}
+function summarizeH002(nodeData) {
+  const data = nodeData?.data || {};
+  let totalCount = 0;
+  let totalSize = 0;
+  for (const dbData of Object.values(data)) {
+    const dbEntry = dbData;
+    totalCount += dbEntry.total_count || 0;
+    totalSize += dbEntry.total_size_bytes || 0;
+  }
+  if (totalCount === 0) {
+    return { status: "ok", message: "All indexes utilized" };
+  }
+  return {
+    status: "warning",
+    message: `Found ${totalCount} unused index${totalCount > 1 ? "es" : ""} (${formatBytes(totalSize)})`
+  };
+}
+function summarizeH004(nodeData) {
+  const data = nodeData?.data || {};
+  let totalCount = 0;
+  let totalSize = 0;
+  for (const dbData of Object.values(data)) {
+    const dbEntry = dbData;
+    totalCount += dbEntry.total_count || 0;
+    totalSize += dbEntry.total_size_bytes || 0;
+  }
+  if (totalCount === 0) {
+    return { status: "ok", message: "No redundant indexes" };
+  }
+  return {
+    status: "warning",
+    message: `Found ${totalCount} redundant index${totalCount > 1 ? "es" : ""} (${formatBytes(totalSize)})`
+  };
+}
+function summarizeA002(nodeData) {
+  const ver = nodeData?.data?.version;
+  if (!ver) {
+    return { status: "info", message: "Version checked" };
   }
-  return result;
+  const major = parseInt(ver.server_major_ver, 10);
+  if (major >= 17) {
+    return { status: "ok", message: `PostgreSQL ${major}` };
+  }
+  if (major >= 15) {
+    return { status: "info", message: `PostgreSQL ${major}` };
+  }
+  return {
+    status: "warning",
+    message: `PostgreSQL ${major} (consider upgrading)`
+  };
+}
+function summarizeA013(nodeData) {
+  const ver = nodeData?.data?.version;
+  if (!ver) {
+    return { status: "info", message: "Minor version checked" };
+  }
+  const current = ver.version || "";
+  return {
+    status: "info",
+    message: `Version ${current}`
+  };
+}
+function summarizeD001(nodeData) {
+  const data = nodeData?.data || {};
+  const settingsCount = Object.keys(data).length;
+  if (settingsCount === 0) {
+    return { status: "info", message: "No logging settings found" };
+  }
+  return {
+    status: "info",
+    message: `${settingsCount} logging setting${settingsCount > 1 ? "s" : ""} collected`
+  };
+}
+function summarizeD004(nodeData) {
+  const data = nodeData?.data || {};
+  const settingsCount = Object.keys(data).length;
+  if (settingsCount === 0) {
+    return { status: "info", message: "No pg_stat_statements settings found" };
+  }
+  return {
+    status: "info",
+    message: `${settingsCount} pg_stat_statements setting${settingsCount > 1 ? "s" : ""} collected`
+  };
+}
+function summarizeF001(nodeData) {
+  const data = nodeData?.data || {};
+  const settingsCount = Object.keys(data).length;
+  if (settingsCount === 0) {
+    return { status: "info", message: "No autovacuum settings found" };
+  }
+  return {
+    status: "info",
+    message: `${settingsCount} autovacuum setting${settingsCount > 1 ? "s" : ""} collected`
+  };
+}
+function summarizeF002(nodeData) {
+  if (nodeData?.data?.settings_available === false) {
+    return { status: "info", message: "Wraparound settings unavailable" };
+  }
+  const severity = nodeData?.data?.severity;
+  const databases = nodeData?.data?.databases?.length || 0;
+  const tables = nodeData?.data?.tables || [];
+  const offenders = tables.filter((table) => table?.xid?.severity !== "info" || table?.multixact?.severity !== "info").length;
+  if (!severity)
+    return { status: "info", message: "No wraparound data" };
+  if (severity === "info") {
+    return { status: "ok", message: `${databases} database${databases === 1 ? "" : "s"} below wraparound thresholds` };
+  }
+  return {
+    status: "warning",
+    message: `${severity.toUpperCase()} wraparound risk${offenders ? `; ${offenders} table${offenders === 1 ? "" : "s"} affected` : ""}`
+  };
+}
+function summarizeF003(nodeData) {
+  const data = nodeData?.data || {};
+  let flaggedCount = 0;
+  let disabledCount = 0;
+  for (const dbData of Object.values(data)) {
+    const dbEntry = dbData;
+    flaggedCount += dbEntry.flagged_count || 0;
+    disabledCount += dbEntry.autovacuum_disabled_flagged_count || 0;
+  }
+  if (flaggedCount === 0 && disabledCount === 0) {
+    return { status: "ok", message: "No significant dead tuple accumulation" };
+  }
+  const parts = [];
+  if (flaggedCount > 0) {
+    parts.push(`${flaggedCount} table${flaggedCount > 1 ? "s" : ""} with excessive dead tuples`);
+  }
+  if (disabledCount > 0) {
+    parts.push(`${disabledCount} table${disabledCount > 1 ? "s" : ""} with autovacuum disabled`);
+  }
+  return { status: "warning", message: parts.join(", ") };
+}
+function summarizeF009(nodeData) {
+  const data = nodeData?.data || {};
+  if (data.skipped) {
+    return { status: "info", message: data.skip_reason || "Primary-only check skipped on replica" };
+  }
+  const severity = String(data.severity || "OK");
+  const age = Math.max(Number(data.data_horizon_age_tx || 0), Number(data.catalog_horizon_age_tx || 0));
+  if (severity === "OK") {
+    return { status: "ok", message: `Xmin horizons healthy (oldest holder: ${age} transactions)` };
+  }
+  const holder = data.dominant_holder?.source ? `; dominant holder: ${data.dominant_holder.source}` : "";
+  const activityAgeSeconds = Number(data.components?.pg_stat_activity?.top_blocker?.xact_age_seconds || 0);
+  if (severity === "NOTICE" && data.data_horizon_severity === "OK" && data.catalog_horizon_severity === "OK" && activityAgeSeconds > 0) {
+    return {
+      status: "info",
+      message: `NOTICE: transaction open for ${activityAgeSeconds} seconds${holder}`
+    };
+  }
+  return {
+    status: severity === "NOTICE" ? "info" : "warning",
+    message: `${severity}: xmin horizon age ${age} transactions${holder}`
+  };
+}
+function summarizeBloat(nodeData, kind) {
+  const data = nodeData?.data || {};
+  let totalCount = 0;
+  for (const dbData of Object.values(data)) {
+    const dbEntry = dbData;
+    if (dbEntry?.status?.ok === false) {
+      const reason = String(dbEntry.status.reason || "query_error").replaceAll("_", " ");
+      return { status: "warning", message: `Bloat estimate degraded: ${reason}` };
+    }
+    totalCount += dbEntry?.total_count || 0;
+  }
+  if (totalCount === 0) {
+    return { status: "ok", message: `No bloated ${kind}${kind === "index" ? "es" : "s"} found` };
+  }
+  return {
+    status: "warning",
+    message: `Found ${totalCount} bloated ${kind}${totalCount === 1 ? "" : kind === "index" ? "es" : "s"}`
+  };
+}
+function summarizeG001(nodeData) {
+  const data = nodeData?.data || {};
+  const settingsCount = Object.keys(data).length;
+  if (settingsCount === 0) {
+    return { status: "info", message: "No memory settings found" };
+  }
+  return {
+    status: "info",
+    message: `${settingsCount} memory setting${settingsCount > 1 ? "s" : ""} collected`
+  };
+}
+function summarizeG003(nodeData) {
+  const data = nodeData?.data || {};
+  const settings = data.settings || {};
+  const deadlockStats = data.deadlock_stats;
+  const settingsCount = Object.keys(settings).length;
+  if (deadlockStats && typeof deadlockStats.deadlocks === "number" && deadlockStats.deadlocks > 0) {
+    return {
+      status: "warning",
+      message: `${deadlockStats.deadlocks} deadlock${deadlockStats.deadlocks > 1 ? "s" : ""} detected`
+    };
+  }
+  if (settingsCount === 0) {
+    return { status: "info", message: "No timeout/lock settings found" };
+  }
+  return {
+    status: "info",
+    message: `${settingsCount} timeout/lock setting${settingsCount > 1 ? "s" : ""} collected`
+  };
 }
 
 // lib/checkup.ts
 var __dirname = "/builds/postgres-ai/postgresai/cli/lib";
+var CONTRACT_VERSION = "1.0.0";
 var SECONDS_PER_DAY = 86400;
 var SECONDS_PER_HOUR = 3600;
 var SECONDS_PER_MINUTE = 60;
 function toBool(val) {
   return val === true || val === 1 || val === "t" || val === "true";
 }
+var F002_WRAPAROUND_LIMIT = 2147483648;
+var F002_CRITICAL_AGE = 1e9;
+var F002_FAILSAFE_HIGH_PCT = 80;
+var severityRank = {
+  info: 0,
+  warning: 1,
+  high: 2,
+  critical: 3
+};
+function evaluateWraparoundRisk(age, emergencyAge, failsafeAge) {
+  let severity = "info";
+  if (emergencyAge <= 0) {
+    severity = "info";
+  } else if (age >= F002_CRITICAL_AGE) {
+    severity = "critical";
+  } else if (age >= 2 * emergencyAge || failsafeAge !== null && age >= failsafeAge * (F002_FAILSAFE_HIGH_PCT / 100)) {
+    severity = "high";
+  } else if (age >= emergencyAge) {
+    severity = "warning";
+  }
+  const pct = (value, limit) => limit > 0 ? Math.round(value / limit * 1e4) / 100 : 0;
+  return {
+    age,
+    emergency_age: emergencyAge,
+    failsafe_age: failsafeAge,
+    pct_towards_wraparound: pct(age, F002_WRAPAROUND_LIMIT),
+    pct_towards_emergency: pct(age, emergencyAge),
+    pct_towards_failsafe: failsafeAge === null ? null : pct(age, failsafeAge),
+    severity
+  };
+}
+function maxSeverity(...severities) {
+  return severities.reduce((max, value) => severityRank[value] > severityRank[max] ? value : max, "info");
+}
 var F003_DEAD_TUPLES_MIN = 1e5;
 var F003_DEAD_PCT_MIN = 20;
 var F003_AUTOVACUUM_DISABLED_MIN_ROWS = 1e4;
@@ -32053,11 +33912,11 @@ function parseVersionNum(versionNum) {
     return { major: "", minor: "" };
   }
 }
-function formatBytes(bytes) {
+function formatBytes2(bytes) {
   if (bytes === 0)
     return "0 B";
   if (bytes < 0)
-    return `-${formatBytes(-bytes)}`;
+    return `-${formatBytes2(-bytes)}`;
   if (!Number.isFinite(bytes))
     return `${bytes} B`;
   const units = ["B", "KiB", "MiB", "GiB", "TiB", "PiB"];
@@ -32069,7 +33928,7 @@ function formatSettingPrettyValue(settingNormalized, unitNormalized, rawValue) {
     return rawValue;
   }
   if (unitNormalized === "bytes") {
-    return formatBytes(settingNormalized);
+    return formatBytes2(settingNormalized);
   }
   if (unitNormalized === "seconds") {
     const MS_PER_SECOND = 1000;
@@ -32243,7 +34102,7 @@ async function getClusterInfo(client, pgMajorVersion = 16) {
     };
     const tempBytes = parseInt(stats.temp_bytes || "0", 10);
     info.temp_bytes_written = {
-      value: formatBytes(tempBytes),
+      value: formatBytes2(tempBytes),
       unit: "bytes",
       description: "Total temporary file bytes written"
     };
@@ -32309,7 +34168,7 @@ async function getInvalidIndexes(client, pgMajorVersion = 16) {
       index_name: String(transformed.index_name || ""),
       relation_name: String(transformed.relation_name || ""),
       index_size_bytes: indexSizeBytes,
-      index_size_pretty: formatBytes(indexSizeBytes),
+      index_size_pretty: formatBytes2(indexSizeBytes),
       index_definition: String(transformed.index_definition || ""),
       supports_fk: toBool(transformed.supports_fk),
       is_pk: toBool(transformed.is_pk),
@@ -32338,7 +34197,7 @@ async function getUnusedIndexes(client, pgMajorVersion = 16) {
       index_size_bytes: indexSizeBytes,
       idx_is_btree: toBool(transformed.idx_is_btree),
       supports_fk: toBool(transformed.supports_fk),
-      index_size_pretty: formatBytes(indexSizeBytes)
+      index_size_pretty: formatBytes2(indexSizeBytes)
     };
   });
 }
@@ -32411,7 +34270,7 @@ async function getRedundantIndexes(client, pgMajorVersion = 16) {
             index_name: String(item.index_name ?? ""),
             index_definition: String(item.index_definition ?? ""),
             index_size_bytes: sizeBytes,
-            index_size_pretty: formatBytes(sizeBytes)
+            index_size_pretty: formatBytes2(sizeBytes)
           };
         });
       }
@@ -32433,8 +34292,8 @@ async function getRedundantIndexes(client, pgMajorVersion = 16) {
       index_usage: parseInt(String(transformed.index_usage || 0), 10),
       supports_fk: toBool(transformed.supports_fk),
       index_definition: String(transformed.index_definition || ""),
-      index_size_pretty: formatBytes(indexSizeBytes),
-      table_size_pretty: formatBytes(tableSizeBytes),
+      index_size_pretty: formatBytes2(indexSizeBytes),
+      table_size_pretty: formatBytes2(tableSizeBytes),
       redundant_to: redundantTo
     };
     if (parseError) {
@@ -32469,12 +34328,103 @@ async function getDeadTuples(client, pgMajorVersion = 16) {
       vacuum_count: parseInt(String(t.vacuum_count || 0), 10),
       autovacuum_disabled: autovacuumDisabled,
       table_size_bytes: tableSizeBytes,
-      table_size_pretty: formatBytes(tableSizeBytes),
+      table_size_pretty: formatBytes2(tableSizeBytes),
       exceeds_dead_tuple_thresholds: nDead >= F003_DEAD_TUPLES_MIN && deadPct >= F003_DEAD_PCT_MIN,
       autovacuum_disabled_flagged: autovacuumDisabled && nLive + nDead >= F003_AUTOVACUUM_DISABLED_MIN_ROWS
     };
   });
 }
+async function getWraparoundData(client, pgMajorVersion = 16) {
+  const [settingsResult, databaseResult, tableResult, multixactSizeResult] = await Promise.all([
+    client.query(getMetricSql(METRIC_NAMES.F002Settings, pgMajorVersion)),
+    client.query(getMetricSql(METRIC_NAMES.F002Database, pgMajorVersion)),
+    client.query(getMetricSql(METRIC_NAMES.F002Tables, pgMajorVersion)),
+    client.query(getMetricSql(METRIC_NAMES.F002MultixactSize, pgMajorVersion))
+  ]);
+  const numberValue = (value) => parseInt(String(value ?? 0), 10) || 0;
+  const rawSettings = settingsResult.rows[0] || {};
+  const failsafe3 = pgMajorVersion >= 14 ? numberValue(rawSettings.vacuum_failsafe_age) : 0;
+  const multixactFailsafe = pgMajorVersion >= 14 ? numberValue(rawSettings.vacuum_multixact_failsafe_age) : 0;
+  const settings = {
+    autovacuum_freeze_max_age: numberValue(rawSettings.autovacuum_freeze_max_age),
+    vacuum_freeze_min_age: numberValue(rawSettings.vacuum_freeze_min_age),
+    vacuum_freeze_table_age: numberValue(rawSettings.vacuum_freeze_table_age),
+    autovacuum_multixact_freeze_max_age: numberValue(rawSettings.autovacuum_multixact_freeze_max_age),
+    vacuum_multixact_freeze_min_age: numberValue(rawSettings.vacuum_multixact_freeze_min_age),
+    vacuum_multixact_freeze_table_age: numberValue(rawSettings.vacuum_multixact_freeze_table_age),
+    vacuum_failsafe_age: failsafe3 > 0 ? failsafe3 : null,
+    vacuum_multixact_failsafe_age: multixactFailsafe > 0 ? multixactFailsafe : null
+  };
+  const settings_available = settings.autovacuum_freeze_max_age > 0 && settings.autovacuum_multixact_freeze_max_age > 0;
+  const databases = databaseResult.rows.map((row) => {
+    const xidAge = numberValue(row.age_datfrozenxid);
+    const multixactAge = numberValue(row.age_datminmxid);
+    return {
+      database_name: String(row.tag_datname || ""),
+      xid: evaluateWraparoundRisk(xidAge, settings.autovacuum_freeze_max_age, settings.vacuum_failsafe_age),
+      multixact: evaluateWraparoundRisk(multixactAge, settings.autovacuum_multixact_freeze_max_age, settings.vacuum_multixact_failsafe_age)
+    };
+  }).sort((a, b) => Math.max(b.xid.age, b.multixact.age) - Math.max(a.xid.age, a.multixact.age));
+  const tables = tableResult.rows.map((row) => {
+    const xidAge = numberValue(row.xid_age);
+    const multixactAge = numberValue(row.multixact_age);
+    const tableSizeBytes = numberValue(row.table_size_bytes);
+    return {
+      database_name: String(row.tag_datname || ""),
+      schema_name: String(row.tag_schema_name || ""),
+      table_name: String(row.tag_table_name || ""),
+      ranked_by: String(row.tag_ranked_by || "").split(",").filter(Boolean),
+      table_size_bytes: tableSizeBytes,
+      table_size_pretty: formatBytes2(tableSizeBytes),
+      xid: evaluateWraparoundRisk(xidAge, numberValue(row.effective_freeze_max_age) || settings.autovacuum_freeze_max_age, settings.vacuum_failsafe_age),
+      multixact: evaluateWraparoundRisk(multixactAge, numberValue(row.effective_multixact_freeze_max_age) || settings.autovacuum_multixact_freeze_max_age, settings.vacuum_multixact_failsafe_age)
+    };
+  }).sort((a, b) => Math.max(b.xid.age, b.multixact.age) - Math.max(a.xid.age, a.multixact.age) || a.database_name.localeCompare(b.database_name) || a.schema_name.localeCompare(b.schema_name) || a.table_name.localeCompare(b.table_name));
+  const rawMultixactSize = multixactSizeResult.rows[0] || {};
+  const multixactBytes = rawMultixactSize.members_bytes === null || rawMultixactSize.members_bytes === undefined || rawMultixactSize.offsets_bytes === null || rawMultixactSize.offsets_bytes === undefined ? null : numberValue(rawMultixactSize.members_bytes) + numberValue(rawMultixactSize.offsets_bytes);
+  const multixact_size = {
+    bytes: multixactBytes,
+    size_pretty: multixactBytes === null ? null : formatBytes2(multixactBytes),
+    status_code: numberValue(rawMultixactSize.status_code)
+  };
+  return { settings, databases, tables, multixact_size, settings_available };
+}
+function buildWraparoundConclusions(databases, tables, settingsAvailable = true) {
+  if (!settingsAvailable) {
+    return {
+      severity: "info",
+      conclusions: ["Wraparound settings are unavailable; severity could not be evaluated."],
+      recommendations: ["Verify pg_settings_wraparound collection and rerun F002 before assessing wraparound risk."]
+    };
+  }
+  const offenders = [
+    ...databases.flatMap((db) => [
+      { name: `database "${db.database_name}"`, kind: "transaction ID", risk: db.xid },
+      { name: `database "${db.database_name}"`, kind: "MultiXact", risk: db.multixact }
+    ]),
+    ...tables.flatMap((table) => [
+      { name: `table "${table.database_name}"."${table.schema_name}"."${table.table_name}"`, kind: "transaction ID", risk: table.xid },
+      { name: `table "${table.database_name}"."${table.schema_name}"."${table.table_name}"`, kind: "MultiXact", risk: table.multixact }
+    ])
+  ].filter((item) => item.risk.severity !== "info").sort((a, b) => severityRank[b.risk.severity] - severityRank[a.risk.severity] || b.risk.age - a.risk.age);
+  const severity = maxSeverity(...offenders.map((item) => item.risk.severity));
+  if (offenders.length === 0) {
+    return {
+      severity,
+      conclusions: ["Transaction ID and MultiXact ages are below their emergency vacuum thresholds."],
+      recommendations: []
+    };
+  }
+  const conclusions = offenders.slice(0, 10).map((item) => `${item.name} has ${item.kind} age ${item.risk.age.toLocaleString("en-US")} ` + `(${item.risk.pct_towards_emergency}% of its emergency vacuum threshold; ${item.risk.severity}).`);
+  const recommendations = [
+    "Check pg_stat_activity for 'autovacuum: %to prevent wraparound%' workers and inspect pg_stat_progress_vacuum for progress.",
+    "Check xmin-horizon holders (long transactions, stale replication slots, and prepared transactions) and the F003 autovacuum queue analysis; high age is usually a symptom of vacuum starvation or a blocked horizon."
+  ];
+  if (severity === "high" || severity === "critical") {
+    recommendations.push("Run VACUUM (FREEZE, VERBOSE) on the highest-age offender tables after confirming operational impact. Do not raise freeze_max_age merely to silence the check; that reduces the remaining safety margin.");
+  }
+  return { severity, conclusions, recommendations };
+}
 function buildDeadTuplesConclusions(tables) {
   const conclusions = [];
   const recommendations = [];
@@ -32498,6 +34448,7 @@ function buildDeadTuplesConclusions(tables) {
 function createBaseReport(checkId, checkTitle, nodeName) {
   const buildTs = resolveBuildTs();
   return {
+    contract_version: CONTRACT_VERSION,
     version: version || null,
     build_ts: buildTs,
     generation_mode: "express",
@@ -32572,9 +34523,9 @@ async function generateIndexReport(client, nodeName, checkId, checkTitle, indexF
     [indexFieldName]: indexes,
     total_count: totalCount,
     total_size_bytes: totalSizeBytes,
-    total_size_pretty: formatBytes(totalSizeBytes),
+    total_size_pretty: formatBytes2(totalSizeBytes),
     database_size_bytes: dbSizeBytes,
-    database_size_pretty: formatBytes(dbSizeBytes)
+    database_size_pretty: formatBytes2(dbSizeBytes)
   };
   if (extraFields) {
     Object.assign(dbEntry, await extraFields(client, pgMajorVersion));
@@ -32758,6 +34709,33 @@ async function generateF001(client, nodeName) {
   };
   return report;
 }
+async function generateF002(client, nodeName) {
+  const report = createBaseReport("F002", "Autovacuum: transaction ID and MultiXact wraparound", nodeName);
+  const postgresVersion = await getPostgresVersion(client);
+  const pgMajorVersion = parseInt(postgresVersion.server_major_ver, 10) || 16;
+  const { settings, databases, tables, multixact_size, settings_available } = await getWraparoundData(client, pgMajorVersion);
+  const { severity, conclusions, recommendations } = buildWraparoundConclusions(databases, tables, settings_available);
+  report.results[nodeName] = {
+    data: {
+      settings,
+      databases,
+      tables,
+      multixact_size,
+      settings_available,
+      severity,
+      thresholds: {
+        wraparound_limit: F002_WRAPAROUND_LIMIT,
+        critical_age: F002_CRITICAL_AGE,
+        failsafe_high_pct: F002_FAILSAFE_HIGH_PCT,
+        table_limit_per_age: 50
+      },
+      conclusions,
+      recommendations
+    },
+    postgres_version: postgresVersion
+  };
+  return report;
+}
 async function generateF003(client, nodeName) {
   const report = createBaseReport("F003", "Autovacuum: dead tuples", nodeName);
   const postgresVersion = await getPostgresVersion(client);
@@ -32784,7 +34762,7 @@ async function generateF003(client, nodeName) {
     conclusions,
     recommendations,
     database_size_bytes: dbSizeBytes,
-    database_size_pretty: formatBytes(dbSizeBytes)
+    database_size_pretty: formatBytes2(dbSizeBytes)
   };
   report.results[nodeName] = {
     data: { [dbName]: dbEntry },
@@ -32792,6 +34770,185 @@ async function generateF003(client, nodeName) {
   };
   return report;
 }
+var F009_NOTICE_FRACTION = 0.1;
+var F009_WARNING_FRACTION = 0.5;
+var F009_CRITICAL_FRACTION = 0.8;
+var F009_ACTIVITY_NOTICE_SECONDS = SECONDS_PER_HOUR;
+var F009_SEVERITY_RANK = {
+  OK: 0,
+  NOTICE: 1,
+  WARNING: 2,
+  CRITICAL: 3
+};
+function numberValue(value) {
+  const parsed = Number(value ?? 0);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+function parseJsonObject(value) {
+  if (value && typeof value === "object")
+    return value;
+  if (typeof value === "string") {
+    try {
+      const parsed = JSON.parse(value);
+      if (parsed && typeof parsed === "object")
+        return parsed;
+    } catch {}
+  }
+  return {};
+}
+function normalizeF009Components(value) {
+  const raw = parseJsonObject(value);
+  const component = (name) => {
+    const item = parseJsonObject(raw[name]);
+    const detail = item.top_blocker;
+    return {
+      age_tx: numberValue(item.age_tx),
+      count: numberValue(item.count),
+      top_blocker: detail && typeof detail === "object" ? detail : null
+    };
+  };
+  return {
+    pg_stat_activity: component("pg_stat_activity"),
+    pg_replication_slots: component("pg_replication_slots"),
+    pg_replication_slots_catalog: component("pg_replication_slots_catalog"),
+    pg_stat_replication: component("pg_stat_replication"),
+    pg_prepared_xacts: component("pg_prepared_xacts")
+  };
+}
+function getF009Severity(ageTx, freezeMaxAge) {
+  if (freezeMaxAge <= 0)
+    return "OK";
+  const fraction = ageTx / freezeMaxAge;
+  if (fraction >= F009_CRITICAL_FRACTION)
+    return "CRITICAL";
+  if (fraction >= F009_WARNING_FRACTION)
+    return "WARNING";
+  if (fraction >= F009_NOTICE_FRACTION)
+    return "NOTICE";
+  return "OK";
+}
+function selectF009DominantHolder(components) {
+  const candidates = [];
+  const add = (source, component, horizonType, priority) => {
+    const item = components[component];
+    if (item.count > 0 && item.top_blocker) {
+      candidates.push({ source, component, horizon_type: horizonType, age_tx: item.age_tx, detail: item.top_blocker, priority });
+    }
+  };
+  add("slot", "pg_replication_slots", "data", 4);
+  add("slot", "pg_replication_slots_catalog", "catalog", 4);
+  add("prepared", "pg_prepared_xacts", "data", 3);
+  add("activity", "pg_stat_activity", "data", 2);
+  add("replication", "pg_stat_replication", "data", 1);
+  candidates.sort((a, b) => b.age_tx - a.age_tx || b.priority - a.priority || a.component.localeCompare(b.component));
+  if (candidates.length === 0)
+    return null;
+  const { priority: _priority, ...dominant } = candidates[0];
+  return dominant;
+}
+function sqlLiteral(value) {
+  return String(value ?? "").replace(/'/g, "''");
+}
+function buildF009Analysis(components, dominantHolder, dataSeverity, catalogSeverity, options) {
+  const conclusions = [];
+  const recommendations = [];
+  if (options.skipped) {
+    return { conclusions: ["INFO: xmin horizon analysis is primary-only; this replica was skipped."], recommendations };
+  }
+  if (options.limitedVisibility) {
+    conclusions.push("NOTICE: the check ran with limited visibility; sessions owned by other users may hide query text or xmin details. Grant pg_monitor or pg_read_all_stats for complete RCA context.");
+  }
+  if (options.historyDetected) {
+    conclusions.push("INFO: pg_flight_recorder detected — historical xmin timeline is available via pgfr_analyze.xmin_horizon_history().");
+  }
+  const dataAge = Math.max(components.pg_stat_activity.age_tx, components.pg_replication_slots.age_tx, components.pg_stat_replication.age_tx, components.pg_prepared_xacts.age_tx);
+  const catalogAge = components.pg_replication_slots_catalog.age_tx;
+  if (dataSeverity !== "OK")
+    conclusions.push(`${dataSeverity}: data xmin horizon age is ${dataAge} transactions.`);
+  if (catalogSeverity !== "OK")
+    conclusions.push(`${catalogSeverity}: catalog xmin horizon age is ${catalogAge} transactions.`);
+  const activity = components.pg_stat_activity.top_blocker;
+  const xactAgeSeconds = numberValue(activity?.xact_age_seconds);
+  if (activity && xactAgeSeconds >= F009_ACTIVITY_NOTICE_SECONDS) {
+    conclusions.push(`NOTICE: activity PID ${activity.pid} has held a transaction open for ${xactAgeSeconds} seconds.`);
+  }
+  if (!dominantHolder) {
+    if (conclusions.length === 0)
+      conclusions.push("OK: no xmin horizon blocker is currently visible.");
+    return { conclusions, recommendations };
+  }
+  const d = dominantHolder.detail;
+  conclusions.unshift(`${dataSeverity === "OK" && catalogSeverity === "OK" ? "INFO" : "CAUSE"}: dominant xmin holder is ${dominantHolder.source} (${dominantHolder.age_tx} transactions, ${dominantHolder.horizon_type} horizon).`);
+  if (dominantHolder.source === "activity") {
+    const pid = numberValue(d.pid);
+    const backendType = String(d.backend_type || "").toLowerCase();
+    const state = String(d.state || "").toLowerCase();
+    if (backendType.includes("autovacuum")) {
+      recommendations.push(`Inspect pg_stat_progress_vacuum for autovacuum worker PID ${pid}; do not kill it until its progress and table size are understood.`);
+    } else if (state.includes("idle in transaction")) {
+      recommendations.push(`Terminate the idle-in-transaction holder with SELECT pg_terminate_backend(${pid}); pg_cancel_backend() is a no-op while it is idle. Prevent recurrence with idle_in_transaction_session_timeout.`);
+    } else {
+      recommendations.push(`Cancel the active statement first with SELECT pg_cancel_backend(${pid}); if backend_xmin reappears, the query is inside an explicit BEGIN and SELECT pg_terminate_backend(${pid}) may be required. Prevent recurrence with statement_timeout and, on PostgreSQL 17+, transaction_timeout.`);
+    }
+  } else if (dominantHolder.source === "slot") {
+    const slotName = sqlLiteral(d.slot_name);
+    recommendations.push(`Confirm subscriber state for replication slot '${slotName}' before intervening. Then advance it with pg_replication_slot_advance() or, only if obsolete, SELECT pg_drop_replication_slot('${slotName}'). Slot status=${d.status || "unknown"}, wal_status=${d.wal_status || "unknown"}.`);
+  } else if (dominantHolder.source === "replication") {
+    recommendations.push(`On standby '${d.application_name || "unknown"}', find and cancel the long query responsible for hot_standby_feedback. Do not disable hot_standby_feedback as a first response; that trades xmin holdback for recovery-conflict cancellations.`);
+  } else {
+    const gid = sqlLiteral(d.gid);
+    recommendations.push(`After confirming the transaction outcome, resolve the prepared transaction with ROLLBACK PREPARED '${gid}'. Owner=${d.owner || "unknown"}, database=${d.database || "unknown"}, prepared_at=${d.prepared_at || "unknown"}.`);
+  }
+  return { conclusions, recommendations };
+}
+async function generateF009(client, nodeName) {
+  const report = createBaseReport("F009", "Xmin horizon and blockers", nodeName);
+  const postgresVersion = await getPostgresVersion(client);
+  const pgMajorVersion = parseInt(postgresVersion.server_major_ver, 10) || 16;
+  const result = await client.query(getMetricSql(METRIC_NAMES.F009, pgMajorVersion));
+  const row = result.rows[0] || {};
+  const components = normalizeF009Components(row.components);
+  const skipped = toBool(row.is_in_recovery);
+  const freezeMaxAge = numberValue(row.autovacuum_freeze_max_age);
+  const dataAge = numberValue(row.data_horizon_age_tx);
+  const catalogAge = numberValue(row.catalog_horizon_age_tx);
+  const dataSeverity = skipped ? "OK" : getF009Severity(dataAge, freezeMaxAge);
+  const catalogSeverity = skipped ? "OK" : getF009Severity(catalogAge, freezeMaxAge);
+  const activityAgeSeconds = numberValue(components.pg_stat_activity.top_blocker?.xact_age_seconds);
+  let severity = F009_SEVERITY_RANK[dataSeverity] >= F009_SEVERITY_RANK[catalogSeverity] ? dataSeverity : catalogSeverity;
+  if (severity === "OK" && activityAgeSeconds >= F009_ACTIVITY_NOTICE_SECONDS)
+    severity = "NOTICE";
+  const dominantHolder = skipped ? null : selectF009DominantHolder(components);
+  const limitedVisibility = !toBool(row.has_full_visibility);
+  const historyDetected = toBool(row.pg_flight_recorder_detected);
+  const { conclusions, recommendations } = buildF009Analysis(components, dominantHolder, dataSeverity, catalogSeverity, { limitedVisibility, historyDetected, skipped });
+  const data = {
+    skipped,
+    skip_reason: row.skip_reason || null,
+    snapshot_xmin: row.snapshot_xmin === null || row.snapshot_xmin === undefined ? null : numberValue(row.snapshot_xmin),
+    data_horizon_age_tx: dataAge,
+    catalog_horizon_age_tx: catalogAge,
+    autovacuum_freeze_max_age: freezeMaxAge,
+    severity,
+    data_horizon_severity: dataSeverity,
+    catalog_horizon_severity: catalogSeverity,
+    visibility: limitedVisibility ? "limited" : "full",
+    query_preview_captured: toBool(row.query_preview_enabled) && !limitedVisibility,
+    components,
+    dominant_holder: dominantHolder,
+    conclusions,
+    recommendations
+  };
+  if (historyDetected) {
+    data.history = {
+      available: true,
+      source: "pg_flight_recorder",
+      message: "Historical xmin timeline is available via pgfr_analyze.xmin_horizon_history()."
+    };
+  }
+  report.results[nodeName] = { data, postgres_version: postgresVersion };
+  return report;
+}
 function bloatErrorStatus(err) {
   const error2 = err instanceof Error ? err.message : String(err);
   const code = typeof err === "object" && err !== null && "code" in err ? String(err.code || "") : "";
@@ -32893,9 +35050,9 @@ async function generateF004(client, nodeName) {
         fillfactor: parseInt(String(t.fillfactor || 100), 10),
         last_vacuum: vacuumInfo.last_vacuum,
         last_vacuum_epoch: vacuumInfo.last_vacuum_epoch,
-        real_size_pretty: formatBytes(realSizeBytes),
-        extra_size_pretty: formatBytes(extraSize),
-        bloat_size_pretty: formatBytes(bloatSize)
+        real_size_pretty: formatBytes2(realSizeBytes),
+        extra_size_pretty: formatBytes2(extraSize),
+        bloat_size_pretty: formatBytes2(bloatSize)
       };
     });
   } catch (err) {
@@ -32914,9 +35071,9 @@ async function generateF004(client, nodeName) {
     bloated_tables: bloatedTables,
     total_count: totalCount,
     total_bloat_size_bytes: totalBloatSizeBytes,
-    total_bloat_size_pretty: formatBytes(totalBloatSizeBytes),
+    total_bloat_size_pretty: formatBytes2(totalBloatSizeBytes),
     database_size_bytes: dbSizeBytes,
-    database_size_pretty: formatBytes(dbSizeBytes)
+    database_size_pretty: formatBytes2(dbSizeBytes)
   };
   report.results[nodeName] = {
     data: { [dbName]: dbEntry },
@@ -32976,10 +35133,10 @@ async function generateF005(client, nodeName) {
         fillfactor: parseInt(String(t.fillfactor || 90), 10),
         last_vacuum: vacuumInfo.last_vacuum,
         last_vacuum_epoch: vacuumInfo.last_vacuum_epoch,
-        real_size_pretty: formatBytes(realSizeBytes),
-        table_size_pretty: formatBytes(tableSizeBytes),
-        extra_size_pretty: formatBytes(extraSize),
-        bloat_size_pretty: formatBytes(bloatSize)
+        real_size_pretty: formatBytes2(realSizeBytes),
+        table_size_pretty: formatBytes2(tableSizeBytes),
+        extra_size_pretty: formatBytes2(extraSize),
+        bloat_size_pretty: formatBytes2(bloatSize)
       };
     });
   } catch (err) {
@@ -32998,9 +35155,9 @@ async function generateF005(client, nodeName) {
     bloated_indexes: bloatedIndexes,
     total_count: totalCount,
     total_bloat_size_bytes: totalBloatSizeBytes,
-    total_bloat_size_pretty: formatBytes(totalBloatSizeBytes),
+    total_bloat_size_pretty: formatBytes2(totalBloatSizeBytes),
     database_size_bytes: dbSizeBytes,
-    database_size_pretty: formatBytes(dbSizeBytes)
+    database_size_pretty: formatBytes2(dbSizeBytes)
   };
   report.results[nodeName] = {
     data: { [dbName]: dbEntry },
@@ -33059,19 +35216,19 @@ async function generateG001(client, nodeName) {
       const maxWorkMemUsage = workMemBytes * maxConnections;
       memoryUsage = {
         shared_buffers_bytes: sharedBuffersBytes,
-        shared_buffers_pretty: formatBytes(sharedBuffersBytes),
+        shared_buffers_pretty: formatBytes2(sharedBuffersBytes),
         wal_buffers_bytes: walBuffersBytes,
-        wal_buffers_pretty: formatBytes(walBuffersBytes),
+        wal_buffers_pretty: formatBytes2(walBuffersBytes),
         shared_memory_total_bytes: sharedMemoryTotal,
-        shared_memory_total_pretty: formatBytes(sharedMemoryTotal),
+        shared_memory_total_pretty: formatBytes2(sharedMemoryTotal),
         work_mem_per_connection_bytes: workMemBytes,
-        work_mem_per_connection_pretty: formatBytes(workMemBytes),
+        work_mem_per_connection_pretty: formatBytes2(workMemBytes),
         max_work_mem_usage_bytes: maxWorkMemUsage,
-        max_work_mem_usage_pretty: formatBytes(maxWorkMemUsage),
+        max_work_mem_usage_pretty: formatBytes2(maxWorkMemUsage),
         maintenance_work_mem_bytes: maintenanceWorkMemBytes,
-        maintenance_work_mem_pretty: formatBytes(maintenanceWorkMemBytes),
+        maintenance_work_mem_pretty: formatBytes2(maintenanceWorkMemBytes),
         effective_cache_size_bytes: effectiveCacheSizeBytes,
-        effective_cache_size_pretty: formatBytes(effectiveCacheSizeBytes)
+        effective_cache_size_pretty: formatBytes2(effectiveCacheSizeBytes)
       };
     }
   } catch (err) {
@@ -33292,9 +35449,11 @@ var REPORT_GENERATORS = {
   D001: generateD001,
   D004: generateD004,
   F001: generateF001,
+  F002: generateF002,
   F003: generateF003,
   F004: generateF004,
   F005: generateF005,
+  F009: generateF009,
   G001: generateG001,
   G003: generateG003,
   H001: generateH001,
@@ -33311,23 +35470,43 @@ var CHECK_INFO = (() => {
   }
   return filtered;
 })();
-async function generateAllReports(client, nodeName = "node-01", onProgress) {
+async function generateAllReports(client, nodeName = "node-01", onProgress, onCheckError) {
   const reports = {};
+  const failures = [];
   const entries = Object.entries(REPORT_GENERATORS);
   const total = entries.length;
   let index = 0;
   for (const [checkId, generator] of entries) {
     index += 1;
+    const checkTitle = CHECK_INFO[checkId] || checkId;
     onProgress?.({
       checkId,
-      checkTitle: CHECK_INFO[checkId] || checkId,
+      checkTitle,
       index,
       total
     });
-    reports[checkId] = await generator(client, nodeName);
+    try {
+      reports[checkId] = withCheckSummary(await generator(client, nodeName));
+    } catch (err) {
+      const failure = {
+        checkId,
+        checkTitle,
+        error: err instanceof Error ? err : new Error(String(err))
+      };
+      failures.push(failure);
+      onCheckError?.(failure);
+    }
+  }
+  if (total > 0 && Object.keys(reports).length === 0) {
+    const first = failures[0];
+    throw new Error(`All ${total} checks failed — first error (${first.checkId}): ${first.error.message}`);
   }
   return reports;
 }
+function withCheckSummary(report) {
+  report.summary = generateCheckSummary(report.checkId, report);
+  return report;
+}
 
 // lib/checkup-dictionary.ts
 var dictionaryByCode2 = new Map(CHECKUP_DICTIONARY_DATA.map((entry) => [entry.code.toUpperCase(), entry]));
@@ -33483,6 +35662,7 @@ async function postRpc(params) {
         clearTimeout(timeoutId);
         timeoutId = null;
       }
+      res.setEncoding("utf8");
       let data = "";
       res.on("data", (chunk) => data += chunk);
       res.on("end", () => {
@@ -33559,9 +35739,15 @@ async function verifyApiKey(params) {
       signal: controller.signal
     });
     await response.text().catch(() => "");
-    if (response.status === 401 || response.status === 403) {
+    if (response.status === 401) {
       return { status: "invalid", statusCode: response.status };
     }
+    if (response.status === 403) {
+      return {
+        status: "unknown",
+        detail: "HTTP 403 from GET /checkup_reports — the token may still be allowed to upload (different permission surface)"
+      };
+    }
     if (response.ok) {
       return { status: "valid" };
     }
@@ -33636,7 +35822,7 @@ async function convertCheckupReportJsonToMarkdown(params) {
 }
 
 // lib/checkup-summary.ts
-function generateCheckSummary(checkId, report) {
+function generateCheckSummary2(checkId, report) {
   const nodeIds = Object.keys(report.results || {});
   if (nodeIds.length === 0) {
     return { status: "info", message: "No data" };
@@ -33644,42 +35830,46 @@ function generateCheckSummary(checkId, report) {
   const nodeData = report.results[nodeIds[0]];
   switch (checkId) {
     case "H001":
-      return summarizeH001(nodeData);
+      return summarizeH0012(nodeData);
     case "H002":
-      return summarizeH002(nodeData);
+      return summarizeH0022(nodeData);
     case "H004":
-      return summarizeH004(nodeData);
+      return summarizeH0042(nodeData);
     case "A002":
-      return summarizeA002(nodeData);
+      return summarizeA0022(nodeData);
     case "A013":
-      return summarizeA013(nodeData);
+      return summarizeA0132(nodeData);
     case "A003":
-      return summarizeA003(nodeData);
+      return summarizeA0032(nodeData);
     case "A004":
-      return summarizeA004(nodeData);
+      return summarizeA0042(nodeData);
     case "A007":
-      return summarizeA007(nodeData);
+      return summarizeA0072(nodeData);
     case "D001":
-      return summarizeD001(nodeData);
+      return summarizeD0012(nodeData);
     case "D004":
-      return summarizeD004(nodeData);
+      return summarizeD0042(nodeData);
     case "F001":
-      return summarizeF001(nodeData);
+      return summarizeF0012(nodeData);
+    case "F002":
+      return summarizeF0022(nodeData);
     case "F003":
-      return summarizeF003(nodeData);
+      return summarizeF0032(nodeData);
     case "F004":
-      return summarizeBloat(nodeData, "table");
+      return summarizeBloat2(nodeData, "table");
     case "F005":
-      return summarizeBloat(nodeData, "index");
+      return summarizeBloat2(nodeData, "index");
+    case "F009":
+      return summarizeF0092(nodeData);
     case "G001":
-      return summarizeG001(nodeData);
+      return summarizeG0012(nodeData);
     case "G003":
-      return summarizeG003(nodeData);
+      return summarizeG0032(nodeData);
     default:
       return { status: "info", message: "Check completed" };
   }
 }
-function summarizeA003(nodeData) {
+function summarizeA0032(nodeData) {
   const data = nodeData?.data || {};
   const settingsCount = Object.keys(data).length;
   if (settingsCount === 0) {
@@ -33690,7 +35880,7 @@ function summarizeA003(nodeData) {
     message: `${settingsCount} setting${settingsCount > 1 ? "s" : ""} collected`
   };
 }
-function summarizeA004(nodeData) {
+function summarizeA0042(nodeData) {
   const data = nodeData?.data;
   if (!data) {
     return { status: "info", message: "Cluster information collected" };
@@ -33701,7 +35891,7 @@ function summarizeA004(nodeData) {
   }
   return { status: "info", message: "Cluster information collected" };
 }
-function summarizeA007(nodeData) {
+function summarizeA0072(nodeData) {
   const data = nodeData?.data || {};
   const alteredCount = Object.keys(data).length;
   if (alteredCount === 0) {
@@ -33712,7 +35902,7 @@ function summarizeA007(nodeData) {
     message: `${alteredCount} setting${alteredCount > 1 ? "s" : ""} altered from defaults`
   };
 }
-function formatBytes2(bytes) {
+function formatBytes3(bytes) {
   if (bytes === 0)
     return "0 B";
   if (bytes < 1024)
@@ -33723,7 +35913,7 @@ function formatBytes2(bytes) {
     return `${(bytes / (1024 * 1024)).toFixed(0)} MiB`;
   return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GiB`;
 }
-function summarizeH001(nodeData) {
+function summarizeH0012(nodeData) {
   const data = nodeData?.data || {};
   let totalCount = 0;
   let totalSize = 0;
@@ -33737,10 +35927,10 @@ function summarizeH001(nodeData) {
   }
   return {
     status: "warning",
-    message: `Found ${totalCount} invalid index${totalCount > 1 ? "es" : ""} (${formatBytes2(totalSize)})`
+    message: `Found ${totalCount} invalid index${totalCount > 1 ? "es" : ""} (${formatBytes3(totalSize)})`
   };
 }
-function summarizeH002(nodeData) {
+function summarizeH0022(nodeData) {
   const data = nodeData?.data || {};
   let totalCount = 0;
   let totalSize = 0;
@@ -33754,10 +35944,10 @@ function summarizeH002(nodeData) {
   }
   return {
     status: "warning",
-    message: `Found ${totalCount} unused index${totalCount > 1 ? "es" : ""} (${formatBytes2(totalSize)})`
+    message: `Found ${totalCount} unused index${totalCount > 1 ? "es" : ""} (${formatBytes3(totalSize)})`
   };
 }
-function summarizeH004(nodeData) {
+function summarizeH0042(nodeData) {
   const data = nodeData?.data || {};
   let totalCount = 0;
   let totalSize = 0;
@@ -33771,10 +35961,10 @@ function summarizeH004(nodeData) {
   }
   return {
     status: "warning",
-    message: `Found ${totalCount} redundant index${totalCount > 1 ? "es" : ""} (${formatBytes2(totalSize)})`
+    message: `Found ${totalCount} redundant index${totalCount > 1 ? "es" : ""} (${formatBytes3(totalSize)})`
   };
 }
-function summarizeA002(nodeData) {
+function summarizeA0022(nodeData) {
   const ver = nodeData?.data?.version;
   if (!ver) {
     return { status: "info", message: "Version checked" };
@@ -33791,7 +35981,7 @@ function summarizeA002(nodeData) {
     message: `PostgreSQL ${major} (consider upgrading)`
   };
 }
-function summarizeA013(nodeData) {
+function summarizeA0132(nodeData) {
   const ver = nodeData?.data?.version;
   if (!ver) {
     return { status: "info", message: "Minor version checked" };
@@ -33802,7 +35992,7 @@ function summarizeA013(nodeData) {
     message: `Version ${current}`
   };
 }
-function summarizeD001(nodeData) {
+function summarizeD0012(nodeData) {
   const data = nodeData?.data || {};
   const settingsCount = Object.keys(data).length;
   if (settingsCount === 0) {
@@ -33813,7 +36003,7 @@ function summarizeD001(nodeData) {
     message: `${settingsCount} logging setting${settingsCount > 1 ? "s" : ""} collected`
   };
 }
-function summarizeD004(nodeData) {
+function summarizeD0042(nodeData) {
   const data = nodeData?.data || {};
   const settingsCount = Object.keys(data).length;
   if (settingsCount === 0) {
@@ -33824,7 +36014,7 @@ function summarizeD004(nodeData) {
     message: `${settingsCount} pg_stat_statements setting${settingsCount > 1 ? "s" : ""} collected`
   };
 }
-function summarizeF001(nodeData) {
+function summarizeF0012(nodeData) {
   const data = nodeData?.data || {};
   const settingsCount = Object.keys(data).length;
   if (settingsCount === 0) {
@@ -33835,7 +36025,25 @@ function summarizeF001(nodeData) {
     message: `${settingsCount} autovacuum setting${settingsCount > 1 ? "s" : ""} collected`
   };
 }
-function summarizeF003(nodeData) {
+function summarizeF0022(nodeData) {
+  if (nodeData?.data?.settings_available === false) {
+    return { status: "info", message: "Wraparound settings unavailable" };
+  }
+  const severity = nodeData?.data?.severity;
+  const databases = nodeData?.data?.databases?.length || 0;
+  const tables = nodeData?.data?.tables || [];
+  const offenders = tables.filter((table) => table?.xid?.severity !== "info" || table?.multixact?.severity !== "info").length;
+  if (!severity)
+    return { status: "info", message: "No wraparound data" };
+  if (severity === "info") {
+    return { status: "ok", message: `${databases} database${databases === 1 ? "" : "s"} below wraparound thresholds` };
+  }
+  return {
+    status: "warning",
+    message: `${severity.toUpperCase()} wraparound risk${offenders ? `; ${offenders} table${offenders === 1 ? "" : "s"} affected` : ""}`
+  };
+}
+function summarizeF0032(nodeData) {
   const data = nodeData?.data || {};
   let flaggedCount = 0;
   let disabledCount = 0;
@@ -33856,7 +36064,30 @@ function summarizeF003(nodeData) {
   }
   return { status: "warning", message: parts.join(", ") };
 }
-function summarizeBloat(nodeData, kind) {
+function summarizeF0092(nodeData) {
+  const data = nodeData?.data || {};
+  if (data.skipped) {
+    return { status: "info", message: data.skip_reason || "Primary-only check skipped on replica" };
+  }
+  const severity = String(data.severity || "OK");
+  const age = Math.max(Number(data.data_horizon_age_tx || 0), Number(data.catalog_horizon_age_tx || 0));
+  if (severity === "OK") {
+    return { status: "ok", message: `Xmin horizons healthy (oldest holder: ${age} transactions)` };
+  }
+  const holder = data.dominant_holder?.source ? `; dominant holder: ${data.dominant_holder.source}` : "";
+  const activityAgeSeconds = Number(data.components?.pg_stat_activity?.top_blocker?.xact_age_seconds || 0);
+  if (severity === "NOTICE" && data.data_horizon_severity === "OK" && data.catalog_horizon_severity === "OK" && activityAgeSeconds > 0) {
+    return {
+      status: "info",
+      message: `NOTICE: transaction open for ${activityAgeSeconds} seconds${holder}`
+    };
+  }
+  return {
+    status: severity === "NOTICE" ? "info" : "warning",
+    message: `${severity}: xmin horizon age ${age} transactions${holder}`
+  };
+}
+function summarizeBloat2(nodeData, kind) {
   const data = nodeData?.data || {};
   let totalCount = 0;
   for (const dbData of Object.values(data)) {
@@ -33875,7 +36106,7 @@ function summarizeBloat(nodeData, kind) {
     message: `Found ${totalCount} bloated ${kind}${totalCount === 1 ? "" : kind === "index" ? "es" : "s"}`
   };
 }
-function summarizeG001(nodeData) {
+function summarizeG0012(nodeData) {
   const data = nodeData?.data || {};
   const settingsCount = Object.keys(data).length;
   if (settingsCount === 0) {
@@ -33886,7 +36117,7 @@ function summarizeG001(nodeData) {
     message: `${settingsCount} memory setting${settingsCount > 1 ? "s" : ""} collected`
   };
 }
-function summarizeG003(nodeData) {
+function summarizeG0032(nodeData) {
   const data = nodeData?.data || {};
   const settings = data.settings || {};
   const deadlockStats = data.deadlock_stats;
@@ -34318,7 +36549,7 @@ Checkup report uploaded`);
   for (const item of summary.uploaded) {
     const report = reports[item.checkId];
     if (report) {
-      const { status, message } = generateCheckSummary(item.checkId, report);
+      const { status, message } = generateCheckSummary2(item.checkId, report);
       const title = report.checkTitle || item.checkId;
       const isSignificant = status !== "info" || /\d/.test(message) || message.includes("PostgreSQL") || message.includes("Version");
       if (isSignificant) {
@@ -34354,6 +36585,14 @@ async function downloadText(url) {
     clearTimeout(timeout);
   }
 }
+function composeRefCandidates() {
+  return [
+    process.env.PGAI_PROJECT_REF,
+    package_default.version,
+    `v${package_default.version}`,
+    "main"
+  ].filter((v) => Boolean(v && v.trim()));
+}
 async function ensureDefaultMonitoringProject() {
   const projectDir = getDefaultMonitoringProjectDir();
   const composeFile = path7.resolve(projectDir, "docker-compose.yml");
@@ -34362,12 +36601,7 @@ async function ensureDefaultMonitoringProject() {
     fs9.mkdirSync(projectDir, { recursive: true, mode: 448 });
   }
   if (!fs9.existsSync(composeFile)) {
-    const refs = [
-      process.env.PGAI_PROJECT_REF,
-      package_default.version,
-      `v${package_default.version}`,
-      "main"
-    ].filter((v) => Boolean(v && v.trim()));
+    const refs = composeRefCandidates();
     let lastErr;
     for (const ref of refs) {
       const url = `https://gitlab.com/postgres-ai/postgres_ai/-/raw/${encodeURIComponent(ref)}/docker-compose.yml`;
@@ -34459,11 +36693,7 @@ async function refreshBundledComposeIfStale(projectDir, oldTag) {
   const composeFile = path7.resolve(projectDir, "docker-compose.yml");
   if (!fs9.existsSync(composeFile))
     return false;
-  const refs = [
-    process.env.PGAI_PROJECT_REF,
-    package_default.version,
-    `v${package_default.version}`
-  ].filter((v) => Boolean(v && v.trim()));
+  const refs = composeRefCandidates();
   const fetched = await fetchTargetCompose(refs);
   if (!fetched || !isValidComposeYaml(fetched)) {
     console.error(`\u26A0 Could not refresh docker-compose.yml to ${package_default.version} (no valid compose was retrieved).`);
@@ -34522,6 +36752,36 @@ function printResult(result, json3) {
 }
 var program2 = new Command;
 program2.name("postgres-ai").description("PostgresAI CLI").version(package_default.version).option("--api-key <key>", "API key (overrides PGAI_API_KEY)").option("--api-base-url <url>", "API base URL for backend RPC (overrides PGAI_API_BASE_URL)").option("--ui-base-url <url>", "UI base URL for browser routes (overrides PGAI_UI_BASE_URL)").option("--storage-base-url <url>", "Storage base URL for file uploads (overrides PGAI_STORAGE_BASE_URL)");
+program2.showHelpAfterError();
+program2.addHelpText("after", () => `
+\uD83D\uDCA1 Ideas / feedback: ${FEEDBACK_URL}
+`);
+program2.hook("postAction", (_thisCommand, actionCommand) => {
+  const name = actionCommand.name();
+  if (name === "feedback" || name === "help")
+    return;
+  if (process.exitCode && process.exitCode !== 0)
+    return;
+  const opts = actionCommand.opts();
+  maybeEmitFeedbackTip({
+    isTTY: !!process.stdout.isTTY,
+    json: !!opts.json,
+    suppress: process.env[FEEDBACK_SUPPRESS_ENV]
+  });
+});
+program2.command("feedback").description("share ideas or feedback about the CLI").option("--open", "open the feedback page in your browser", false).option("--json", "output the feedback URL as JSON (machine-readable)", false).action(async (opts) => {
+  if (opts.json) {
+    console.log(feedbackJson());
+    return;
+  }
+  console.log(feedbackMessage());
+  if (opts.open) {
+    const openCommand = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+      spawn2(openCommand, [FEEDBACK_URL], { detached: true, stdio: "ignore" }).unref();
+    } catch {}
+  }
+});
 program2.command("set-default-project <project>").description("store default project for checkup uploads").action(async (project) => {
   const value = (project || "").trim();
   if (!value) {
@@ -35579,9 +37839,13 @@ Usage: postgresai checkup ${checkId} postgresql://user@host:5432/dbname
       return;
     }
     let reports;
+    const failedChecks = [];
     if (checkId === "ALL") {
       reports = await generateAllReports(client, opts.nodeName, (p) => {
         spinner.update(`Running ${p.checkId}: ${p.checkTitle} (${p.index}/${p.total})`);
+      }, (failure) => {
+        failedChecks.push(failure);
+        console.error(`Warning: check ${failure.checkId} (${failure.checkTitle}) failed: ${failure.error.message} \u2014 continuing with remaining checks`);
       });
     } else {
       const generator = REPORT_GENERATORS[checkId];
@@ -35599,7 +37863,7 @@ Usage: postgresai checkup ${checkId} postgresql://user@host:5432/dbname
         return;
       }
       spinner.update(`Running ${checkId}: ${CHECK_INFO[checkId] || checkId}`);
-      reports = { [checkId]: await generator(client, opts.nodeName) };
+      reports = { [checkId]: withCheckSummary(await generator(client, opts.nodeName)) };
     }
     let uploadSummary;
     if (uploadCfg) {
@@ -35686,7 +37950,7 @@ Usage: postgresai checkup ${checkId} postgresql://user@host:5432/dbname
       const summaries = [];
       let skippedCount = 0;
       for (const [checkId2, report] of Object.entries(reports)) {
-        const { status, message } = generateCheckSummary(checkId2, report);
+        const { status, message } = generateCheckSummary2(checkId2, report);
         const title = report.checkTitle || checkId2;
         const isSignificant = status !== "info" || /\d/.test(message) || message.includes("PostgreSQL") || message.includes("Version");
         if (isSignificant) {
@@ -35709,6 +37973,11 @@ For details:`);
       }
       console.log("  --output <dir>  Save to directory");
     }
+    if (failedChecks.length > 0) {
+      const ids = failedChecks.map((f) => f.checkId).join(", ");
+      console.error(`Warning: ${failedChecks.length} of ${failedChecks.length + Object.keys(reports).length} checks failed (${ids}); results are partial`);
+      process.exitCode = 1;
+    }
   } catch (error2) {
     if (error2 instanceof RpcError) {
       for (const line of formatRpcErrorForDisplay(error2)) {
@@ -35971,7 +38240,7 @@ async function runCompose(args, grafanaPassword) {
     child.on("close", (code) => resolve8(code || 0));
   });
 }
-program2.command("help", { isDefault: true }).description("show help").action(() => {
+program2.command("help").description("show help").action(() => {
   program2.outputHelp();
 });
 var mon = program2.command("mon").description("monitoring services management");
@@ -36372,19 +38641,24 @@ Searched: ${demoCandidates.join(", ")}
       } else {
         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,
-        instancesPath,
-        vcpus: parseVcpus(opts.vcpus ?? process.env.PGAI_VCPUS),
-        apiBaseUrl: globalOpts.apiBaseUrl,
-        debug: !!process.env.DEBUG
-      });
-      if (aas.ok) {
-        console.log(`\u2713 AAS auto-collection registered
+      if (reg === null) {
+        console.error(`\u26A0 Skipping AAS auto-collection arming because instance adoption failed; it can be enabled later by re-running 'postgresai mon local-install'
 `);
       } else {
-        console.error(`\u26A0 AAS auto-collection not registered (${aas.reason}); it can be enabled later by re-running 'postgresai mon local-install'
+        const aas = await registerAasCollection(apiKey, instanceId, {
+          grafanaPassword,
+          instancesPath,
+          vcpus: parseVcpus(opts.vcpus ?? process.env.PGAI_VCPUS),
+          apiBaseUrl: globalOpts.apiBaseUrl,
+          debug: !!process.env.DEBUG
+        });
+        if (aas.ok) {
+          console.log(`\u2713 AAS auto-collection registered
+`);
+        } else {
+          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>.");
@@ -37014,7 +39288,9 @@ Opening browser for authentication...`);
 ${authUrl}
 `);
     const openCommand = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-    spawn2(openCommand, [authUrl], { detached: true, stdio: "ignore" }).unref();
+    const browserProcess = spawn2(openCommand, [authUrl], { detached: true, stdio: "ignore" });
+    browserProcess.on("error", () => {});
+    browserProcess.unref();
     console.log("Waiting for authorization...");
     console.log(`(Press Ctrl+C to cancel)
 `);
@@ -37073,10 +39349,22 @@ Please verify the --api-base-url parameter.`);
         const result = JSON.parse(exchangeBody);
         const apiToken = result.api_token || result?.[0]?.result?.api_token;
         const orgId = result.org_id || result?.[0]?.result?.org_id;
+        const tokenValid = typeof apiToken === "string" && apiToken.length > 0;
+        const orgIdValid = orgId !== undefined && orgId !== null && orgId !== "";
+        if (!tokenValid || !orgIdValid) {
+          const missingField = !tokenValid ? "an API token" : "an organization ID";
+          console.error(`Authentication failed: server response did not include ${missingField}.`);
+          console.error("Your existing configuration has been left unchanged.");
+          if (opts.debug) {
+            console.error(`Debug: exchange response body: ${exchangeBody}`);
+          }
+          process.exit(1);
+          return;
+        }
         const existingConfig = readConfig();
         const existingOrgId = existingConfig.orgId;
         const existingProject = existingConfig.defaultProject;
-        const orgChanged = existingOrgId && existingOrgId !== orgId;
+        const orgChanged = existingOrgId != null && existingOrgId !== orgId;
         writeConfig({
           apiKey: apiToken,
           baseUrl: apiBaseUrl,
@@ -38030,6 +40318,369 @@ function tryParseJson(s) {
     return s;
   }
 }
+function printJoeOutcome(outcome, json3, budgetMs) {
+  const effectiveBudgetMs = typeof budgetMs === "number" && Number.isFinite(budgetMs) ? budgetMs : DEFAULT_BUDGET_MS;
+  const budgetSeconds = Math.round(effectiveBudgetMs / 1000);
+  if (outcome.budgetExpired) {
+    if (json3) {
+      console.log(JSON.stringify({
+        command_id: outcome.commandId,
+        status: outcome.status,
+        budget_expired: true,
+        resume: `pgai joe result ${outcome.commandId}`
+      }, null, 2));
+    } else {
+      console.log(`started ${outcome.commandId} \xB7 ${outcome.status} \xB7 budget ${budgetSeconds}s reached \u2014 resume:  pgai joe result ${outcome.commandId}`);
+    }
+    return;
+  }
+  const output = outcome.output;
+  if (outcome.status === "ok") {
+    if (!output) {
+      console.error(`command ${outcome.commandId} ok but output is empty`);
+      process.exitCode = 1;
+      return;
+    }
+    if (json3)
+      console.log(JSON.stringify(output, null, 2));
+    else {
+      console.log(`command ${outcome.commandId} \xB7 ok`);
+      const body = formatJoeOutput(output);
+      if (body)
+        console.log(body);
+    }
+    return;
+  }
+  if (json3 && output)
+    console.log(JSON.stringify(output, null, 2));
+  console.error(`command ${outcome.commandId} error: ${output?.error ?? "command failed"}`);
+  process.exitCode = 1;
+}
+async function runJoeCli(command, arg, 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();
+    const instanceRef = (opts.instanceId ?? "").toString().trim();
+    if (!projectRef && !instanceRef) {
+      console.error("Specify --project <id|alias> or --instance-id <id>.");
+      process.exitCode = 1;
+      return;
+    }
+    const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+    if (typeof opts.budget === "number" && (!Number.isFinite(opts.budget) || opts.budget < 0)) {
+      throw new Error("--budget must be a non-negative number of seconds");
+    }
+    const budgetMs = typeof opts.budget === "number" ? opts.budget * 1000 : undefined;
+    const outcome = await executeJoeCommand({
+      apiKey,
+      apiBaseUrl,
+      command,
+      project: projectRef || undefined,
+      instanceId: instanceRef || undefined,
+      input: { arg, variant: opts.variant ?? null },
+      orgId: cfg.orgId ?? undefined,
+      budgetMs,
+      debug: !!opts.debug
+    });
+    printJoeOutcome(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("--instance-id <id>", "target the Joe instance id directly (skips --project resolution); required unless --project is given").option("--project <id|alias>", "target project by numeric id OR alias/name; required unless --instance-id is given").option("--budget <seconds>", "one-shot poll budget in seconds (default 25)", (v) => parseFloat(v)).option("--debug", "enable debug output").option("--json", "output raw JSON");
+}
+var joe = program2.command("joe").description("Joe \u2014 plan/EXPLAIN/exec queries on ephemeral DBLab clones. " + "All subcommands except 'result' require --project <id|alias> or --instance-id <id>.");
+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, opts);
+});
+withJoeOptions(joe.command("explain <sql>").description("EXPLAIN + EXPLAIN ANALYZE a query (EXECUTES on the ephemeral clone)")).action(async (sql, opts) => {
+  await runJoeCli("explain", sql, 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, opts);
+});
+withJoeOptions(joe.command("hypo <args>").description("HypoPG hypothetical indexes (e.g. `hypo create index on users (email)`, `hypo desc`, `hypo reset`)")).action(async (args, opts) => {
+  await runJoeCli("hypo", args, opts);
+});
+withJoeOptions(joe.command("activity").description("running-activity snapshot (pg_stat_activity) on the clone")).action(async (opts) => {
+  await runJoeCli("activity", null, opts);
+});
+withJoeOptions(joe.command("terminate <pid>").description("pg_terminate_backend(pid) on the clone")).action(async (pid, opts) => {
+  await runJoeCli("terminate", pid, opts);
+});
+withJoeOptions(joe.command("reset").description("reset/recreate the session's thin clone")).action(async (opts) => {
+  await runJoeCli("reset", 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) => {
+  await runJoeCli("describe", object4, opts);
+});
+joe.command("result <commandId>").description("fetch a Joe command's output by id (resume a budget-expired 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 output = await getCommandOutput({ apiKey, apiBaseUrl, commandId, debug: !!opts.debug });
+    if (opts.json) {
+      console.log(JSON.stringify(output, null, 2));
+      if (output.status !== "ok") {
+        process.exitCode = 1;
+      }
+      return;
+    }
+    if (output.status === "ok") {
+      console.log(`command ${output.command_id} \xB7 ok`);
+      const body = formatJoeOutput(output);
+      if (body)
+        console.log(body);
+    } else if (output.status === "error") {
+      console.error(`command ${output.command_id} error: ${output.error ?? "command failed"}`);
+      process.exitCode = 1;
+    } else {
+      console.error(`command ${output.command_id} \xB7 ${output.status} \u2014 result is not ready`);
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    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 listProjects({
+      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 resolveDblabInstanceId({ 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 (set password via PGAI_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 dbPassword = process.env.PGAI_CLONE_DB_PASSWORD;
+    if (opts.dbUser && !dbPassword || !opts.dbUser && dbPassword) {
+      throw new Error("--db-user and PGAI_CLONE_DB_PASSWORD must be provided together");
+    }
+    const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
+    const result = await createClone({
+      apiKey,
+      apiBaseUrl,
+      instanceId,
+      cloneId: opts.id,
+      branch: opts.branch,
+      snapshotId: opts.snapshot,
+      dbUser: opts.dbUser,
+      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;
+  }
+});
+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 listClones({ apiKey, apiBaseUrl, instanceId, debug: !!opts.debug });
+    printResult(result, opts.json);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    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 getClone({ 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 resetClone({
+      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 the Admin or AllFeaturesUser role)").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 destroyClone({ 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 listBranches({ 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 createBranch({
+      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 the Admin or AllFeaturesUser role)").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 deleteBranch({ 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 branchLog({ 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 listSnapshots({
+      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 createSnapshot({
+      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 the Admin or AllFeaturesUser role)").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 destroySnapshot({
+      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();
@@ -38150,9 +40801,14 @@ mcp.command("install [client]").description("install MCP server configuration fo
   }
 });
 if (__require.main == __require.module) {
-  program2.parseAsync(process.argv).finally(() => {
+  if (process.argv.length <= 2) {
+    program2.outputHelp();
     closeReadline();
-  });
+  } else {
+    program2.parseAsync(process.argv).finally(() => {
+      closeReadline();
+    });
+  }
 }
 export {
   resolveAdoptedProject,