postgresai 0.14.0-dev.67 → 0.14.0-dev.69

package/bin/postgres-ai.ts

@@ -1204,25 +1204,25 @@ mon
     // Update .env with custom tag if provided
     const envFile = path.resolve(projectDir, ".env");
 
-    // Build .env content, preserving important existing values
-    // Read existing .env first to preserve CI/custom settings
-    let existingTag: string | null = null;
+    // Build .env content, preserving important existing values (registry, password)
+    // Note: PGAI_TAG is intentionally NOT preserved - the CLI version should always match Docker images
     let existingRegistry: string | null = null;
     let existingPassword: string | null = null;
 
     if (fs.existsSync(envFile)) {
       const existingEnv = fs.readFileSync(envFile, "utf8");
-      // Extract existing values
-      const tagMatch = existingEnv.match(/^PGAI_TAG=(.+)$/m);
-      if (tagMatch) existingTag = tagMatch[1].trim();
+      // Extract existing values (except tag - always use CLI version)
       const registryMatch = existingEnv.match(/^PGAI_REGISTRY=(.+)$/m);
       if (registryMatch) existingRegistry = registryMatch[1].trim();
       const pwdMatch = existingEnv.match(/^GF_SECURITY_ADMIN_PASSWORD=(.+)$/m);
       if (pwdMatch) existingPassword = pwdMatch[1].trim();
     }
 
-    // Priority: CLI --tag flag > PGAI_TAG env var > existing .env > package version
-    const imageTag = opts.tag || process.env.PGAI_TAG || existingTag || pkg.version;
+    // Priority: CLI --tag flag > package version
+    // Note: We intentionally do NOT use process.env.PGAI_TAG here because Bun auto-loads .env files,
+    // which would cause stale .env values to override the CLI version. The CLI version should always
+    // match the Docker images. Users can override with --tag if needed.
+    const imageTag = opts.tag || pkg.version;
 
     const envLines: string[] = [`PGAI_TAG=${imageTag}`];
     if (existingRegistry) {
@@ -1550,6 +1550,16 @@ const MONITORING_CONTAINERS = [
   "postgres-reports",
 ];
 
+/**
+ * Network cleanup constants.
+ * Docker Compose creates a default network named "{project}_default".
+ * In CI environments, network cleanup can fail if containers are slow to disconnect.
+ */
+const COMPOSE_PROJECT_NAME = "postgres_ai";
+const DOCKER_NETWORK_NAME = `${COMPOSE_PROJECT_NAME}_default`;
+/** Delay before retrying network cleanup (allows container network disconnections to complete) */
+const NETWORK_CLEANUP_DELAY_MS = 2000;
+
 /** Remove orphaned containers that docker compose down might miss */
 async function removeOrphanedContainers(): Promise<void> {
   for (const container of MONITORING_CONTAINERS) {
@@ -1565,7 +1575,33 @@ mon
   .command("stop")
   .description("stop monitoring services")
   .action(async () => {
-    const code = await runCompose(["down"]);
+    // Multi-stage cleanup strategy for reliable shutdown in CI environments:
+    // Stage 1: Standard compose down with orphan removal
+    // Stage 2: Force remove any orphaned containers, then retry compose down
+    // Stage 3: Force remove the Docker network directly
+    // This handles edge cases where containers are slow to disconnect from networks.
+    let code = await runCompose(["down", "--remove-orphans"]);
+
+    // Stage 2: If initial cleanup fails, try removing orphaned containers first
+    if (code !== 0) {
+      await removeOrphanedContainers();
+      // Wait a moment for container network disconnections to complete
+      await new Promise(resolve => setTimeout(resolve, NETWORK_CLEANUP_DELAY_MS));
+      // Retry compose down
+      code = await runCompose(["down", "--remove-orphans"]);
+    }
+
+    // Final cleanup: force remove the network if it still exists
+    if (code !== 0) {
+      try {
+        await execFilePromise("docker", ["network", "rm", DOCKER_NETWORK_NAME]);
+        // Network removal succeeded - cleanup is complete
+        code = 0;
+      } catch {
+        // Network doesn't exist or couldn't be removed, ignore
+      }
+    }
+
     if (code !== 0) process.exitCode = code;
   });
 

package/dist/bin/postgres-ai.js

@@ -13064,7 +13064,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.14.0-dev.67",
+  version: "0.14.0-dev.69",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -15887,7 +15887,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.14.0-dev.67";
+var version = "0.14.0-dev.69";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -24958,17 +24958,17 @@ where
     statement_timeout_seconds: 300
   },
   pg_invalid_indexes: {
-    description: "This metric identifies invalid indexes in the database. It provides insights into the number of invalid indexes and their details. This metric helps administrators identify and fix invalid indexes to improve database performance.",
+    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).",
     sqls: {
       11: `with fk_indexes as ( /* pgwatch_generated */
   select
-    schemaname as tag_schema_name,
-    (indexrelid::regclass)::text as tag_index_name,
-    (relid::regclass)::text as tag_table_name,
-    (confrelid::regclass)::text as tag_fk_table_ref,
-    array_to_string(indclass, ', ') as tag_opclasses
-  from
-    pg_stat_all_indexes
+    schemaname as schema_name,
+    indexrelid,
+    (indexrelid::regclass)::text as index_name,
+    (relid::regclass)::text as table_name,
+    (confrelid::regclass)::text as fk_table_ref,
+    array_to_string(indclass, ', ') as opclasses
+  from pg_stat_all_indexes
   join pg_index using (indexrelid)
   left join pg_constraint
     on array_to_string(indkey, ',') = array_to_string(conkey, ',')
@@ -24977,37 +24977,58 @@ where
       and contype = 'f'
   where idx_scan = 0
     and indisunique is false
-    and conkey is not null --conkey is not null then true else false end as is_fk_idx
-), data as (
+    and conkey is not null
+),
+-- Find valid indexes that could be duplicates (same table, same columns)
+valid_duplicates as (
+  select
+    inv.indexrelid as invalid_indexrelid,
+    val.indexrelid as valid_indexrelid,
+    (val.indexrelid::regclass)::text as valid_index_name,
+    pg_get_indexdef(val.indexrelid) as valid_index_definition
+  from pg_index inv
+  join pg_index val on inv.indrelid = val.indrelid  -- same table
+    and inv.indkey = val.indkey  -- same columns (in same order)
+    and inv.indexrelid != val.indexrelid  -- different index
+    and val.indisvalid = true  -- valid index
+  where inv.indisvalid = false
+),
+data as (
   select
     pci.relname as tag_index_name,
     pn.nspname as tag_schema_name,
     pct.relname as tag_table_name,
-    quote_ident(pn.nspname) as tag_schema_name,
-    quote_ident(pci.relname) as tag_index_name,
-    quote_ident(pct.relname) as tag_table_name,
     coalesce(nullif(quote_ident(pn.nspname), 'public') || '.', '') || quote_ident(pct.relname) as tag_relation_name,
     pg_get_indexdef(pidx.indexrelid) as index_definition,
-    pg_relation_size(pidx.indexrelid) index_size_bytes,
+    pg_relation_size(pidx.indexrelid) as index_size_bytes,
+    -- Constraint info
+    pidx.indisprimary as is_pk,
+    pidx.indisunique as is_unique,
+    con.conname as constraint_name,
+    -- Table row estimate
+    pct.reltuples::bigint as table_row_estimate,
+    -- Valid duplicate check
+    (vd.valid_indexrelid is not null) as has_valid_duplicate,
+    vd.valid_index_name,
+    vd.valid_index_definition,
+    -- FK support check
     ((
       select count(1)
       from fk_indexes fi
-      where
-        fi.tag_fk_table_ref = pct.relname
-        and fi.tag_opclasses like (array_to_string(pidx.indclass, ', ') || '%')
+      where fi.fk_table_ref = pct.relname
+        and fi.opclasses like (array_to_string(pidx.indclass, ', ') || '%')
     ) > 0)::int as supports_fk
   from pg_index pidx
-  join pg_class as pci on pci.oid = pidx.indexrelid
-  join pg_class as pct on pct.oid = pidx.indrelid
+  join pg_class pci on pci.oid = pidx.indexrelid
+  join pg_class pct on pct.oid = pidx.indrelid
   left join pg_namespace pn on pn.oid = pct.relnamespace
+  left join pg_constraint con on con.conindid = pidx.indexrelid
+  left join valid_duplicates vd on vd.invalid_indexrelid = pidx.indexrelid
   where pidx.indisvalid = false
-), data_total as (
-    select
-      sum(index_size_bytes) as index_size_bytes_sum
-    from data
-), num_data as (
+),
+num_data as (
   select
-    row_number() over () num,
+    row_number() over () as num,
     data.*
   from data
 )
@@ -25626,7 +25647,14 @@ async function getInvalidIndexes(client, pgMajorVersion = 16) {
       index_size_bytes: indexSizeBytes,
       index_size_pretty: formatBytes(indexSizeBytes),
       index_definition: String(transformed.index_definition || ""),
-      supports_fk: toBool(transformed.supports_fk)
+      supports_fk: toBool(transformed.supports_fk),
+      is_pk: toBool(transformed.is_pk),
+      is_unique: toBool(transformed.is_unique),
+      constraint_name: transformed.constraint_name ? String(transformed.constraint_name) : null,
+      table_row_estimate: parseInt(String(transformed.table_row_estimate || 0), 10),
+      has_valid_duplicate: toBool(transformed.has_valid_duplicate),
+      valid_duplicate_name: transformed.valid_index_name ? String(transformed.valid_index_name) : null,
+      valid_duplicate_definition: transformed.valid_index_definition ? String(transformed.valid_index_definition) : null
     };
   });
 }
@@ -27213,14 +27241,10 @@ mon.command("local-install").description("install local monitoring stack (genera
   console.log(`Project directory: ${projectDir}
 `);
   const envFile = path5.resolve(projectDir, ".env");
-  let existingTag = null;
   let existingRegistry = null;
   let existingPassword = null;
   if (fs5.existsSync(envFile)) {
     const existingEnv = fs5.readFileSync(envFile, "utf8");
-    const tagMatch = existingEnv.match(/^PGAI_TAG=(.+)$/m);
-    if (tagMatch)
-      existingTag = tagMatch[1].trim();
     const registryMatch = existingEnv.match(/^PGAI_REGISTRY=(.+)$/m);
     if (registryMatch)
       existingRegistry = registryMatch[1].trim();
@@ -27228,7 +27252,7 @@ mon.command("local-install").description("install local monitoring stack (genera
     if (pwdMatch)
       existingPassword = pwdMatch[1].trim();
   }
-  const imageTag = opts.tag || process.env.PGAI_TAG || existingTag || package_default.version;
+  const imageTag = opts.tag || package_default.version;
   const envLines = [`PGAI_TAG=${imageTag}`];
   if (existingRegistry) {
     envLines.push(`PGAI_REGISTRY=${existingRegistry}`);
@@ -27565,6 +27589,9 @@ var MONITORING_CONTAINERS = [
   "sources-generator",
   "postgres-reports"
 ];
+var COMPOSE_PROJECT_NAME = "postgres_ai";
+var DOCKER_NETWORK_NAME = `${COMPOSE_PROJECT_NAME}_default`;
+var NETWORK_CLEANUP_DELAY_MS = 2000;
 async function removeOrphanedContainers() {
   for (const container of MONITORING_CONTAINERS) {
     try {
@@ -27573,7 +27600,18 @@ async function removeOrphanedContainers() {
   }
 }
 mon.command("stop").description("stop monitoring services").action(async () => {
-  const code = await runCompose(["down"]);
+  let code = await runCompose(["down", "--remove-orphans"]);
+  if (code !== 0) {
+    await removeOrphanedContainers();
+    await new Promise((resolve6) => setTimeout(resolve6, NETWORK_CLEANUP_DELAY_MS));
+    code = await runCompose(["down", "--remove-orphans"]);
+  }
+  if (code !== 0) {
+    try {
+      await execFilePromise("docker", ["network", "rm", DOCKER_NETWORK_NAME]);
+      code = 0;
+    } catch {}
+  }
   if (code !== 0)
     process.exitCode = code;
 });

package/lib/checkup.ts

@@ -109,6 +109,12 @@ export interface ClusterMetric {
 
 /**
  * Invalid index entry (H001) - matches H001.schema.json invalidIndex
+ *
+ * Decision tree for remediation recommendations:
+ * 1. has_valid_duplicate=true → DROP (valid duplicate exists, safe to remove)
+ * 2. is_pk=true or is_unique=true → RECREATE (backs a constraint, must restore)
+ * 3. table_row_estimate < 10000 → RECREATE (small table, quick rebuild)
+ * 4. Otherwise → UNCERTAIN (needs manual analysis of query plans)
  */
 export interface InvalidIndex {
   schema_name: string;
@@ -117,9 +123,61 @@ export interface InvalidIndex {
   relation_name: string;
   index_size_bytes: number;
   index_size_pretty: string;
-  /** Full CREATE INDEX statement from pg_get_indexdef(), useful for DROP/CREATE migrations */
+  /** Full CREATE INDEX statement from pg_get_indexdef() - useful for DROP/RECREATE migrations */
   index_definition: string;
   supports_fk: boolean;
+  /** True if this index backs a PRIMARY KEY constraint */
+  is_pk: boolean;
+  /** True if this is a UNIQUE index (includes PK indexes) */
+  is_unique: boolean;
+  /** Name of the constraint this index backs, or null if none */
+  constraint_name: string | null;
+  /** Estimated row count of the table from pg_class.reltuples */
+  table_row_estimate: number;
+  /** True if there is a valid index on the same column(s) */
+  has_valid_duplicate: boolean;
+  /** Name of the valid duplicate index if one exists */
+  valid_duplicate_name: string | null;
+  /** Full CREATE INDEX statement of the valid duplicate index */
+  valid_duplicate_definition: string | null;
+}
+
+/** Recommendation for handling an invalid index */
+export type InvalidIndexRecommendation = "DROP" | "RECREATE" | "UNCERTAIN";
+
+/** Threshold for considering a table "small" (quick to rebuild) */
+const SMALL_TABLE_ROW_THRESHOLD = 10000;
+
+/**
+ * Compute remediation recommendation for an invalid index using decision tree.
+ *
+ * Decision tree logic:
+ * 1. If has_valid_duplicate is true → DROP (valid duplicate exists, safe to remove)
+ * 2. If is_pk or is_unique is true → RECREATE (backs a constraint, must restore)
+ * 3. If table_row_estimate < 10000 → RECREATE (small table, quick rebuild)
+ * 4. Otherwise → UNCERTAIN (needs manual analysis of query plans)
+ *
+ * @param index - Invalid index with observation data
+ * @returns Recommendation: "DROP", "RECREATE", or "UNCERTAIN"
+ */
+export function getInvalidIndexRecommendation(index: InvalidIndex): InvalidIndexRecommendation {
+  // 1. Valid duplicate exists - safe to drop
+  if (index.has_valid_duplicate) {
+    return "DROP";
+  }
+
+  // 2. Backs a constraint - must recreate
+  if (index.is_pk || index.is_unique) {
+    return "RECREATE";
+  }
+
+  // 3. Small table - quick to recreate
+  if (index.table_row_estimate < SMALL_TABLE_ROW_THRESHOLD) {
+    return "RECREATE";
+  }
+
+  // 4. Large table without clear path - needs manual analysis
+  return "UNCERTAIN";
 }
 
 /**
@@ -564,11 +622,11 @@ export async function getClusterInfo(client: Client, pgMajorVersion: number = 16
 
 /**
  * Get invalid indexes from the database (H001).
- * Invalid indexes are indexes that failed to build (e.g., due to CONCURRENTLY failure).
+ * Invalid indexes have indisvalid = false, typically from failed CREATE INDEX CONCURRENTLY.
  *
  * @param client - Connected PostgreSQL client
  * @param pgMajorVersion - PostgreSQL major version (default: 16)
- * @returns Array of invalid index entries with size and FK support info
+ * @returns Array of invalid index entries with observation data for decision tree analysis
  */
 export async function getInvalidIndexes(client: Client, pgMajorVersion: number = 16): Promise<InvalidIndex[]> {
   const sql = getMetricSql(METRIC_NAMES.H001, pgMajorVersion);
@@ -576,6 +634,7 @@ export async function getInvalidIndexes(client: Client, pgMajorVersion: number =
   return result.rows.map((row) => {
     const transformed = transformMetricRow(row);
     const indexSizeBytes = parseInt(String(transformed.index_size_bytes || 0), 10);
+
     return {
       schema_name: String(transformed.schema_name || ""),
       table_name: String(transformed.table_name || ""),
@@ -585,6 +644,13 @@ export async function getInvalidIndexes(client: Client, pgMajorVersion: number =
       index_size_pretty: formatBytes(indexSizeBytes),
       index_definition: String(transformed.index_definition || ""),
       supports_fk: toBool(transformed.supports_fk),
+      is_pk: toBool(transformed.is_pk),
+      is_unique: toBool(transformed.is_unique),
+      constraint_name: transformed.constraint_name ? String(transformed.constraint_name) : null,
+      table_row_estimate: parseInt(String(transformed.table_row_estimate || 0), 10),
+      has_valid_duplicate: toBool(transformed.has_valid_duplicate),
+      valid_duplicate_name: transformed.valid_index_name ? String(transformed.valid_index_name) : null,
+      valid_duplicate_definition: transformed.valid_index_definition ? String(transformed.valid_index_definition) : null,
     };
   });
 }

package/lib/metrics-embedded.ts

@@ -1,6 +1,6 @@
 // AUTO-GENERATED FILE - DO NOT EDIT
 // Generated from config/pgwatch-prometheus/metrics.yml by scripts/embed-metrics.ts
-// Generated at: 2025-12-30T04:11:39.278Z
+// Generated at: 2026-01-06T14:31:10.733Z
 
 /**
  * Metric definition from metrics.yml
@@ -45,9 +45,9 @@ export const METRICS: Record<string, MetricDefinition> = {
     statement_timeout_seconds: 300,
   },
   "pg_invalid_indexes": {
-    description: "This metric identifies invalid indexes in the database. It provides insights into the number of invalid indexes and their details. This metric helps administrators identify and fix invalid indexes to improve database performance.",
+    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).",
     sqls: {
-      11: "with fk_indexes as ( /* pgwatch_generated */\n  select\n    schemaname as tag_schema_name,\n    (indexrelid::regclass)::text as tag_index_name,\n    (relid::regclass)::text as tag_table_name,\n    (confrelid::regclass)::text as tag_fk_table_ref,\n    array_to_string(indclass, ', ') as tag_opclasses\n  from\n    pg_stat_all_indexes\n  join pg_index using (indexrelid)\n  left join pg_constraint\n    on array_to_string(indkey, ',') = array_to_string(conkey, ',')\n      and schemaname = (connamespace::regnamespace)::text\n      and conrelid = relid\n      and contype = 'f'\n  where idx_scan = 0\n    and indisunique is false\n    and conkey is not null --conkey is not null then true else false end as is_fk_idx\n), data as (\n  select\n    pci.relname as tag_index_name,\n    pn.nspname as tag_schema_name,\n    pct.relname as tag_table_name,\n    quote_ident(pn.nspname) as tag_schema_name,\n    quote_ident(pci.relname) as tag_index_name,\n    quote_ident(pct.relname) as tag_table_name,\n    coalesce(nullif(quote_ident(pn.nspname), 'public') || '.', '') || quote_ident(pct.relname) as tag_relation_name,\n    pg_get_indexdef(pidx.indexrelid) as index_definition,\n    pg_relation_size(pidx.indexrelid) index_size_bytes,\n    ((\n      select count(1)\n      from fk_indexes fi\n      where\n        fi.tag_fk_table_ref = pct.relname\n        and fi.tag_opclasses like (array_to_string(pidx.indclass, ', ') || '%')\n    ) > 0)::int as supports_fk\n  from pg_index pidx\n  join pg_class as pci on pci.oid = pidx.indexrelid\n  join pg_class as pct on pct.oid = pidx.indrelid\n  left join pg_namespace pn on pn.oid = pct.relnamespace\n  where pidx.indisvalid = false\n), data_total as (\n    select\n      sum(index_size_bytes) as index_size_bytes_sum\n    from data\n), num_data as (\n  select\n    row_number() over () num,\n    data.*\n  from data\n)\nselect\n  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,\n  current_database() as tag_datname,\n  num_data.*\nfrom num_data\nlimit 1000;\n",
+      11: "with fk_indexes as ( /* pgwatch_generated */\n  select\n    schemaname as schema_name,\n    indexrelid,\n    (indexrelid::regclass)::text as index_name,\n    (relid::regclass)::text as table_name,\n    (confrelid::regclass)::text as fk_table_ref,\n    array_to_string(indclass, ', ') as opclasses\n  from pg_stat_all_indexes\n  join pg_index using (indexrelid)\n  left join pg_constraint\n    on array_to_string(indkey, ',') = array_to_string(conkey, ',')\n      and schemaname = (connamespace::regnamespace)::text\n      and conrelid = relid\n      and contype = 'f'\n  where idx_scan = 0\n    and indisunique is false\n    and conkey is not null\n),\n-- Find valid indexes that could be duplicates (same table, same columns)\nvalid_duplicates as (\n  select\n    inv.indexrelid as invalid_indexrelid,\n    val.indexrelid as valid_indexrelid,\n    (val.indexrelid::regclass)::text as valid_index_name,\n    pg_get_indexdef(val.indexrelid) as valid_index_definition\n  from pg_index inv\n  join pg_index val on inv.indrelid = val.indrelid  -- same table\n    and inv.indkey = val.indkey  -- same columns (in same order)\n    and inv.indexrelid != val.indexrelid  -- different index\n    and val.indisvalid = true  -- valid index\n  where inv.indisvalid = false\n),\ndata as (\n  select\n    pci.relname as tag_index_name,\n    pn.nspname as tag_schema_name,\n    pct.relname as tag_table_name,\n    coalesce(nullif(quote_ident(pn.nspname), 'public') || '.', '') || quote_ident(pct.relname) as tag_relation_name,\n    pg_get_indexdef(pidx.indexrelid) as index_definition,\n    pg_relation_size(pidx.indexrelid) as index_size_bytes,\n    -- Constraint info\n    pidx.indisprimary as is_pk,\n    pidx.indisunique as is_unique,\n    con.conname as constraint_name,\n    -- Table row estimate\n    pct.reltuples::bigint as table_row_estimate,\n    -- Valid duplicate check\n    (vd.valid_indexrelid is not null) as has_valid_duplicate,\n    vd.valid_index_name,\n    vd.valid_index_definition,\n    -- FK support check\n    ((\n      select count(1)\n      from fk_indexes fi\n      where fi.fk_table_ref = pct.relname\n        and fi.opclasses like (array_to_string(pidx.indclass, ', ') || '%')\n    ) > 0)::int as supports_fk\n  from pg_index pidx\n  join pg_class pci on pci.oid = pidx.indexrelid\n  join pg_class pct on pct.oid = pidx.indrelid\n  left join pg_namespace pn on pn.oid = pct.relnamespace\n  left join pg_constraint con on con.conindid = pidx.indexrelid\n  left join valid_duplicates vd on vd.invalid_indexrelid = pidx.indexrelid\n  where pidx.indisvalid = false\n),\nnum_data as (\n  select\n    row_number() over () as num,\n    data.*\n  from data\n)\nselect\n  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,\n  current_database() as tag_datname,\n  num_data.*\nfrom num_data\nlimit 1000;\n",
     },
     gauges: ["*"],
     statement_timeout_seconds: 15,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.14.0-dev.67",
+  "version": "0.14.0-dev.69",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,

package/test/checkup.test.ts

@@ -287,27 +287,28 @@ describe("Report generators with mock client", () => {
           },
         ],
         databaseSizesRows: [{ datname: "postgres", size_bytes: "1073741824" }],
-        dbStatsRows: [{ 
-          numbackends: 5, 
-          xact_commit: 100, 
-          xact_rollback: 1, 
-          blks_read: 1000, 
-          blks_hit: 9000, 
-          tup_returned: 500, 
-          tup_fetched: 400, 
-          tup_inserted: 50, 
-          tup_updated: 30, 
-          tup_deleted: 10, 
-          deadlocks: 0, 
-          temp_files: 0, 
+        dbStatsRows: [{
+          numbackends: 5,
+          xact_commit: 100,
+          xact_rollback: 1,
+          blks_read: 1000,
+          blks_hit: 9000,
+          tup_returned: 500,
+          tup_fetched: 400,
+          tup_inserted: 50,
+          tup_updated: 30,
+          tup_deleted: 10,
+          deadlocks: 0,
+          temp_files: 0,
           temp_bytes: 0,
-          postmaster_uptime_s: 864000 
+          postmaster_uptime_s: 864000
         }],
         connectionStatesRows: [{ state: "active", count: 2 }, { state: "idle", count: 3 }],
         uptimeRows: [{ start_time: new Date("2024-01-01T00:00:00Z"), uptime: "10 days" }],
         invalidIndexesRows: [],
         unusedIndexesRows: [],
         redundantIndexesRows: [],
+        sensitiveColumnsRows: [],
       }
     );
 
@@ -320,6 +321,7 @@ describe("Report generators with mock client", () => {
     expect("H001" in reports).toBe(true);
     expect("H002" in reports).toBe(true);
     expect("H004" in reports).toBe(true);
+    // S001 is only available in Python reporter, not in CLI express mode
     expect(reports.A002.checkId).toBe("A002");
     expect(reports.A003.checkId).toBe("A003");
     expect(reports.A004.checkId).toBe("A004");
@@ -525,9 +527,233 @@ describe("H001 - Invalid indexes", () => {
     expect(dbData.database_size_pretty).toBeTruthy();
     expect(report.results["test-node"].postgres_version).toBeTruthy();
   });
+
+  test("getInvalidIndexes returns decision tree fields including valid_duplicate_definition", async () => {
+    const mockClient = createMockClient({
+      invalidIndexesRows: [
+        {
+          schema_name: "public",
+          table_name: "users",
+          index_name: "users_email_idx_invalid",
+          relation_name: "users",
+          index_size_bytes: "1048576",
+          index_definition: "CREATE INDEX users_email_idx_invalid ON public.users USING btree (email)",
+          supports_fk: false,
+          is_pk: false,
+          is_unique: false,
+          constraint_name: null,
+          table_row_estimate: "5000",
+          has_valid_duplicate: true,
+          valid_index_name: "users_email_idx",
+          valid_index_definition: "CREATE INDEX users_email_idx ON public.users USING btree (email)",
+        },
+      ],
+    });
+
+    const indexes = await checkup.getInvalidIndexes(mockClient as any);
+    expect(indexes.length).toBe(1);
+    expect(indexes[0].is_pk).toBe(false);
+    expect(indexes[0].is_unique).toBe(false);
+    expect(indexes[0].constraint_name).toBeNull();
+    expect(indexes[0].table_row_estimate).toBe(5000);
+    expect(indexes[0].has_valid_duplicate).toBe(true);
+    expect(indexes[0].valid_duplicate_name).toBe("users_email_idx");
+    expect(indexes[0].valid_duplicate_definition).toBe("CREATE INDEX users_email_idx ON public.users USING btree (email)");
+  });
+
+  test("getInvalidIndexes handles has_valid_duplicate: false with null values", async () => {
+    const mockClient = createMockClient({
+      invalidIndexesRows: [
+        {
+          schema_name: "public",
+          table_name: "orders",
+          index_name: "orders_status_idx_invalid",
+          relation_name: "orders",
+          index_size_bytes: "524288",
+          index_definition: "CREATE INDEX orders_status_idx_invalid ON public.orders USING btree (status)",
+          supports_fk: false,
+          is_pk: false,
+          is_unique: false,
+          constraint_name: null,
+          table_row_estimate: "100000",
+          has_valid_duplicate: false,
+          valid_index_name: null,
+          valid_index_definition: null,
+        },
+      ],
+    });
+
+    const indexes = await checkup.getInvalidIndexes(mockClient as Client);
+    expect(indexes.length).toBe(1);
+    expect(indexes[0].has_valid_duplicate).toBe(false);
+    expect(indexes[0].valid_duplicate_name).toBeNull();
+    expect(indexes[0].valid_duplicate_definition).toBeNull();
+  });
+
+  test("getInvalidIndexes handles is_pk: true with constraint", async () => {
+    const mockClient = createMockClient({
+      invalidIndexesRows: [
+        {
+          schema_name: "public",
+          table_name: "accounts",
+          index_name: "accounts_pkey_invalid",
+          relation_name: "accounts",
+          index_size_bytes: "262144",
+          index_definition: "CREATE UNIQUE INDEX accounts_pkey_invalid ON public.accounts USING btree (id)",
+          supports_fk: true,
+          is_pk: true,
+          is_unique: true,
+          constraint_name: "accounts_pkey",
+          table_row_estimate: "500",
+          has_valid_duplicate: false,
+          valid_index_name: null,
+          valid_index_definition: null,
+        },
+      ],
+    });
+
+    const indexes = await checkup.getInvalidIndexes(mockClient as Client);
+    expect(indexes.length).toBe(1);
+    expect(indexes[0].is_pk).toBe(true);
+    expect(indexes[0].is_unique).toBe(true);
+    expect(indexes[0].constraint_name).toBe("accounts_pkey");
+    expect(indexes[0].supports_fk).toBe(true);
+  });
+
+  test("getInvalidIndexes handles is_unique: true without PK", async () => {
+    const mockClient = createMockClient({
+      invalidIndexesRows: [
+        {
+          schema_name: "public",
+          table_name: "users",
+          index_name: "users_email_unique_invalid",
+          relation_name: "users",
+          index_size_bytes: "131072",
+          index_definition: "CREATE UNIQUE INDEX users_email_unique_invalid ON public.users USING btree (email)",
+          supports_fk: false,
+          is_pk: false,
+          is_unique: true,
+          constraint_name: "users_email_unique",
+          table_row_estimate: "25000",
+          has_valid_duplicate: true,
+          valid_index_name: "users_email_unique_idx",
+          valid_index_definition: "CREATE UNIQUE INDEX users_email_unique_idx ON public.users USING btree (email)",
+        },
+      ],
+    });
+
+    const indexes = await checkup.getInvalidIndexes(mockClient as Client);
+    expect(indexes.length).toBe(1);
+    expect(indexes[0].is_pk).toBe(false);
+    expect(indexes[0].is_unique).toBe(true);
+    expect(indexes[0].constraint_name).toBe("users_email_unique");
+    expect(indexes[0].has_valid_duplicate).toBe(true);
+  });
   // Top-level structure tests removed - covered by schema-validation.test.ts
 });
 
+// Tests for H001 decision tree recommendation logic
+describe("H001 - Decision tree recommendations", () => {
+  // Helper to create a minimal InvalidIndex for testing
+  const createTestIndex = (overrides: Partial<checkup.InvalidIndex> = {}): checkup.InvalidIndex => ({
+    schema_name: "public",
+    table_name: "test_table",
+    index_name: "test_idx",
+    relation_name: "public.test_table",
+    index_size_bytes: 1024,
+    index_size_pretty: "1 KiB",
+    index_definition: "CREATE INDEX test_idx ON public.test_table USING btree (col)",
+    supports_fk: false,
+    is_pk: false,
+    is_unique: false,
+    constraint_name: null,
+    table_row_estimate: 100000, // Large table by default
+    has_valid_duplicate: false,
+    valid_duplicate_name: null,
+    valid_duplicate_definition: null,
+    ...overrides,
+  });
+
+  test("returns DROP when has_valid_duplicate is true", () => {
+    const index = createTestIndex({ has_valid_duplicate: true, valid_duplicate_name: "existing_idx" });
+    expect(checkup.getInvalidIndexRecommendation(index)).toBe("DROP");
+  });
+
+  test("returns DROP even when is_pk is true if has_valid_duplicate is true", () => {
+    // has_valid_duplicate takes precedence over is_pk
+    const index = createTestIndex({
+      has_valid_duplicate: true,
+      is_pk: true,
+      is_unique: true,
+    });
+    expect(checkup.getInvalidIndexRecommendation(index)).toBe("DROP");
+  });
+
+  test("returns RECREATE when is_pk is true and no valid duplicate", () => {
+    const index = createTestIndex({
+      is_pk: true,
+      is_unique: true,
+      constraint_name: "test_pkey",
+    });
+    expect(checkup.getInvalidIndexRecommendation(index)).toBe("RECREATE");
+  });
+
+  test("returns RECREATE when is_unique is true (non-PK) and no valid duplicate", () => {
+    const index = createTestIndex({
+      is_unique: true,
+      constraint_name: "test_unique",
+    });
+    expect(checkup.getInvalidIndexRecommendation(index)).toBe("RECREATE");
+  });
+
+  test("returns RECREATE for small table (< 10K rows) without valid duplicate", () => {
+    const index = createTestIndex({ table_row_estimate: 5000 });
+    expect(checkup.getInvalidIndexRecommendation(index)).toBe("RECREATE");
+  });
+
+  test("returns RECREATE for table at threshold boundary (9999 rows)", () => {
+    const index = createTestIndex({ table_row_estimate: 9999 });
+    expect(checkup.getInvalidIndexRecommendation(index)).toBe("RECREATE");
+  });
+
+  test("returns UNCERTAIN for large table (>= 10K rows) at threshold boundary", () => {
+    const index = createTestIndex({ table_row_estimate: 10000 });
+    expect(checkup.getInvalidIndexRecommendation(index)).toBe("UNCERTAIN");
+  });
+
+  test("returns UNCERTAIN for large table without valid duplicate or constraint", () => {
+    const index = createTestIndex({ table_row_estimate: 1000000 });
+    expect(checkup.getInvalidIndexRecommendation(index)).toBe("UNCERTAIN");
+  });
+
+  test("returns UNCERTAIN for empty table (0 rows) with no valid duplicate - edge case", () => {
+    // Empty table should be RECREATE (< 10K threshold)
+    const index = createTestIndex({ table_row_estimate: 0 });
+    expect(checkup.getInvalidIndexRecommendation(index)).toBe("RECREATE");
+  });
+
+  test("decision tree priority: has_valid_duplicate > is_pk > small_table", () => {
+    // Even with PK and small table, has_valid_duplicate should win
+    const index = createTestIndex({
+      has_valid_duplicate: true,
+      is_pk: true,
+      is_unique: true,
+      table_row_estimate: 100,
+    });
+    expect(checkup.getInvalidIndexRecommendation(index)).toBe("DROP");
+  });
+
+  test("decision tree priority: is_pk > small_table", () => {
+    // is_pk should return RECREATE regardless of table size
+    const index = createTestIndex({
+      is_pk: true,
+      is_unique: true,
+      table_row_estimate: 1000000, // Large table
+    });
+    expect(checkup.getInvalidIndexRecommendation(index)).toBe("RECREATE");
+  });
+});
+
 // Tests for H002 (Unused indexes)
 describe("H002 - Unused indexes", () => {
   test("getUnusedIndexes returns unused indexes", async () => {

package/test/init.integration.test.ts

@@ -399,6 +399,7 @@ describe.skipIf(skipTests)("integration: prepare-db", () => {
     }
   });
 
+  // 60s timeout for PostgreSQL startup + multiple SQL queries in slow CI
   test("explain_generic validates input and prevents SQL injection", async () => {
     pg = await createTempPostgres();
 
@@ -495,5 +496,5 @@ describe.skipIf(skipTests)("integration: prepare-db", () => {
     } finally {
       await pg.cleanup();
     }
-  });
+  }, { timeout: 60000 });
 });

package/test/init.test.ts

@@ -1,5 +1,7 @@
-import { describe, test, expect, beforeAll } from "bun:test";
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
 import { resolve } from "path";
+import * as fs from "fs";
+import * as os from "os";
 
 // Import from source directly since we're using Bun
 import * as init from "../lib/init";
@@ -415,3 +417,111 @@ describe("CLI commands", () => {
     expect(r.stderr).toMatch(/Cannot use --api-key with --demo mode/);
   });
 });
+
+describe("imageTag priority behavior", () => {
+  // Tests for the imageTag priority: --tag flag > PGAI_TAG env var > pkg.version
+  // This verifies the fix that prevents stale .env PGAI_TAG from being used
+
+  let tempDir: string;
+
+  beforeAll(() => {
+    tempDir = fs.mkdtempSync(resolve(os.tmpdir(), "pgai-test-"));
+  });
+
+  afterAll(() => {
+    if (tempDir && fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  test("stale .env PGAI_TAG is NOT used - CLI version takes precedence", () => {
+    // Create a stale .env with an old tag value
+    const testDir = resolve(tempDir, "stale-tag-test");
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=beta\n");
+    // Create minimal docker-compose.yml so resolvePaths() finds it
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), "version: '3'\nservices: {}\n");
+
+    // Run from the test directory (so resolvePaths finds docker-compose.yml)
+    const cliPath = resolve(import.meta.dir, "..", "bin", "postgres-ai.ts");
+    const bunBin = typeof process.execPath === "string" && process.execPath.length > 0 ? process.execPath : "bun";
+    const result = Bun.spawnSync([bunBin, cliPath, "mon", "local-install", "--db-url", "postgresql://u:p@h:5432/d", "--yes"], {
+      env: { ...process.env, PGAI_TAG: undefined },
+      cwd: testDir,
+    });
+
+    // Read the .env that was written
+    const envContent = fs.readFileSync(resolve(testDir, ".env"), "utf8");
+
+    // The .env should NOT contain the stale "beta" tag - it should use pkg.version
+    expect(envContent).not.toMatch(/PGAI_TAG=beta/);
+    // It should contain the CLI version (0.0.0-dev.0 in dev)
+    expect(envContent).toMatch(/PGAI_TAG=\d+\.\d+\.\d+|PGAI_TAG=0\.0\.0-dev/);
+  });
+
+  test("--tag flag takes priority over pkg.version", () => {
+    const testDir = resolve(tempDir, "tag-flag-test");
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), "version: '3'\nservices: {}\n");
+
+    const cliPath = resolve(import.meta.dir, "..", "bin", "postgres-ai.ts");
+    const bunBin = typeof process.execPath === "string" && process.execPath.length > 0 ? process.execPath : "bun";
+    const result = Bun.spawnSync([bunBin, cliPath, "mon", "local-install", "--tag", "v1.2.3-custom", "--db-url", "postgresql://u:p@h:5432/d", "--yes"], {
+      env: { ...process.env, PGAI_TAG: undefined },
+      cwd: testDir,
+    });
+
+    const envContent = fs.readFileSync(resolve(testDir, ".env"), "utf8");
+    expect(envContent).toMatch(/PGAI_TAG=v1\.2\.3-custom/);
+
+    // Verify stdout confirms the tag being used
+    const stdout = new TextDecoder().decode(result.stdout);
+    expect(stdout).toMatch(/Using image tag: v1\.2\.3-custom/);
+  });
+
+  test("PGAI_TAG env var is intentionally ignored (Bun auto-loads .env)", () => {
+    // Note: We do NOT use process.env.PGAI_TAG because Bun auto-loads .env files,
+    // which would cause stale .env values to pollute the environment.
+    // Users should use --tag flag to override, not env vars.
+    const testDir = resolve(tempDir, "env-var-ignored-test");
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), "version: '3'\nservices: {}\n");
+
+    const cliPath = resolve(import.meta.dir, "..", "bin", "postgres-ai.ts");
+    const bunBin = typeof process.execPath === "string" && process.execPath.length > 0 ? process.execPath : "bun";
+    const result = Bun.spawnSync([bunBin, cliPath, "mon", "local-install", "--db-url", "postgresql://u:p@h:5432/d", "--yes"], {
+      env: { ...process.env, PGAI_TAG: "v2.0.0-from-env" },
+      cwd: testDir,
+    });
+
+    const envContent = fs.readFileSync(resolve(testDir, ".env"), "utf8");
+    // PGAI_TAG env var should be IGNORED - uses pkg.version instead
+    expect(envContent).not.toMatch(/PGAI_TAG=v2\.0\.0-from-env/);
+    expect(envContent).toMatch(/PGAI_TAG=\d+\.\d+\.\d+|PGAI_TAG=0\.0\.0-dev/);
+  });
+
+  test("existing registry and password are preserved while tag is updated", () => {
+    const testDir = resolve(tempDir, "preserve-test");
+    fs.mkdirSync(testDir, { recursive: true });
+    // Create .env with stale tag but valid registry and password
+    fs.writeFileSync(resolve(testDir, ".env"),
+      "PGAI_TAG=stale-tag\nPGAI_REGISTRY=my.registry.com\nGF_SECURITY_ADMIN_PASSWORD=secret123\n");
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), "version: '3'\nservices: {}\n");
+
+    const cliPath = resolve(import.meta.dir, "..", "bin", "postgres-ai.ts");
+    const bunBin = typeof process.execPath === "string" && process.execPath.length > 0 ? process.execPath : "bun";
+    const result = Bun.spawnSync([bunBin, cliPath, "mon", "local-install", "--db-url", "postgresql://u:p@h:5432/d", "--yes"], {
+      env: { ...process.env, PGAI_TAG: undefined },
+      cwd: testDir,
+    });
+
+    const envContent = fs.readFileSync(resolve(testDir, ".env"), "utf8");
+
+    // Tag should be updated (not stale-tag)
+    expect(envContent).not.toMatch(/PGAI_TAG=stale-tag/);
+
+    // But registry and password should be preserved
+    expect(envContent).toMatch(/PGAI_REGISTRY=my\.registry\.com/);
+    expect(envContent).toMatch(/GF_SECURITY_ADMIN_PASSWORD=secret123/);
+  });
+});

package/test/test-utils.ts

@@ -15,6 +15,7 @@ export interface MockClientOptions {
   invalidIndexesRows?: any[];
   unusedIndexesRows?: any[];
   redundantIndexesRows?: any[];
+  sensitiveColumnsRows?: any[];
 }
 
 const DEFAULT_VERSION_ROWS = [
@@ -45,6 +46,7 @@ export function createMockClient(options: MockClientOptions = {}) {
     invalidIndexesRows = [],
     unusedIndexesRows = [],
     redundantIndexesRows = [],
+    sensitiveColumnsRows = [],
   } = options;
 
   return {
@@ -116,6 +118,10 @@ export function createMockClient(options: MockClientOptions = {}) {
           max_connections: 100,
         }] };
       }
+      // S001: Sensitive columns query (from metrics.yml)
+      if (sql.includes("information_schema.columns") && sql.includes("tag_schema_name") && sql.includes("tag_column_name")) {
+        return { rows: sensitiveColumnsRows };
+      }
       throw new Error(`Unexpected query: ${sql}`);
     },
   };