postgresai 0.15.0 → 0.16.0-rc.0

package/dist/bin/postgres-ai.js

@@ -13334,9 +13334,11 @@ function isHtmlContent2(text) {
 function formatHttpError2(operation, status, responseBody) {
   const statusMessage = HTTP_STATUS_MESSAGES2[status] || "Request failed";
   let errMsg = `${operation}: HTTP ${status} - ${statusMessage}`;
+  const remediation = status === 401 ? `
+${AUTH_REMEDIATION_HINT2}` : "";
   if (responseBody) {
     if (isHtmlContent2(responseBody)) {
-      return errMsg;
+      return errMsg + remediation;
     }
     try {
       const errObj = JSON.parse(responseBody);
@@ -13356,7 +13358,7 @@ ${trimmed}`;
       }
     }
   }
-  return errMsg;
+  return errMsg + remediation;
 }
 function maskSecret2(secret) {
   if (!secret)
@@ -13389,7 +13391,7 @@ function resolveBaseUrls2(opts, cfg, defaults2 = {}) {
     storageBaseUrl: normalizeBaseUrl2(storageCandidate)
   };
 }
-var HTTP_STATUS_MESSAGES2;
+var HTTP_STATUS_MESSAGES2, AUTH_REMEDIATION_HINT2 = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.";
 var init_util = __esm(() => {
   HTTP_STATUS_MESSAGES2 = {
     400: "Bad Request",
@@ -13423,7 +13425,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.15.0",
+  version: "0.16.0-rc.0",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16254,7 +16256,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.15.0";
+var version = "0.16.0-rc.0";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -16395,12 +16397,15 @@ function isHtmlContent(text) {
   const trimmed = text.trim();
   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}`;
+  const remediation = status === 401 ? `
+${AUTH_REMEDIATION_HINT}` : "";
   if (responseBody) {
     if (isHtmlContent(responseBody)) {
-      return errMsg;
+      return errMsg + remediation;
     }
     try {
       const errObj = JSON.parse(responseBody);
@@ -16420,7 +16425,7 @@ ${trimmed}`;
       }
     }
   }
-  return errMsg;
+  return errMsg + remediation;
 }
 function maskSecret(secret) {
   if (!secret)
@@ -27689,7 +27694,7 @@ where
   pg_invalid_indexes: {
     description: "This metric identifies invalid indexes in the database with decision tree data for remediation. It provides insights into whether to DROP (if duplicate exists), RECREATE (if backs constraint), or flag as UNCERTAIN (if additional RCA is needed to check query plans). Decision tree: 1) Valid duplicate exists -> DROP, 2) Backs PK/UNIQUE constraint -> RECREATE, 3) Table < 10K rows -> RECREATE (small tables rebuild quickly, typically under 1 second), 4) Otherwise -> UNCERTAIN (need query plan analysis to assess impact). Adapts the top-N + `'$other$'` bucket pattern from !262 to this metric: ranks invalid indexes by `index_size_bytes desc` (ties broken by schema, table, then index name for stability), keeps the top 100, and folds the tail into a single `'$other$'` row whose `index_size_bytes` / `table_row_estimate` are summed and whose tag columns carry the literal `'$other$'` sentinel. The `'$other$'` row is omitted entirely (via `HAVING count(*) > 0`) when all invalid indexes fit within the top-100 cap, so its absence on healthy clusters is normal.",
     sqls: {
-      11: `with fk_indexes as ( /* pgwatch_generated */
+      11: `with fk_indexes as materialized ( /* pgwatch_generated */
   select
     schemaname as schema_name,
     indexrelid,
@@ -27815,7 +27820,7 @@ having count(*) > 0;
   unused_indexes: {
     description: "This metric identifies unused indexes in the database. It provides insights into the number of unused indexes and their details. This metric helps administrators identify and fix unused indexes to improve database performance. Adapts the top-N + `'$other$'` bucket pattern from !262 to this metric: within the `idx_scan = 0 AND idx_is_btree` filter, ranks indexes by `index_size_bytes desc` (ties broken by schema, table, index name), keeps the top 100, and folds the tail into a single `'$other$'` row. Counter columns (`idx_scan`, `all_scans`, `writes`, `index_size_bytes`, `table_size_bytes`, `relpages`) are summed across the tail; ratio columns (`index_scan_pct`, `scans_per_write`) and the `supports_fk` boolean are deliberately zeroed/false on the aggregate row because the tail-level average would mislead and the per-row FK relationship has no meaningful aggregate. Tag columns carry the literal `'$other$'` sentinel. The `'$other$'` row is omitted entirely (via `HAVING count(*) > 0`) when ≤100 indexes match the unused filter.",
     sqls: {
-      11: `with fk_indexes as ( /* pgwatch_generated */
+      11: `with fk_indexes as materialized ( /* pgwatch_generated */
   select
     n.nspname as schema_name,
     ci.relname as index_name,
@@ -27956,7 +27961,7 @@ having count(*) > 0;
   redundant_indexes: {
     description: "This metric identifies redundant indexes that can potentially be dropped to save storage space and improve write performance. It analyzes index relationships and finds indexes that are covered by other indexes, considering column order, operator classes, and foreign key constraints. Uses the exact logic from tmp.sql with JSON aggregation and proper thresholds. Adapts the top-N + `'$other$'` bucket pattern from !262 to this metric: ranks redundant indexes by `index_size_bytes desc` (ties broken by `table_name`), keeps the top 100, and folds the tail into a single `'$other$'` row whose `table_size_bytes`, `index_size_bytes` and `index_usage` columns are summed and whose tag columns carry the literal `'$other$'` sentinel. The `redundant_indexes_grouped` CTE intentionally preserves duplicate column aliases (`tag_schema_name` / `tag_index_name` appear twice — once from the raw name and once from the `formated_*` variant) because the dashboards rely on both spellings; the duplication is preserved on the `'$other$'` row for consistency. The `'$other$'` row is omitted entirely (via `HAVING count(*) > 0`) when there are ≤100 redundant pairs, so its absence on healthy clusters is normal.",
     sqls: {
-      11: `with fk_indexes as ( /* pgwatch_generated */
+      11: `with fk_indexes as materialized ( /* pgwatch_generated */
   select
     n.nspname as schema_name,
     ci.relname as index_name,
@@ -28163,6 +28168,64 @@ where datname = current_database()
     gauges: ["stats_reset_epoch", "seconds_since_reset"],
     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: {
+      11: `with dead_tuples as ( /* pgwatch_generated */
+  select
+    s.schemaname,
+    s.relname,
+    s.n_live_tup,
+    s.n_dead_tup,
+    coalesce(
+      round(100 * s.n_dead_tup::numeric / nullif(s.n_live_tup + s.n_dead_tup, 0), 2),
+      0
+    )::float as dead_pct,
+    extract(epoch from greatest(s.last_autovacuum, '1970-01-01Z'))::int8 as last_autovacuum,
+    extract(epoch from greatest(s.last_vacuum, '1970-01-01Z'))::int8 as last_vacuum,
+    s.autovacuum_count,
+    s.vacuum_count,
+    case when exists (
+      select 1
+      from unnest(coalesce(c.reloptions, '{}'::text[])) as opt
+      where lower(opt) ~ '^autovacuum_enabled=(false|fals|fal|fa|f|no|n|off|of|0)$'
+    ) then 1 else 0 end as autovacuum_disabled,
+    pg_table_size(c.oid) as table_size_b
+  from pg_stat_user_tables s
+  join pg_class c on c.oid = s.relid
+  where not exists (
+    select 1 from pg_locks
+    where relation = s.relid and mode = 'AccessExclusiveLock'
+  )
+), ranked as (
+  select
+    row_number() over (
+      order by n_dead_tup desc, schemaname, relname
+    ) as rownum,
+    *
+  from dead_tuples
+  where n_dead_tup > 0 or autovacuum_disabled = 1
+)
+select
+  current_database() as tag_datname,
+  schemaname as tag_schemaname,
+  relname as tag_relname,
+  n_live_tup,
+  n_dead_tup,
+  dead_pct,
+  last_autovacuum,
+  last_vacuum,
+  autovacuum_count,
+  vacuum_count,
+  autovacuum_disabled,
+  table_size_b
+from ranked
+where rownum <= 100
+`
+    },
+    gauges: ["n_live_tup", "n_dead_tup", "dead_pct", "last_autovacuum", "last_vacuum", "autovacuum_count", "vacuum_count", "autovacuum_disabled", "table_size_b"],
+    statement_timeout_seconds: 15
+  },
   pg_table_bloat: {
     description: "Estimated per-table bloat (heap pages allocated vs heap pages needed at perfect packing), bounded to the top 100 per database. Adapts the top-N + `'$other$'` bucket pattern from !262: everything below the cap is summed into a single `'$other$'` row so dashboard \"total bloat across the DB\" stays correct even when the tail is large. Ranks by `bloat_pct` descending (most-bloated tables first), with `is_na = 0` preferred (don't crowd top-N with tables whose estimate is unreliable) and stable schemaname/tblname tiebreakers. Preserves the existing >1 MiB filter (zero-byte and tiny tables aren't interesting for bloat). Aggregate semantics on the `'$other$'` row: sum for real_size_mib / extra_size / bloat_size (total wasted bytes in the tail); recompute extra_pct and bloat_pct from the summed numerator/denominator (weighted-avg effectively); avg(fillfactor); max(is_na) (any tail row with bad stats taints the aggregate). The `'$other$'` sentinel cannot collide with a real Postgres identifier.",
     sqls: {
@@ -28477,8 +28540,8 @@ group by
     (sum(coalesce(write_bytes, 0)) / 1048576.0)::int8 as write_bytes_mb,
     sum(coalesce(write_time, 0))::int8 as write_time_ms,
     sum(coalesce(writebacks, 0))::int8 as writebacks,
-    -- PostgreSQL 18 has no writeback_bytes column; rows with NULL op_bytes contribute zero by design.
-    (sum(coalesce(writebacks, 0) * coalesce(op_bytes, 0)) / 1048576.0)::int8 as writeback_bytes_mb,
+    -- PostgreSQL 18 removed the per-operation byte size column and exposes no writeback byte counts, so this is always 0.
+    0::int8 as writeback_bytes_mb,
     sum(coalesce(writeback_time, 0))::int8 as writeback_time_ms,
     sum(coalesce(fsyncs, 0))::int8 as fsyncs,
     sum(coalesce(fsync_time, 0))::int8 as fsync_time_ms,
@@ -28515,6 +28578,7 @@ var METRIC_NAMES = {
   H001: "pg_invalid_indexes",
   H002: "unused_indexes",
   H004: "redundant_indexes",
+  F003: "pg_dead_tuples",
   F004: "pg_table_bloat",
   F005: "pg_btree_bloat",
   settings: "settings",
@@ -28809,46 +28873,6 @@ var CHECKUP_DICTIONARY_DATA = [
     sort_order: null,
     is_system_report: false
   },
-  {
-    code: "F001",
-    title: "Autovacuum: current settings",
-    description: "Autovacuum configuration",
-    category: "vacuum",
-    sort_order: null,
-    is_system_report: false
-  },
-  {
-    code: "F002",
-    title: "Autovacuum: transaction ID wraparound",
-    description: "XID age and wraparound risk",
-    category: "vacuum",
-    sort_order: null,
-    is_system_report: false
-  },
-  {
-    code: "F003",
-    title: "Autovacuum: dead tuples",
-    description: "Dead tuple counts and cleanup status",
-    category: "vacuum",
-    sort_order: null,
-    is_system_report: false
-  },
-  {
-    code: "F004",
-    title: "Autovacuum: heap bloat estimate",
-    description: "Estimated table bloat",
-    category: "vacuum",
-    sort_order: null,
-    is_system_report: false
-  },
-  {
-    code: "F005",
-    title: "Autovacuum: index bloat estimate",
-    description: "Estimated index bloat",
-    category: "vacuum",
-    sort_order: null,
-    is_system_report: false
-  },
   {
     code: "F006",
     title: "Precise heap bloat analysis",
@@ -28865,14 +28889,6 @@ var CHECKUP_DICTIONARY_DATA = [
     sort_order: null,
     is_system_report: false
   },
-  {
-    code: "F008",
-    title: "Autovacuum: resource usage",
-    description: "Autovacuum I/O and CPU impact",
-    category: "vacuum",
-    sort_order: null,
-    is_system_report: false
-  },
   {
     code: "G001",
     title: "Memory-related settings",
@@ -29088,6 +29104,54 @@ var CHECKUP_DICTIONARY_DATA = [
     category: "waits",
     sort_order: null,
     is_system_report: false
+  },
+  {
+    code: "F001",
+    title: "Autovacuum settings",
+    description: "Autovacuum configuration",
+    category: "vacuum",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "F002",
+    title: "Autovacuum transaction ID wraparound",
+    description: "XID age and wraparound risk",
+    category: "vacuum",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "F003",
+    title: "Autovacuum dead tuples",
+    description: "Dead tuple counts and cleanup status",
+    category: "vacuum",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "F004",
+    title: "Autovacuum heap bloat estimate",
+    description: "Estimated table bloat",
+    category: "vacuum",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "F005",
+    title: "Autovacuum index bloat estimate",
+    description: "Estimated index bloat",
+    category: "vacuum",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "F008",
+    title: "Autovacuum resource usage",
+    description: "Autovacuum I/O and CPU impact",
+    category: "vacuum",
+    sort_order: null,
+    is_system_report: false
   }
 ];
 
@@ -29109,6 +29173,9 @@ var SECONDS_PER_MINUTE = 60;
 function toBool(val) {
   return val === true || val === 1 || val === "t" || val === "true";
 }
+var F003_DEAD_TUPLES_MIN = 1e5;
+var F003_DEAD_PCT_MIN = 20;
+var F003_AUTOVACUUM_DISABLED_MIN_ROWS = 1e4;
 function parseVersionNum(versionNum) {
   if (!versionNum || versionNum.length < 6) {
     return { major: "", minor: "" };
@@ -29515,6 +29582,58 @@ async function getRedundantIndexes(client, pgMajorVersion = 16) {
     return result2;
   });
 }
+async function getDeadTuples(client, pgMajorVersion = 16) {
+  const sql = getMetricSql(METRIC_NAMES.F003, pgMajorVersion);
+  const result = await client.query(sql);
+  return result.rows.map((row) => {
+    const t = transformMetricRow(row);
+    const nLive = parseInt(String(t.n_live_tup || 0), 10);
+    const nDead = parseInt(String(t.n_dead_tup || 0), 10);
+    const deadPct = parseFloat(String(t.dead_pct)) || 0;
+    const lastAutovacuumEpoch = parseInt(String(t.last_autovacuum || 0), 10);
+    const lastVacuumEpoch = parseInt(String(t.last_vacuum || 0), 10);
+    const autovacuumDisabled = parseInt(String(t.autovacuum_disabled || 0), 10) === 1 || toBool(t.autovacuum_disabled);
+    const tableSizeBytes = parseInt(String(t.table_size_b || 0), 10);
+    return {
+      schema_name: String(t.schemaname || ""),
+      table_name: String(t.relname || ""),
+      n_live_tup: nLive,
+      n_dead_tup: nDead,
+      dead_pct: deadPct,
+      last_autovacuum: lastAutovacuumEpoch > 0 ? new Date(lastAutovacuumEpoch * 1000).toISOString() : null,
+      last_autovacuum_epoch: lastAutovacuumEpoch,
+      last_vacuum: lastVacuumEpoch > 0 ? new Date(lastVacuumEpoch * 1000).toISOString() : null,
+      last_vacuum_epoch: lastVacuumEpoch,
+      autovacuum_count: parseInt(String(t.autovacuum_count || 0), 10),
+      vacuum_count: parseInt(String(t.vacuum_count || 0), 10),
+      autovacuum_disabled: autovacuumDisabled,
+      table_size_bytes: tableSizeBytes,
+      table_size_pretty: formatBytes(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
+    };
+  });
+}
+function buildDeadTuplesConclusions(tables) {
+  const conclusions = [];
+  const recommendations = [];
+  const fmt = (n) => n.toLocaleString("en-US");
+  for (const t of tables) {
+    const rel = `"${t.schema_name}"."${t.table_name}"`;
+    const lastAv = t.last_autovacuum ? `last autovacuum: ${t.last_autovacuum}` : "autovacuum has never vacuumed it";
+    if (t.exceeds_dead_tuple_thresholds && t.autovacuum_disabled) {
+      conclusions.push(`Table ${rel} has ${fmt(t.n_dead_tup)} dead tuples (${t.dead_pct}% of all tuples) ` + `and autovacuum is disabled on it via reloptions (${lastAv}).`);
+      recommendations.push(`Re-enable autovacuum on ${rel}: alter table ${rel} reset (autovacuum_enabled); ` + `then run: vacuum (analyze) ${rel}; to clean up the accumulated dead tuples.`);
+    } else if (t.exceeds_dead_tuple_thresholds) {
+      conclusions.push(`Table ${rel} has ${fmt(t.n_dead_tup)} dead tuples (${t.dead_pct}% of all tuples; ${lastAv}).`);
+      recommendations.push(`Run: vacuum (analyze) ${rel}; and review autovacuum settings ` + `(autovacuum_vacuum_scale_factor, autovacuum_vacuum_cost_delay, autovacuum_max_workers) ` + `if dead tuples keep accumulating on ${rel}.`);
+    } else if (t.autovacuum_disabled_flagged) {
+      conclusions.push(`Autovacuum is disabled via reloptions on table ${rel} ` + `(~${fmt(t.n_live_tup + t.n_dead_tup)} tuples); dead tuples and transaction ID age ` + `will accumulate unchecked.`);
+      recommendations.push(`Re-enable autovacuum on ${rel}: alter table ${rel} reset (autovacuum_enabled); ` + `unless this table is managed by a carefully scheduled manual vacuum job.`);
+    }
+  }
+  return { conclusions, recommendations };
+}
 function createBaseReport(checkId, checkTitle, nodeName) {
   const buildTs = resolveBuildTs();
   return {
@@ -29778,6 +29897,40 @@ async function generateF001(client, nodeName) {
   };
   return report;
 }
+async function generateF003(client, nodeName) {
+  const report = createBaseReport("F003", "Autovacuum: dead tuples", nodeName);
+  const postgresVersion = await getPostgresVersion(client);
+  const pgMajorVersion = parseInt(postgresVersion.server_major_ver, 10) || 16;
+  const tables = await getDeadTuples(client, pgMajorVersion);
+  const { datname: dbName, size_bytes: dbSizeBytes } = await getCurrentDatabaseInfo(client, pgMajorVersion);
+  const flaggedCount = tables.filter((t) => t.exceeds_dead_tuple_thresholds).length;
+  const autovacuumDisabledCount = tables.filter((t) => t.autovacuum_disabled).length;
+  const autovacuumDisabledFlaggedCount = tables.filter((t) => t.autovacuum_disabled_flagged).length;
+  const totalDeadTuples = tables.reduce((sum, t) => sum + t.n_dead_tup, 0);
+  const { conclusions, recommendations } = buildDeadTuplesConclusions(tables);
+  const dbEntry = {
+    dead_tuples_tables: tables,
+    total_count: tables.length,
+    flagged_count: flaggedCount,
+    autovacuum_disabled_count: autovacuumDisabledCount,
+    autovacuum_disabled_flagged_count: autovacuumDisabledFlaggedCount,
+    total_dead_tuples: totalDeadTuples,
+    thresholds: {
+      dead_tuples_min: F003_DEAD_TUPLES_MIN,
+      dead_pct_min: F003_DEAD_PCT_MIN,
+      autovacuum_disabled_min_rows: F003_AUTOVACUUM_DISABLED_MIN_ROWS
+    },
+    conclusions,
+    recommendations,
+    database_size_bytes: dbSizeBytes,
+    database_size_pretty: formatBytes(dbSizeBytes)
+  };
+  report.results[nodeName] = {
+    data: { [dbName]: dbEntry },
+    postgres_version: postgresVersion
+  };
+  return report;
+}
 async function generateF004(client, nodeName) {
   const report = createBaseReport("F004", "Autovacuum: heap bloat (estimated)", nodeName);
   const postgresVersion = await getPostgresVersion(client);
@@ -30211,6 +30364,7 @@ var REPORT_GENERATORS = {
   D001: generateD001,
   D004: generateD004,
   F001: generateF001,
+  F003: generateF003,
   F004: generateF004,
   F005: generateF005,
   G001: generateG001,
@@ -30452,6 +30606,45 @@ async function postRpc(params) {
     req.end();
   });
 }
+var VERIFY_API_KEY_TIMEOUT_MS = 1e4;
+async function verifyApiKey(params) {
+  const { apiKey, apiBaseUrl, timeoutMs = VERIFY_API_KEY_TIMEOUT_MS } = params;
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL3(`${base}/checkup_reports`);
+  url.searchParams.set("limit", "1");
+  if (url.protocol === "http:") {
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    const isLoopback = ["localhost", "127.0.0.1", "::1"].includes(hostname);
+    if (!isLoopback && process.env.CHECKUP_ALLOW_HTTP !== "1") {
+      return {
+        status: "unknown",
+        detail: `refusing to send API key over plaintext HTTP to '${url.host}'`
+      };
+    }
+  }
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url.toString(), {
+      method: "GET",
+      headers: { "access-token": apiKey },
+      signal: controller.signal
+    });
+    await response.text().catch(() => "");
+    if (response.status === 401 || response.status === 403) {
+      return { status: "invalid", statusCode: response.status };
+    }
+    if (response.ok) {
+      return { status: "valid" };
+    }
+    return { status: "unknown", detail: `HTTP ${response.status}` };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { status: "unknown", detail: message };
+  } finally {
+    clearTimeout(timer);
+  }
+}
 async function createCheckupReport(params) {
   const { apiKey, apiBaseUrl, project, status } = params;
   const bodyObj = {
@@ -30544,6 +30737,8 @@ function generateCheckSummary(checkId, report) {
       return summarizeD004(nodeData);
     case "F001":
       return summarizeF001(nodeData);
+    case "F003":
+      return summarizeF003(nodeData);
     case "G001":
       return summarizeG001(nodeData);
     case "G003":
@@ -30708,6 +30903,27 @@ function summarizeF001(nodeData) {
     message: `${settingsCount} autovacuum setting${settingsCount > 1 ? "s" : ""} collected`
   };
 }
+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 summarizeG001(nodeData) {
   const data = nodeData?.data || {};
   const settingsCount = Object.keys(data).length;
@@ -33720,6 +33936,9 @@ function prepareUploadConfig(opts, rootOpts, shouldUpload, uploadExplicitlyReque
       console.error("Tip: run 'postgresai auth' or pass --api-key / set PGAI_API_KEY");
       return null;
     }
+    console.error("Notice: no API key configured \u2014 results will NOT be uploaded to PostgresAI.");
+    console.error("        To upload: run 'postgresai auth login' or pass --api-key / set PGAI_API_KEY.");
+    console.error("        To run locally without this notice, pass --no-upload.");
     return;
   }
   const cfg = readConfig();
@@ -35010,6 +35229,22 @@ Usage: postgresai checkup ${checkId} postgresql://user@host:5432/dbname
   const uploadCfg = uploadResult?.config;
   const projectWasGenerated = uploadResult?.projectWasGenerated ?? false;
   shouldUpload = !!uploadCfg;
+  if (uploadCfg) {
+    const verification = await verifyApiKey({
+      apiKey: uploadCfg.apiKey,
+      apiBaseUrl: uploadCfg.apiBaseUrl
+    });
+    if (verification.status === "invalid") {
+      console.error(`Error: the configured API key was rejected by the PostgresAI API (HTTP ${verification.statusCode})`);
+      console.error("Tip: run 'postgresai auth login' to re-authenticate, or pass a valid --api-key / set PGAI_API_KEY");
+      console.error("Tip: pass --no-upload to run checks locally without uploading");
+      process.exitCode = 1;
+      return;
+    }
+    if (verification.status === "unknown") {
+      console.error(`Warning: could not verify API key before running checks (${verification.detail}); continuing \u2014 upload will still be attempted`);
+    }
+  }
   const adminConn = resolveAdminConnection({
     conn,
     envPassword: process.env.PGPASSWORD
@@ -35233,42 +35468,79 @@ function checkRunningContainers() {
     return { running: false, containers: [] };
   }
 }
-function registerMonitoringInstance(apiKey, projectName, opts) {
+async function registerMonitoringInstance(apiKey, projectName, opts) {
   const { apiBaseUrl } = resolveBaseUrls2(opts);
   const url = `${apiBaseUrl}/rpc/monitoring_instance_register`;
   const debug = opts?.debug;
+  const instanceId = opts?.instanceId;
+  const retries = opts?.retries ?? (instanceId ? 1 : 0);
+  const retryDelayMs = opts?.retryDelayMs ?? 400;
   if (debug) {
     console.error(`
 Debug: Registering monitoring instance...`);
     console.error(`Debug: POST ${url}`);
-    console.error(`Debug: project_name=${projectName}`);
+    console.error(`Debug: project_name=${projectName}${instanceId ? ` instance_id=${instanceId}` : ""}`);
   }
-  fetch(url, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json"
-    },
-    body: JSON.stringify({
-      api_token: apiKey,
-      project_name: projectName
-    })
-  }).then(async (res) => {
-    const body = await res.text().catch(() => "");
-    if (!res.ok) {
+  const requestBody = {
+    api_token: apiKey,
+    project_name: projectName
+  };
+  if (instanceId) {
+    requestBody.instance_id = instanceId;
+  }
+  for (let attempt = 0;attempt <= retries; attempt++) {
+    if (attempt > 0 && retryDelayMs > 0) {
+      await new Promise((resolve8) => setTimeout(resolve8, retryDelayMs));
+    }
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(requestBody)
+      });
+      const body = await res.text().catch(() => "");
+      if (!res.ok) {
+        if (debug) {
+          console.error(`Debug: Monitoring registration failed: HTTP ${res.status}`);
+          console.error(`Debug: Response: ${body}`);
+        }
+        continue;
+      }
       if (debug) {
-        console.error(`Debug: Monitoring registration failed: HTTP ${res.status}`);
-        console.error(`Debug: Response: ${body}`);
+        console.error(`Debug: Monitoring registration response: ${body}`);
+      }
+      try {
+        const parsed = JSON.parse(body);
+        return {
+          instanceId: typeof parsed.instance_id === "string" ? parsed.instance_id : undefined,
+          projectId: typeof parsed.project_id === "number" ? parsed.project_id : undefined,
+          projectName: typeof parsed.project_name === "string" ? parsed.project_name : undefined,
+          created: typeof parsed.created === "boolean" ? parsed.created : undefined
+        };
+      } catch {
+        return {};
+      }
+    } catch (err) {
+      if (debug) {
+        console.error(`Debug: Monitoring registration error: ${err.message}`);
       }
-      return;
-    }
-    if (debug) {
-      console.error(`Debug: Monitoring registration response: ${body}`);
-    }
-  }).catch((err) => {
-    if (debug) {
-      console.error(`Debug: Monitoring registration error: ${err.message}`);
     }
-  });
+  }
+  return null;
+}
+var PROJECT_NAME_RE = /^[A-Za-z0-9._-]+$/;
+function resolveAdoptedProject(reg) {
+  if (!reg)
+    return null;
+  if (typeof reg.projectId === "number" && Number.isFinite(reg.projectId)) {
+    return String(reg.projectId);
+  }
+  if (typeof reg.projectName === "string" && PROJECT_NAME_RE.test(reg.projectName)) {
+    return reg.projectName;
+  }
+  return null;
 }
 function updatePgwatchConfig(configPath, updates) {
   let lines = [];
@@ -35389,7 +35661,7 @@ mon.command("local-install").description("install local monitoring stack (genera
   "      PGAI_ENABLE_IPV6=false   (accepted: true|false|yes|no, lowercase)",
   ""
 ].join(`
-`)).option("--demo", "demo mode with sample database", false).option("--api-key <key>", "Postgres AI API key for automated report uploads").option("--db-url <url>", "PostgreSQL connection URL to monitor").option("--tag <tag>", "Docker image tag to use (e.g., 0.14.0, 0.14.0-dev.33)").option("--project <name>", "Docker Compose project name (default: postgres_ai)").option("-y, --yes", "accept all defaults and skip interactive prompts", false).action(async (opts) => {
+`)).option("--demo", "demo mode with sample database", false).option("--api-key <key>", "Postgres AI API key for automated report uploads").option("--db-url <url>", "PostgreSQL connection URL to monitor").option("--tag <tag>", "Docker image tag to use (e.g., 0.14.0, 0.14.0-dev.33)").option("--project <name>", "Docker Compose project name (default: postgres_ai)").option("--instance-id <uuid>", "adopt a console-provisioned monitoring instance instead of self-registering a new one (set automatically by the provisioning flow; PGAI_INSTANCE_ID env also works)").option("-y, --yes", "accept all defaults and skip interactive prompts", false).action(async (opts) => {
   const globalOpts = program2.opts();
   let apiKey = opts.apiKey || globalOpts.apiKey;
   console.log(`
@@ -35756,10 +36028,32 @@ Searched: ${demoCandidates.join(", ")}
 `);
   if (apiKey && !opts.demo) {
     const projectName = opts.project || "postgres-ai-monitoring";
-    registerMonitoringInstance(apiKey, projectName, {
-      apiBaseUrl: globalOpts.apiBaseUrl,
-      debug: !!process.env.DEBUG
-    });
+    const instanceId = opts.instanceId || process.env.PGAI_INSTANCE_ID;
+    if (instanceId) {
+      const reg = await registerMonitoringInstance(apiKey, projectName, {
+        apiBaseUrl: globalOpts.apiBaseUrl,
+        debug: !!process.env.DEBUG,
+        instanceId
+      });
+      const adoptedProject = resolveAdoptedProject(reg);
+      if (adoptedProject != null) {
+        updatePgwatchConfig(path7.resolve(projectDir, ".pgwatch-config"), {
+          project_name: adoptedProject
+        });
+        const verb = reg?.created ? "Registered" : "Adopted";
+        console.log(`\u2713 ${verb} monitoring instance (project: ${adoptedProject})
+`);
+      } else if (reg) {
+        console.error(`\u26A0 Adopted provisioned instance ${instanceId} but the platform returned no project \u2014 reports will use project '${projectName}'`);
+      } else {
+        console.error(`\u26A0 Could not adopt provisioned instance ${instanceId} \u2014 reports will use project '${projectName}' until 'postgresai mon local-install' is re-run`);
+      }
+    } else {
+      registerMonitoringInstance(apiKey, projectName, {
+        apiBaseUrl: globalOpts.apiBaseUrl,
+        debug: !!process.env.DEBUG
+      });
+    }
   }
   console.log("=================================");
   console.log("  Local install completed!");
@@ -37515,6 +37809,8 @@ if (__require.main == __require.module) {
   });
 }
 export {
+  resolveAdoptedProject,
+  registerMonitoringInstance,
   refreshBundledComposeIfStale,
   readDeployedTag,
   isValidComposeYaml