postgresai 0.17.0-dev.4 → 0.17.0-dev.5

package/dist/bin/postgres-ai.js

@@ -13533,7 +13533,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.17.0-dev.4",
+  version: "0.17.0-dev.5",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16893,7 +16893,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.17.0-dev.4";
+var version = "0.17.0-dev.5";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -17169,6 +17169,22 @@ class HttpStatusError extends Error {
 function isRetryableHttpStatus(status) {
   return status >= 500 || status === 429;
 }
+function isUnknownRpcSignature(status, text, rpc) {
+  if (status !== 404)
+    return false;
+  try {
+    const parsed = JSON.parse(text);
+    return typeof parsed.message === "string" && /Could not find the .* function/.test(parsed.message) && parsed.message.includes(`${rpc}(`);
+  } catch {
+    return false;
+  }
+}
+function positiveSeconds(v) {
+  return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : null;
+}
+function asyncPollDelayMs(attempt) {
+  return Math.min(1000 * 2 ** attempt, 15000);
+}
 var DEFAULT_HTTP_REQUEST_TIMEOUT_MS = 25000;
 
 class HttpRequestTimeoutError extends Error {
@@ -21466,7 +21482,8 @@ function summarizeF001(nodeData) {
       return `Autovacuum config: ${parts.join(", ")} finding${fired.length > 1 ? "s" : ""}`;
     };
     if (severity === "CRITICAL" || severity === "WARNING") {
-      return { status: "warning", message: summarize() };
+      const top = fired.find((r) => r.severity === "CRITICAL") ?? fired.find((r) => r.severity === "WARNING");
+      return { status: "warning", message: top?.conclusion ? `${summarize()}. ${top.conclusion}` : summarize() };
     }
     return { status: "info", message: summarize() };
   }
@@ -21625,7 +21642,7 @@ function summarizeG003(nodeData) {
 
 // lib/checkup.ts
 var __dirname = "/builds/postgres-ai/postgresai/cli/lib";
-var CONTRACT_VERSION = "1.0.0";
+var CONTRACT_VERSION = "1.1.0";
 var SECONDS_PER_DAY = 86400;
 var SECONDS_PER_HOUR = 3600;
 var SECONDS_PER_MINUTE = 60;
@@ -27817,46 +27834,58 @@ async function verifyInitSetup(params) {
 }
 
 // lib/joe.ts
+var JOE_ASYNC_FALLBACK_WAIT_MS = 10 * 60 * 1000;
+var JOE_ASYNC_MAX_WAIT_MS = 60 * 60 * 1000;
 async function callRpc(params) {
+  return (await callRpcRaw(params)).data;
+}
+async function callRpcRaw(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 = buildAuthHeaders(apiKey, params.orgScope);
-  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);
+  const send = async (bodyObj) => {
+    const payload = JSON.stringify(bodyObj);
+    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));
     }
-    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)}`);
+    const text = await response.text();
+    if (debug) {
+      console.error(`Debug: Response status: ${response.status}`);
+      console.error(`Debug: Response body: ${redactSecretsForLog(text)}`);
+    }
+    return { response, text };
+  };
+  let { response, text } = await send(body);
+  if (params.fallbackBody && isUnknownRpcSignature(response.status, text, fn)) {
+    ({ response, text } = await send(params.fallbackBody));
   }
   if (!response.ok) {
     throw new HttpStatusError(formatHttpError(operation, response.status, text, response.statusText), response.status);
   }
   try {
-    return JSON.parse(text);
+    return { data: JSON.parse(text), status: response.status };
   } catch {
     throw new Error(`${operation}: failed to parse response: ${redactSecretsForLog(text)}`);
   }
@@ -27905,6 +27934,23 @@ function isNumericProjectRef(ref) {
 }
 
 // lib/connect.ts
+var money = (cents, currency) => currency.toLowerCase() === "usd" ? `$${(cents / 100).toFixed(2)}` : `${(cents / 100).toFixed(2)} ${currency.toUpperCase()}`;
+function priceText(q) {
+  if (!q.billed)
+    return q.free_slots.total ? `free (${q.free_slots.remaining} of ${q.free_slots.total} free slots)` : "free";
+  const { amount, currency, interval } = q.price;
+  const base = `${money(amount, currency)}/${interval} per box (${q.plan} plan)${q.subscription ? `, box ${q.quantity + 1} on the subscription` : ""}`;
+  if (q.promo?.valid && q.amount_after_promo !== undefined && q.amount_after_promo !== null) {
+    const after = `${money(q.amount_after_promo, currency)}`;
+    const how = `with ${q.promo.code} (${q.promo.discount_description})`;
+    if (q.promo.duration === "forever")
+      return `${after}/${interval} ${how}, instead of ${base}`;
+    if (q.promo.duration === "repeating")
+      return `${after}/${interval} for ${q.promo.duration_in_months} months ${how}, then ${base}`;
+    return `${after} the first ${interval} ${how}, then ${base}`;
+  }
+  return base;
+}
 var FIRST_CHECKUP_DELAY_MS = 30 * 60000;
 var POLL_MS = 15000;
 var PROVIDERS = ["clickhouse", "rds", "supabase", "self-managed"];
@@ -27960,7 +28006,7 @@ function stateOf(raw) {
 
 class ClickhouseKeyError extends Error {
 }
-var serverOf = (name) => name.split("/")[0];
+var serverOf = (name) => name.split("/")[0].toLowerCase().replace(/\.(?=$|:)/, "");
 var errorText = (err) => err instanceof Error ? err.message : String(err);
 var urlPassword = (u) => decodeURIComponent(u.password) || u.searchParams.get("password") || "";
 var URL_PARAMS_KEPT = ["sslmode", "channel_binding", "application_name"];
@@ -28023,15 +28069,39 @@ function checkupLines(c) {
     return [`Express checkup could not run: ${c.error}`];
   const warnings = c.findings.filter((f) => f.status === "warning");
   const ok = c.findings.filter((f) => f.status === "ok");
+  const failed = c.failed ?? [];
+  const counts = [`${warnings.length} warning${warnings.length === 1 ? "" : "s"}`, `${ok.length} ok`, `${c.info.length} info`, ...failed.length ? [`${failed.length} could not run`] : []];
   return [
-    `Express checkup while the box starts (${c.checks} checks: ${warnings.length} warning${warnings.length === 1 ? "" : "s"}, ${ok.length} ok):`,
+    `Express checkup while the box starts (${c.checks} checks: ${counts.join(", ")}):`,
     ...warnings.map((f) => `  ${f.check_id} ${f.title}: ${f.message}`),
     ...ok.length ? [`  ok: ${ok.map((f) => f.check_id).join(" ")}`] : [],
-    ...c.failed?.length ? [`  could not run: ${c.failed.join(" ")}`] : [],
+    ...c.info.length ? [`  info: ${c.info.join(" ")}`] : [],
+    ...failed.length ? [`  could not run: ${failed.join(" ")}`] : [],
+    c.report_id ? `Saved as report ${c.report_id}: pgai reports files ${c.report_id}` : `Not saved to PostgresAI: ${c.upload_error}`,
     "The full checkup (query analysis and trends) follows on the box."
   ];
 }
+var boxState = (row) => row.status === "launch_requested" && row.registered_at ? "registered" : row.status ?? "starting";
+async function billingFor(q, name, opts, deps) {
+  const billing = { price: priceText(q), requires_payment_method: q.requires_payment_method };
+  if (opts.coupon) {
+    billing.coupon = q.promo?.valid ? { code: q.promo.code, valid: true, description: q.promo.discount_description } : { code: opts.coupon, valid: false, error: q.promo?.error ?? "not valid" };
+  }
+  const billingPage = { ...billing, requires_payment_method: true, next: `Add a payment method at ${deps.billingUrl(q.org_alias)}, then re-run` };
+  const stop = (next) => ({ billing, billingPage, accepted: false, stop: { ...billing, next } });
+  if (billing.coupon && !billing.coupon.valid) {
+    return stop(`Promo code ${opts.coupon}: ${billing.coupon.error}. Nothing was changed: re-run with a valid code, or without ${opts.agent ? "coupon" : "--coupon"}`);
+  }
+  if (q.requires_payment_method)
+    return { billing, billingPage, accepted: false, stop: billingPage };
+  if (q.billed && !opts.yes && !await deps.confirm(`${name} is billed: ${billing.price}. Provision it? (y/N): `)) {
+    return stop(opts.agent ? `Call connect_database again with yes: true to accept ${billing.price}` : `Re-run with --yes to accept ${billing.price}`);
+  }
+  return { billing, billingPage, accepted: q.billed };
+}
 async function connect(url, opts, deps) {
+  const started = deps.now();
+  const progress = (event, message, more = {}) => deps.progress({ event, elapsed_s: Math.round((deps.now() - started) / 1000), message, ...more });
   const provider = opts.provider ?? detectCloudProvider(url);
   if (!PROVIDERS.includes(provider))
     throw new Error(`--provider must be one of: ${PROVIDERS.join(", ")}`);
@@ -28054,6 +28124,9 @@ async function connect(url, opts, deps) {
   const fresh = !row;
   let note = "";
   let checkup;
+  let billing = {};
+  let billingPage;
+  let accepted = false;
   const findOrg = async () => {
     try {
       return await deps.clickhouseOrg(new URL(url).hostname, key.keyId, key.keySecret);
@@ -28082,55 +28155,112 @@ async function connect(url, opts, deps) {
       }
       ch = found;
     }
-    if (opts.resetPassword) {
-      const others = rows.filter((d) => d.name !== name && !disconnecting(d.status) && serverOf(d.name) === serverOf(name));
-      if (others.length) {
-        return { status: "action_required", provider, name, next: `A new password for ${DEFAULT_MONITORING_USER} would cut off the monitoring of ${others.map((d) => d.name).join(", ")} on this server: set PGAI_MON_PASSWORD to its password instead` };
-      }
-    }
-    deps.progress(`Preparing ${maskConnectionString(url)}`);
-    const prepared = await deps.prepare(url, provider, { resetPassword: opts.resetPassword });
-    if ("next" in prepared)
-      return { status: "action_required", provider, name, ...prepared };
-    if (prepared.note)
-      note = `; ${prepared.note}`;
-    if (opts.selfHosted) {
-      await deps.selfHosted(prepared.monitoringUrl, key && ch ? { CLICKHOUSE_ORG_ID: ch.orgId, CLICKHOUSE_KEY_ID: key.keyId, CLICKHOUSE_KEY_SECRET: key.keySecret } : {});
-      return { status: "connected", provider, name, dashboard_url: "http://localhost:3000", host_metrics: !!ch, next: `pgai mon health${note}` };
-    }
-    deps.progress(`Provisioning monitoring for ${name}`);
-    const undo = async () => {
-      if (prepared.generated)
+    const undo = async (p) => {
+      if ("generated" in p && p.generated)
         await deps.unprepare(url).catch(() => false);
     };
-    const created = await deps.create({
-      db_url: prepared.monitoringUrl,
-      ...provider === "clickhouse" ? { provider } : {},
-      ...key && ch ? { clickhouse_org_id: ch.orgId, clickhouse_key_id: key.keyId, clickhouse_key_secret: key.keySecret } : {}
-    }).catch(async (err) => {
-      if (err instanceof HttpStatusError && err.status >= 400 && err.status < 500)
-        await undo();
-      throw err;
-    });
-    if (created.status === "failed") {
-      await undo();
-      return { status: "failed", provider, name, id: created.id, next: `${created.error} Re-run pgai connect later.` };
+    let lockId;
+    const othersOnServer = (list) => list.filter((d) => d.name !== name && !disconnecting(d.status) && serverOf(d.name) === serverOf(name));
+    const cutOff = (others) => ({ status: "action_required", provider, name, next: `A new password for ${DEFAULT_MONITORING_USER} would cut off the monitoring of ${others.map((d) => d.name).join(", ")} on this server: set PGAI_MON_PASSWORD to its password instead` });
+    if (opts.resetPassword) {
+      if (othersOnServer(rows).length)
+        return cutOff(othersOnServer(rows));
+    }
+    if (opts.coupon !== undefined && !opts.coupon.trim()) {
+      return { status: "action_required", provider, name, next: `${opts.agent ? "coupon" : "--coupon"} is empty: pass a promotion code, or leave ${opts.agent ? "coupon" : "--coupon"} out` };
+    }
+    if (!opts.selfHosted) {
+      const b = await billingFor(await deps.quote(opts.coupon), name, opts, deps);
+      if (b.stop)
+        return { status: "action_required", provider, name, ...b.stop };
+      ({ billing, billingPage, accepted } = b);
+      progress("billing", `Billing: ${billing.price}`);
+    }
+    if (opts.resetPassword) {
+      try {
+        lockId = (await deps.resetLock(serverOf(name))).lock_id;
+      } catch (err) {
+        if (err instanceof HttpStatusError && err.status === 409) {
+          return { status: "action_required", provider, name, next: `Another pgai connect --reset-password for ${serverOf(name)} is running: wait for it to finish, then re-run` };
+        }
+        if (err instanceof HttpStatusError && err.status === 404) {
+          return { status: "action_required", provider, name, next: `This platform cannot lock the server for --reset-password yet: set PGAI_MON_PASSWORD to ${DEFAULT_MONITORING_USER}'s password instead` };
+        }
+        throw err;
+      }
+    }
+    let prepared;
+    let created;
+    try {
+      if (lockId) {
+        const now = await deps.list();
+        const same = now.find((d) => d.name === name && !disconnecting(d.status));
+        if (same)
+          return { status: "action_required", provider, name, id: same.id, next: `${name} is already connected, and its monitoring uses the current password: pgai disconnect ${name} --yes first` };
+        const others = othersOnServer(now);
+        if (others.length)
+          return cutOff(others);
+      }
+      progress("preparing", `Preparing ${maskConnectionString(url)}`);
+      prepared = await deps.prepare(url, provider, { resetPassword: opts.resetPassword });
+      if ("next" in prepared)
+        return { status: "action_required", provider, name, ...billing, ...prepared };
+      if (prepared.note)
+        note = `; ${prepared.note}`;
+      if (opts.selfHosted) {
+        await deps.selfHosted(prepared.monitoringUrl, key && ch ? { CLICKHOUSE_ORG_ID: ch.orgId, CLICKHOUSE_KEY_ID: key.keyId, CLICKHOUSE_KEY_SECRET: key.keySecret } : {});
+        return { status: "connected", provider, name, dashboard_url: "http://localhost:3000", host_metrics: !!ch, next: `pgai mon health${note}` };
+      }
+      progress("provisioning", `Provisioning monitoring for ${name}`);
+      created = await deps.create({
+        db_url: prepared.monitoringUrl,
+        ...provider === "clickhouse" ? { provider } : {},
+        ...key && ch ? { clickhouse_org_id: ch.orgId, clickhouse_key_id: key.keyId, clickhouse_key_secret: key.keySecret } : {},
+        ...opts.coupon ? { promo_code: opts.coupon } : {},
+        ...accepted ? { accept_price: true } : {}
+      }).catch(async (err) => {
+        if (err instanceof HttpStatusError && err.status >= 400 && err.status < 500)
+          await undo(prepared);
+        if (err instanceof HttpStatusError && err.status === 402)
+          return /declined/i.test(err.message) ? "declined" : "payment";
+        if (err instanceof HttpStatusError && err.status === 412)
+          return "price";
+        throw err;
+      });
+      if (created === "payment")
+        return { status: "action_required", provider, name, ...billingPage };
+      if (created === "declined") {
+        return { status: "action_required", provider, name, ...billingPage, next: billingPage.next.replace(/^Add a payment method at /, "The payment method on file was declined: update it at ") };
+      }
+      if (created === "price")
+        return { status: "action_required", provider, name, ...billing, next: "The price changed since it was shown: re-run pgai connect to see it" };
+      if (created.status === "failed") {
+        await undo(prepared);
+        return { status: "failed", provider, name, id: created.id, next: `${created.error} Re-run pgai connect later.` };
+      }
+    } finally {
+      if (lockId)
+        await deps.resetUnlock(lockId).catch(() => {});
     }
     row = { id: created.id, name: created.name, provider, status: created.status, dashboard_url: null, host_metrics: !!ch };
-    checkup = await deps.checkup(withLocalTls(prepared.monitoringUrl, url)).catch((err) => ({ error: errorText(err) }));
-    for (const line of checkupLines(checkup))
-      deps.progress(line);
+    checkup = await deps.checkup(withLocalTls(prepared.monitoringUrl, url), created.name).catch((err) => ({ error: errorText(err) }));
+    progress("checkup", checkupLines(checkup).join(`
+`), { checkup });
   }
-  for (const deadline = Date.now() + opts.waitMs;; ) {
+  let shown;
+  for (const deadline = deps.now() + opts.waitMs;; ) {
     const result = connectStatus(row, provider, fresh);
-    if (result.status !== "provisioning" || Date.now() >= deadline) {
+    const state = boxState(row);
+    if (state !== shown && (shown !== undefined || result.status === "provisioning"))
+      progress("box", `Monitoring box: ${state}`, { state });
+    shown = state;
+    if (result.status !== "provisioning" || deps.now() >= deadline) {
       if (result.status === "connected" && provider === "clickhouse" && !row.host_metrics) {
         result.next += "; for CPU, memory and disk, disconnect and reconnect with --clickhouse-key <key-id>:<key-secret>";
       }
       const { next, ...rest } = result;
-      return { ...rest, ...checkup ? { checkup } : {}, next: next + note };
+      return { ...rest, ...billing, ...checkup ? { checkup } : {}, next: next + note };
     }
-    deps.progress(`Waiting for the monitoring box (${row.status ?? "starting"})`);
     await deps.sleep(POLL_MS);
     row = (await deps.list().catch(() => [])).find((d) => d.id === row.id) ?? row;
   }
@@ -28255,14 +28385,52 @@ ${redactPasswordsInSql(s.sql)}`).join(`
 }
 async function expressCheckup(url, opts = {}) {
   const { client } = await openConnection(url, opts);
+  let reports;
+  const failed = [];
   try {
-    const failed = [];
-    const reports = await generateAllReports(client, "node-01", undefined, (f) => failed.push(f.checkId));
-    const findings = Object.values(reports).map((r) => ({ check_id: r.checkId, title: r.checkTitle, status: r.summary.status, message: r.summary.message })).filter((f) => f.status !== "info").sort((a, b) => Number(b.status === "warning") - Number(a.status === "warning"));
-    return { checks: Object.keys(reports).length + failed.length, findings, ...failed.length ? { failed } : {} };
+    reports = await generateAllReports(client, "node-01", undefined, (f) => failed.push(f.checkId));
   } finally {
     await client.end();
   }
+  const all = Object.values(reports).map((r) => ({ check_id: r.checkId, title: r.checkTitle, status: r.summary.status, message: r.summary.message }));
+  const findings = all.filter((f) => f.status !== "info").sort((a, b) => Number(b.status === "warning") - Number(a.status === "warning"));
+  const result = { checks: all.length + failed.length, findings, info: all.filter((f) => f.status === "info").map((f) => f.check_id), ...failed.length ? { failed } : {} };
+  if (!opts.save)
+    return result;
+  try {
+    return { ...result, report_id: await opts.save(reports) };
+  } catch (err) {
+    return { ...result, upload_error: errorText(err) };
+  }
+}
+async function saveCheckupReport(rpc, accessToken, project, reports) {
+  const idOf = (fn, answer, ...keys) => {
+    const a = answer ?? {};
+    const id = Number(keys.map((k) => a[k]).find((v) => v !== undefined));
+    if (!(id > 0))
+      throw new Error(typeof a.message === "string" ? a.message : `Unexpected ${fn} answer: ${JSON.stringify(answer)}`);
+    return id;
+  };
+  const reportId = idOf("checkup_report_create", await rpc("checkup_report_create", { access_token: accessToken, project }), "report_id");
+  const setStatus = (status) => rpc("checkup_report_status_update", { access_token: accessToken, report_id: reportId, status });
+  try {
+    for (const [checkId, report] of Object.entries(reports)) {
+      idOf("checkup_report_file_post", await rpc("checkup_report_file_post", {
+        access_token: accessToken,
+        checkup_report_id: reportId,
+        filename: `${checkId}.json`,
+        check_id: checkId,
+        data: JSON.stringify(report, null, 2),
+        type: "json",
+        generate_issue: true
+      }), "report_chunck_id", "report_chunk_id");
+    }
+  } catch (err) {
+    await setStatus("failed").catch(() => {});
+    throw err;
+  }
+  await setStatus("completed");
+  return reportId;
 }
 async function clickhouseOrgFor(host, keyId, keySecret) {
   const apiUrl = process.env.CLICKHOUSE_API_URL || "https://api.clickhouse.cloud";
@@ -28299,16 +28467,21 @@ function platformDeps(p) {
     list: () => rpc("cloud_monitoring_list"),
     create: (body) => rpc("cloud_monitoring_connect", body),
     disconnect: (id) => rpc("cloud_monitoring_disconnect", { instance_id: id }),
+    resetLock: (server) => rpc("cloud_monitoring_reset_lock", { server }),
+    resetUnlock: (lockId) => rpc("cloud_monitoring_reset_unlock", { lock_id: lockId }),
     prepare: (url, provider, o = {}) => prepareDatabase(url, provider, { ...o, agent: p.agent }),
     unprepare: (url) => unprepareDatabase(url, { agent: p.agent }),
     clickhouseOrg: clickhouseOrgFor,
-    checkup: (url) => expressCheckup(url, { agent: p.agent }),
+    checkup: (url, project) => expressCheckup(url, { agent: p.agent, save: (reports) => saveCheckupReport(rpc, p.apiKey, project, reports) }),
+    quote: (coupon) => rpc("cloud_monitoring_quote", coupon ? { promo_code: coupon } : {}),
+    billingUrl: (orgAlias) => `${p.uiBaseUrl}/${orgAlias}/billing`,
     handoffUrl: async (provider) => {
       const orgs = await listOrgs({ apiKey: p.apiKey, apiBaseUrl: p.apiBaseUrl });
       const org = orgs.length === 1 ? orgs[0] : orgs.find((o) => o.alias === p.orgScope?.alias || o.org_id === p.orgScope?.id);
       return `${p.uiBaseUrl}/${org?.alias ?? "<org>"}/monitoring/scale/create/${provider}`;
     },
-    sleep: (ms) => new Promise((r) => setTimeout(r, ms))
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    now: () => Date.now()
   };
 }
 
@@ -34995,6 +35168,8 @@ async function handleToolCall(req, rootOpts, extra) {
       const result = await connect(url, {
         provider: args.provider ? String(args.provider) : undefined,
         clickhouseKey: args.clickhouse_key ? String(args.clickhouse_key) : undefined,
+        coupon: args.coupon === undefined || args.coupon === null ? undefined : String(args.coupon),
+        yes: args.yes === true,
         waitMs: 0,
         agent: true
       }, {
@@ -35003,6 +35178,7 @@ async function handleToolCall(req, rootOpts, extra) {
           throw new Error("A self-hosted stack is set up from the CLI: pgai connect <url> --self-hosted");
         },
         localStackRunning: () => false,
+        confirm: async () => false,
         progress: () => {}
       });
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], isError: result.status === "failed" };
@@ -35568,7 +35744,7 @@ async function startMcpServer(rootOpts, extra) {
         },
         {
           name: "connect_database",
-          description: "Put a Postgres database under PostgresAI Cloud monitoring (same as `pgai connect`): prepares the monitoring role (an admin URL creates it; otherwise returns the SQL), provisions the monitoring box, and returns JSON with status (connected | provisioning | disconnecting | action_required | failed), dashboard_url and next (the exact next action). It does not wait for the box: call it again to see the status. Safe to call again. ClickHouse Managed Postgres, RDS and Supabase are detected from the host. The URL must carry its password, and only these query parameters: sslmode, channel_binding, application_name. PGAI_MON_PASSWORD, PGPASSWORD and CLICKHOUSE_KEY_ID + CLICKHOUSE_KEY_SECRET of the server process are not used (pass clickhouse_key), and a TLS failure is not retried in plaintext (say sslmode=disable for a server without TLS).",
+          description: "Put a Postgres database under PostgresAI Cloud monitoring (same as `pgai connect`): prepares the monitoring role (an admin URL creates it; otherwise returns the SQL), provisions the monitoring box, and returns JSON with status (connected | provisioning | disconnecting | action_required | failed), dashboard_url and next (the exact next action). A billed box is provisioned only with yes: true: without it the result is action_required with the price (and requires_payment_method), so show the price to the user first. It does not wait for the box: call it again to see the status. Safe to call again. ClickHouse Managed Postgres, RDS and Supabase are detected from the host. The URL must carry its password, and only these query parameters: sslmode, channel_binding, application_name. PGAI_MON_PASSWORD, PGPASSWORD and CLICKHOUSE_KEY_ID + CLICKHOUSE_KEY_SECRET of the server process are not used (pass clickhouse_key), and a TLS failure is not retried in plaintext (say sslmode=disable for a server without TLS).",
           inputSchema: {
             type: "object",
             properties: {
@@ -35576,6 +35752,8 @@ async function startMcpServer(rootOpts, extra) {
               database_url: { type: "string", description: "postgresql:// URL with the password in it (admin, or the postgres_ai_mon role)" },
               provider: { type: "string", description: "clickhouse | rds | supabase | self-managed (default: detected from the host)" },
               clickhouse_key: { type: "string", description: "ClickHouse Cloud API key as <key-id>:<key-secret> (Basic Service API Reader), for CPU, memory and disk" },
+              yes: { type: "boolean", description: "Accept the price of a billed box. Without it, a billed box is not provisioned: the result has status action_required and the price; ask the user, then call again with yes: true" },
+              coupon: { type: "string", description: "Stripe promotion code for the organization's monitoring subscription (applies when it is first created)" },
               debug: { type: "boolean", description: "Enable verbose debug logs" }
             },
             required: ["database_url"],
@@ -36478,6 +36656,23 @@ function renderMarkdownForTerminal(md) {
 }
 
 // lib/connect.ts
+var money2 = (cents, currency) => currency.toLowerCase() === "usd" ? `$${(cents / 100).toFixed(2)}` : `${(cents / 100).toFixed(2)} ${currency.toUpperCase()}`;
+function priceText2(q) {
+  if (!q.billed)
+    return q.free_slots.total ? `free (${q.free_slots.remaining} of ${q.free_slots.total} free slots)` : "free";
+  const { amount, currency, interval } = q.price;
+  const base = `${money2(amount, currency)}/${interval} per box (${q.plan} plan)${q.subscription ? `, box ${q.quantity + 1} on the subscription` : ""}`;
+  if (q.promo?.valid && q.amount_after_promo !== undefined && q.amount_after_promo !== null) {
+    const after = `${money2(q.amount_after_promo, currency)}`;
+    const how = `with ${q.promo.code} (${q.promo.discount_description})`;
+    if (q.promo.duration === "forever")
+      return `${after}/${interval} ${how}, instead of ${base}`;
+    if (q.promo.duration === "repeating")
+      return `${after}/${interval} for ${q.promo.duration_in_months} months ${how}, then ${base}`;
+    return `${after} the first ${interval} ${how}, then ${base}`;
+  }
+  return base;
+}
 var FIRST_CHECKUP_DELAY_MS2 = 30 * 60000;
 var POLL_MS2 = 15000;
 var PROVIDERS2 = ["clickhouse", "rds", "supabase", "self-managed"];
@@ -36533,7 +36728,7 @@ function stateOf2(raw) {
 
 class ClickhouseKeyError2 extends Error {
 }
-var serverOf2 = (name) => name.split("/")[0];
+var serverOf2 = (name) => name.split("/")[0].toLowerCase().replace(/\.(?=$|:)/, "");
 var errorText2 = (err) => err instanceof Error ? err.message : String(err);
 var urlPassword2 = (u) => decodeURIComponent(u.password) || u.searchParams.get("password") || "";
 var URL_PARAMS_KEPT2 = ["sslmode", "channel_binding", "application_name"];
@@ -36596,15 +36791,48 @@ function checkupLines2(c) {
     return [`Express checkup could not run: ${c.error}`];
   const warnings = c.findings.filter((f) => f.status === "warning");
   const ok = c.findings.filter((f) => f.status === "ok");
+  const failed = c.failed ?? [];
+  const counts = [`${warnings.length} warning${warnings.length === 1 ? "" : "s"}`, `${ok.length} ok`, `${c.info.length} info`, ...failed.length ? [`${failed.length} could not run`] : []];
   return [
-    `Express checkup while the box starts (${c.checks} checks: ${warnings.length} warning${warnings.length === 1 ? "" : "s"}, ${ok.length} ok):`,
+    `Express checkup while the box starts (${c.checks} checks: ${counts.join(", ")}):`,
     ...warnings.map((f) => `  ${f.check_id} ${f.title}: ${f.message}`),
     ...ok.length ? [`  ok: ${ok.map((f) => f.check_id).join(" ")}`] : [],
-    ...c.failed?.length ? [`  could not run: ${c.failed.join(" ")}`] : [],
+    ...c.info.length ? [`  info: ${c.info.join(" ")}`] : [],
+    ...failed.length ? [`  could not run: ${failed.join(" ")}`] : [],
+    c.report_id ? `Saved as report ${c.report_id}: pgai reports files ${c.report_id}` : `Not saved to PostgresAI: ${c.upload_error}`,
     "The full checkup (query analysis and trends) follows on the box."
   ];
 }
+function progressText(e) {
+  const s = Math.round(e.elapsed_s);
+  const elapsed = s < 60 ? `${s}s` : `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`;
+  const [first, ...rest] = e.message.split(`
+`);
+  const colon = first.endsWith(":") ? ":" : "";
+  return [`${first.slice(0, first.length - colon.length)} (+${elapsed})${colon}`, ...rest].join(`
+`);
+}
+var boxState2 = (row) => row.status === "launch_requested" && row.registered_at ? "registered" : row.status ?? "starting";
+async function billingFor2(q, name, opts, deps) {
+  const billing = { price: priceText2(q), requires_payment_method: q.requires_payment_method };
+  if (opts.coupon) {
+    billing.coupon = q.promo?.valid ? { code: q.promo.code, valid: true, description: q.promo.discount_description } : { code: opts.coupon, valid: false, error: q.promo?.error ?? "not valid" };
+  }
+  const billingPage = { ...billing, requires_payment_method: true, next: `Add a payment method at ${deps.billingUrl(q.org_alias)}, then re-run` };
+  const stop = (next) => ({ billing, billingPage, accepted: false, stop: { ...billing, next } });
+  if (billing.coupon && !billing.coupon.valid) {
+    return stop(`Promo code ${opts.coupon}: ${billing.coupon.error}. Nothing was changed: re-run with a valid code, or without ${opts.agent ? "coupon" : "--coupon"}`);
+  }
+  if (q.requires_payment_method)
+    return { billing, billingPage, accepted: false, stop: billingPage };
+  if (q.billed && !opts.yes && !await deps.confirm(`${name} is billed: ${billing.price}. Provision it? (y/N): `)) {
+    return stop(opts.agent ? `Call connect_database again with yes: true to accept ${billing.price}` : `Re-run with --yes to accept ${billing.price}`);
+  }
+  return { billing, billingPage, accepted: q.billed };
+}
 async function connect2(url, opts, deps) {
+  const started = deps.now();
+  const progress = (event, message, more = {}) => deps.progress({ event, elapsed_s: Math.round((deps.now() - started) / 1000), message, ...more });
   const provider = opts.provider ?? detectCloudProvider2(url);
   if (!PROVIDERS2.includes(provider))
     throw new Error(`--provider must be one of: ${PROVIDERS2.join(", ")}`);
@@ -36627,6 +36855,9 @@ async function connect2(url, opts, deps) {
   const fresh = !row;
   let note = "";
   let checkup;
+  let billing = {};
+  let billingPage;
+  let accepted = false;
   const findOrg = async () => {
     try {
       return await deps.clickhouseOrg(new URL(url).hostname, key.keyId, key.keySecret);
@@ -36655,55 +36886,112 @@ async function connect2(url, opts, deps) {
       }
       ch = found;
     }
-    if (opts.resetPassword) {
-      const others = rows.filter((d) => d.name !== name && !disconnecting2(d.status) && serverOf2(d.name) === serverOf2(name));
-      if (others.length) {
-        return { status: "action_required", provider, name, next: `A new password for ${DEFAULT_MONITORING_USER} would cut off the monitoring of ${others.map((d) => d.name).join(", ")} on this server: set PGAI_MON_PASSWORD to its password instead` };
-      }
-    }
-    deps.progress(`Preparing ${maskConnectionString(url)}`);
-    const prepared = await deps.prepare(url, provider, { resetPassword: opts.resetPassword });
-    if ("next" in prepared)
-      return { status: "action_required", provider, name, ...prepared };
-    if (prepared.note)
-      note = `; ${prepared.note}`;
-    if (opts.selfHosted) {
-      await deps.selfHosted(prepared.monitoringUrl, key && ch ? { CLICKHOUSE_ORG_ID: ch.orgId, CLICKHOUSE_KEY_ID: key.keyId, CLICKHOUSE_KEY_SECRET: key.keySecret } : {});
-      return { status: "connected", provider, name, dashboard_url: "http://localhost:3000", host_metrics: !!ch, next: `pgai mon health${note}` };
-    }
-    deps.progress(`Provisioning monitoring for ${name}`);
-    const undo = async () => {
-      if (prepared.generated)
+    const undo = async (p) => {
+      if ("generated" in p && p.generated)
         await deps.unprepare(url).catch(() => false);
     };
-    const created = await deps.create({
-      db_url: prepared.monitoringUrl,
-      ...provider === "clickhouse" ? { provider } : {},
-      ...key && ch ? { clickhouse_org_id: ch.orgId, clickhouse_key_id: key.keyId, clickhouse_key_secret: key.keySecret } : {}
-    }).catch(async (err) => {
-      if (err instanceof HttpStatusError && err.status >= 400 && err.status < 500)
-        await undo();
-      throw err;
-    });
-    if (created.status === "failed") {
-      await undo();
-      return { status: "failed", provider, name, id: created.id, next: `${created.error} Re-run pgai connect later.` };
+    let lockId;
+    const othersOnServer = (list) => list.filter((d) => d.name !== name && !disconnecting2(d.status) && serverOf2(d.name) === serverOf2(name));
+    const cutOff = (others) => ({ status: "action_required", provider, name, next: `A new password for ${DEFAULT_MONITORING_USER} would cut off the monitoring of ${others.map((d) => d.name).join(", ")} on this server: set PGAI_MON_PASSWORD to its password instead` });
+    if (opts.resetPassword) {
+      if (othersOnServer(rows).length)
+        return cutOff(othersOnServer(rows));
+    }
+    if (opts.coupon !== undefined && !opts.coupon.trim()) {
+      return { status: "action_required", provider, name, next: `${opts.agent ? "coupon" : "--coupon"} is empty: pass a promotion code, or leave ${opts.agent ? "coupon" : "--coupon"} out` };
+    }
+    if (!opts.selfHosted) {
+      const b = await billingFor2(await deps.quote(opts.coupon), name, opts, deps);
+      if (b.stop)
+        return { status: "action_required", provider, name, ...b.stop };
+      ({ billing, billingPage, accepted } = b);
+      progress("billing", `Billing: ${billing.price}`);
+    }
+    if (opts.resetPassword) {
+      try {
+        lockId = (await deps.resetLock(serverOf2(name))).lock_id;
+      } catch (err) {
+        if (err instanceof HttpStatusError && err.status === 409) {
+          return { status: "action_required", provider, name, next: `Another pgai connect --reset-password for ${serverOf2(name)} is running: wait for it to finish, then re-run` };
+        }
+        if (err instanceof HttpStatusError && err.status === 404) {
+          return { status: "action_required", provider, name, next: `This platform cannot lock the server for --reset-password yet: set PGAI_MON_PASSWORD to ${DEFAULT_MONITORING_USER}'s password instead` };
+        }
+        throw err;
+      }
+    }
+    let prepared;
+    let created;
+    try {
+      if (lockId) {
+        const now = await deps.list();
+        const same = now.find((d) => d.name === name && !disconnecting2(d.status));
+        if (same)
+          return { status: "action_required", provider, name, id: same.id, next: `${name} is already connected, and its monitoring uses the current password: pgai disconnect ${name} --yes first` };
+        const others = othersOnServer(now);
+        if (others.length)
+          return cutOff(others);
+      }
+      progress("preparing", `Preparing ${maskConnectionString(url)}`);
+      prepared = await deps.prepare(url, provider, { resetPassword: opts.resetPassword });
+      if ("next" in prepared)
+        return { status: "action_required", provider, name, ...billing, ...prepared };
+      if (prepared.note)
+        note = `; ${prepared.note}`;
+      if (opts.selfHosted) {
+        await deps.selfHosted(prepared.monitoringUrl, key && ch ? { CLICKHOUSE_ORG_ID: ch.orgId, CLICKHOUSE_KEY_ID: key.keyId, CLICKHOUSE_KEY_SECRET: key.keySecret } : {});
+        return { status: "connected", provider, name, dashboard_url: "http://localhost:3000", host_metrics: !!ch, next: `pgai mon health${note}` };
+      }
+      progress("provisioning", `Provisioning monitoring for ${name}`);
+      created = await deps.create({
+        db_url: prepared.monitoringUrl,
+        ...provider === "clickhouse" ? { provider } : {},
+        ...key && ch ? { clickhouse_org_id: ch.orgId, clickhouse_key_id: key.keyId, clickhouse_key_secret: key.keySecret } : {},
+        ...opts.coupon ? { promo_code: opts.coupon } : {},
+        ...accepted ? { accept_price: true } : {}
+      }).catch(async (err) => {
+        if (err instanceof HttpStatusError && err.status >= 400 && err.status < 500)
+          await undo(prepared);
+        if (err instanceof HttpStatusError && err.status === 402)
+          return /declined/i.test(err.message) ? "declined" : "payment";
+        if (err instanceof HttpStatusError && err.status === 412)
+          return "price";
+        throw err;
+      });
+      if (created === "payment")
+        return { status: "action_required", provider, name, ...billingPage };
+      if (created === "declined") {
+        return { status: "action_required", provider, name, ...billingPage, next: billingPage.next.replace(/^Add a payment method at /, "The payment method on file was declined: update it at ") };
+      }
+      if (created === "price")
+        return { status: "action_required", provider, name, ...billing, next: "The price changed since it was shown: re-run pgai connect to see it" };
+      if (created.status === "failed") {
+        await undo(prepared);
+        return { status: "failed", provider, name, id: created.id, next: `${created.error} Re-run pgai connect later.` };
+      }
+    } finally {
+      if (lockId)
+        await deps.resetUnlock(lockId).catch(() => {});
     }
     row = { id: created.id, name: created.name, provider, status: created.status, dashboard_url: null, host_metrics: !!ch };
-    checkup = await deps.checkup(withLocalTls2(prepared.monitoringUrl, url)).catch((err) => ({ error: errorText2(err) }));
-    for (const line of checkupLines2(checkup))
-      deps.progress(line);
+    checkup = await deps.checkup(withLocalTls2(prepared.monitoringUrl, url), created.name).catch((err) => ({ error: errorText2(err) }));
+    progress("checkup", checkupLines2(checkup).join(`
+`), { checkup });
   }
-  for (const deadline = Date.now() + opts.waitMs;; ) {
+  let shown;
+  for (const deadline = deps.now() + opts.waitMs;; ) {
     const result = connectStatus2(row, provider, fresh);
-    if (result.status !== "provisioning" || Date.now() >= deadline) {
+    const state = boxState2(row);
+    if (state !== shown && (shown !== undefined || result.status === "provisioning"))
+      progress("box", `Monitoring box: ${state}`, { state });
+    shown = state;
+    if (result.status !== "provisioning" || deps.now() >= deadline) {
       if (result.status === "connected" && provider === "clickhouse" && !row.host_metrics) {
         result.next += "; for CPU, memory and disk, disconnect and reconnect with --clickhouse-key <key-id>:<key-secret>";
       }
       const { next, ...rest } = result;
-      return { ...rest, ...checkup ? { checkup } : {}, next: next + note };
+      return { ...rest, ...billing, ...checkup ? { checkup } : {}, next: next + note };
     }
-    deps.progress(`Waiting for the monitoring box (${row.status ?? "starting"})`);
     await deps.sleep(POLL_MS2);
     row = (await deps.list().catch(() => [])).find((d) => d.id === row.id) ?? row;
   }
@@ -36828,14 +37116,52 @@ ${redactPasswordsInSql(s.sql)}`).join(`
 }
 async function expressCheckup2(url, opts = {}) {
   const { client } = await openConnection2(url, opts);
+  let reports;
+  const failed = [];
   try {
-    const failed = [];
-    const reports = await generateAllReports(client, "node-01", undefined, (f) => failed.push(f.checkId));
-    const findings = Object.values(reports).map((r) => ({ check_id: r.checkId, title: r.checkTitle, status: r.summary.status, message: r.summary.message })).filter((f) => f.status !== "info").sort((a, b) => Number(b.status === "warning") - Number(a.status === "warning"));
-    return { checks: Object.keys(reports).length + failed.length, findings, ...failed.length ? { failed } : {} };
+    reports = await generateAllReports(client, "node-01", undefined, (f) => failed.push(f.checkId));
   } finally {
     await client.end();
   }
+  const all = Object.values(reports).map((r) => ({ check_id: r.checkId, title: r.checkTitle, status: r.summary.status, message: r.summary.message }));
+  const findings = all.filter((f) => f.status !== "info").sort((a, b) => Number(b.status === "warning") - Number(a.status === "warning"));
+  const result = { checks: all.length + failed.length, findings, info: all.filter((f) => f.status === "info").map((f) => f.check_id), ...failed.length ? { failed } : {} };
+  if (!opts.save)
+    return result;
+  try {
+    return { ...result, report_id: await opts.save(reports) };
+  } catch (err) {
+    return { ...result, upload_error: errorText2(err) };
+  }
+}
+async function saveCheckupReport2(rpc, accessToken, project, reports) {
+  const idOf = (fn, answer, ...keys) => {
+    const a = answer ?? {};
+    const id = Number(keys.map((k) => a[k]).find((v) => v !== undefined));
+    if (!(id > 0))
+      throw new Error(typeof a.message === "string" ? a.message : `Unexpected ${fn} answer: ${JSON.stringify(answer)}`);
+    return id;
+  };
+  const reportId = idOf("checkup_report_create", await rpc("checkup_report_create", { access_token: accessToken, project }), "report_id");
+  const setStatus = (status) => rpc("checkup_report_status_update", { access_token: accessToken, report_id: reportId, status });
+  try {
+    for (const [checkId, report] of Object.entries(reports)) {
+      idOf("checkup_report_file_post", await rpc("checkup_report_file_post", {
+        access_token: accessToken,
+        checkup_report_id: reportId,
+        filename: `${checkId}.json`,
+        check_id: checkId,
+        data: JSON.stringify(report, null, 2),
+        type: "json",
+        generate_issue: true
+      }), "report_chunck_id", "report_chunk_id");
+    }
+  } catch (err) {
+    await setStatus("failed").catch(() => {});
+    throw err;
+  }
+  await setStatus("completed");
+  return reportId;
 }
 async function clickhouseOrgFor2(host, keyId, keySecret) {
   const apiUrl = process.env.CLICKHOUSE_API_URL || "https://api.clickhouse.cloud";
@@ -36872,84 +37198,124 @@ function platformDeps2(p) {
     list: () => rpc("cloud_monitoring_list"),
     create: (body) => rpc("cloud_monitoring_connect", body),
     disconnect: (id) => rpc("cloud_monitoring_disconnect", { instance_id: id }),
+    resetLock: (server) => rpc("cloud_monitoring_reset_lock", { server }),
+    resetUnlock: (lockId) => rpc("cloud_monitoring_reset_unlock", { lock_id: lockId }),
     prepare: (url, provider, o = {}) => prepareDatabase2(url, provider, { ...o, agent: p.agent }),
     unprepare: (url) => unprepareDatabase2(url, { agent: p.agent }),
     clickhouseOrg: clickhouseOrgFor2,
-    checkup: (url) => expressCheckup2(url, { agent: p.agent }),
+    checkup: (url, project) => expressCheckup2(url, { agent: p.agent, save: (reports) => saveCheckupReport2(rpc, p.apiKey, project, reports) }),
+    quote: (coupon) => rpc("cloud_monitoring_quote", coupon ? { promo_code: coupon } : {}),
+    billingUrl: (orgAlias) => `${p.uiBaseUrl}/${orgAlias}/billing`,
     handoffUrl: async (provider) => {
       const orgs = await listOrgs({ apiKey: p.apiKey, apiBaseUrl: p.apiBaseUrl });
       const org = orgs.length === 1 ? orgs[0] : orgs.find((o) => o.alias === p.orgScope?.alias || o.org_id === p.orgScope?.id);
       return `${p.uiBaseUrl}/${org?.alias ?? "<org>"}/monitoring/scale/create/${provider}`;
     },
-    sleep: (ms) => new Promise((r) => setTimeout(r, ms))
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    now: () => Date.now()
   };
 }
 
 // lib/joe.ts
 var DEFAULT_BUDGET_MS = 25000;
 var DEFAULT_POLL_INTERVAL_MS = 800;
+var JOE_ASYNC_FALLBACK_WAIT_MS2 = 10 * 60 * 1000;
+var JOE_ASYNC_MAX_WAIT_MS2 = 60 * 60 * 1000;
+var JOE_ASYNC_MAX_POLL_FAILURES = 5;
 async function callRpc2(params) {
+  return (await callRpcRaw2(params)).data;
+}
+async function callRpcRaw2(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 = buildAuthHeaders(apiKey, params.orgScope);
-  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);
+  const send = async (bodyObj) => {
+    const payload = JSON.stringify(bodyObj);
+    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));
     }
-    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)}`);
+    const text = await response.text();
+    if (debug) {
+      console.error(`Debug: Response status: ${response.status}`);
+      console.error(`Debug: Response body: ${redactSecretsForLog(text)}`);
+    }
+    return { response, text };
+  };
+  let { response, text } = await send(body);
+  if (params.fallbackBody && isUnknownRpcSignature(response.status, text, fn)) {
+    ({ response, text } = await send(params.fallbackBody));
   }
   if (!response.ok) {
     throw new HttpStatusError(formatHttpError(operation, response.status, text, response.statusText), response.status);
   }
   try {
-    return JSON.parse(text);
+    return { data: JSON.parse(text), status: response.status };
   } catch {
     throw new Error(`${operation}: failed to parse response: ${redactSecretsForLog(text)}`);
   }
 }
-async function startCommand(params) {
+function joeAsyncWaitMs(handle) {
+  const expires = positiveSeconds(handle.expires_in_s);
+  return Math.min(expires ? expires * 1000 : JOE_ASYNC_FALLBACK_WAIT_MS2, JOE_ASYNC_MAX_WAIT_MS2);
+}
+function asyncHandleCommandId(reply, operation) {
+  const commandId = reply?.command_id;
+  if (typeof commandId !== "string" || !/^[0-9]+$/.test(commandId)) {
+    throw new Error(`${operation}: the platform accepted the command over the job channel but ` + `returned no command id: ${redactSecretsForLog(JSON.stringify(reply))}`);
+  }
+  return commandId;
+}
+async function startCommandDetailed(params) {
   const { apiKey, apiBaseUrl, instanceId, command, debug, timeoutMs } = params;
   if (!String(command ?? "").trim()) {
     throw new Error("command text is required");
   }
-  const commandId = await callRpc2({
+  const operation = "Failed to run Joe command";
+  const body = { instance_id: instanceId, command };
+  const { data, status } = await callRpcRaw2({
     apiKey,
     apiBaseUrl,
     fn: "joe_command_run",
-    body: { instance_id: instanceId, command },
-    operation: "Failed to run Joe command",
+    body: { ...body, accept_async: true },
+    fallbackBody: body,
+    operation,
     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))}`);
+  if (status === 202) {
+    const handle = data ?? {};
+    return {
+      commandId: asyncHandleCommandId(data, operation),
+      asyncWaitMs: joeAsyncWaitMs(handle),
+      firstAnswerEstimateS: positiveSeconds(handle.first_answer_estimate_s)
+    };
   }
-  return commandId;
+  if (typeof data !== "string" || !/^[0-9]+$/.test(data)) {
+    throw new Error(`${operation}: expected a command id string, got: ${redactSecretsForLog(JSON.stringify(data))}`);
+  }
+  return { commandId: data, asyncWaitMs: null, firstAnswerEstimateS: null };
 }
 async function getCommandOutput(params) {
   const { apiKey, apiBaseUrl, commandId, debug, timeoutMs } = params;
@@ -37079,18 +37445,29 @@ function buildJoeCommandText(command, input = {}) {
 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 explicitBudgetMs = typeof params.budgetMs === "number" && Number.isFinite(params.budgetMs) && params.budgetMs >= 0 ? params.budgetMs : null;
   const now = params.now ?? Date.now;
   const sleep = params.sleep ?? defaultSleep;
-  const commandId = await startCommand({ apiKey, apiBaseUrl, instanceId, command, debug });
+  const started = await startCommandDetailed({ apiKey, apiBaseUrl, instanceId, command, debug });
+  const commandId = started.commandId;
+  const budgetMs = explicitBudgetMs ?? started.asyncWaitMs ?? DEFAULT_BUDGET_MS;
+  const pollDelayMs = (attempt) => params.pollIntervalMs ?? (started.asyncWaitMs === null ? DEFAULT_POLL_INTERVAL_MS : asyncPollDelayMs(attempt));
   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 };
+    return { commandId, status, output: null, budgetExpired: true, budgetMs };
   }
-  for (;; ) {
+  let announced = false;
+  const announce = () => {
+    if (announced || started.asyncWaitMs === null)
+      return;
+    announced = true;
+    const estimate = started.firstAnswerEstimateS;
+    console.error(`Queued on the Joe job channel (command ${commandId}` + (estimate ? `, reaches Joe in about ${estimate}s` : "") + `); waiting up to ${Math.round(budgetMs / 1000)}s...`);
+  };
+  let transientFailures = 0;
+  for (let attempt = 0;; attempt++) {
     let output;
     try {
       output = await getCommandOutput({
@@ -37102,25 +37479,28 @@ async function runCommand(params) {
       });
     } catch (err) {
       if (err instanceof HttpRequestTimeoutError) {
-        return { commandId, status, output: null, budgetExpired: true };
+        return { commandId, status, output: null, budgetExpired: true, budgetMs };
       }
       if (err instanceof HttpStatusError && isRetryableHttpStatus(err.status)) {
-        if (now() >= deadline) {
-          return { commandId, status, output: null, budgetExpired: true };
+        transientFailures += 1;
+        if (now() >= deadline || started.asyncWaitMs !== null && transientFailures >= JOE_ASYNC_MAX_POLL_FAILURES) {
+          return { commandId, status, output: null, budgetExpired: true, budgetMs };
         }
-        await sleep(pollIntervalMs);
+        await sleep(pollDelayMs(attempt));
         continue;
       }
       throw err;
     }
+    transientFailures = 0;
     status = output.status;
     if (status === "ok" || status === "error") {
-      return { commandId, status, output, budgetExpired: false };
+      return { commandId, status, output, budgetExpired: false, budgetMs };
     }
     if (now() >= deadline) {
-      return { commandId, status, output: null, budgetExpired: true };
+      return { commandId, status, output: null, budgetExpired: true, budgetMs };
     }
-    await sleep(pollIntervalMs);
+    announce();
+    await sleep(pollDelayMs(attempt));
   }
 }
 async function executeJoeCommand(params) {
@@ -37305,22 +37685,6 @@ async function postDblabRpc(rpc, bodyObj, params) {
   }
   return { response, text };
 }
-function isUnknownRpcSignature(status, text, rpc) {
-  if (status !== 404)
-    return false;
-  try {
-    const parsed = JSON.parse(text);
-    return typeof parsed.message === "string" && /Could not find the .* function/.test(parsed.message) && parsed.message.includes(`${rpc}(`);
-  } catch {
-    return false;
-  }
-}
-function positiveSeconds(v) {
-  return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : null;
-}
-function dblabPollDelay(attempt) {
-  return Math.min(1000 * 2 ** attempt, 15000);
-}
 var DBLAB_ASYNC_FALLBACK_WAIT_MS = 15 * 60 * 1000;
 var DBLAB_ASYNC_MAX_WAIT_MS = 60 * 60 * 1000;
 var DBLAB_POLL_MAX_CONSECUTIVE_FAILURES = 5;
@@ -37407,7 +37771,7 @@ async function awaitDblabCall(handle, params) {
       announced = true;
       console.error(`Waiting for the DBLab instance to pick up the call (job ${jobId}` + (estimate ? `, typically ~${estimate}s` : "") + ")...");
     }
-    const delay = dblabPollDelay(attempt);
+    const delay = asyncPollDelayMs(attempt);
     if (now() + delay >= deadline) {
       throw new Error(`${operation}: timed out waiting for the DBLab instance (job ${jobId}, last status ${lastStatus}). ` + dblabNotResentAdvice(jobId));
     }
@@ -38965,6 +39329,10 @@ async function applyUninitPlan(params) {
   }
   return { applied, errors };
 }
+async function legacyHelperWarnings(client) {
+  const r = await client.query("select to_regprocedure('postgres_ai.explain_generic(text,text,text)') is not null as present");
+  return r.rows?.[0]?.present ? ["legacy SECURITY DEFINER helper postgres_ai.explain_generic(text, text, text) is still installed; its owner or a superuser must drop it"] : [];
+}
 async function verifyInitSetup2(params) {
   await params.client.query("begin isolation level repeatable read;");
   try {
@@ -40137,7 +40505,7 @@ import * as childProcess from "child_process";
 import * as fs9 from "fs";
 import * as path8 from "path";
 var __dirname = "/builds/postgres-ai/postgresai/cli/lib";
-var CONTRACT_VERSION2 = "1.0.0";
+var CONTRACT_VERSION2 = "1.1.0";
 var SECONDS_PER_DAY2 = 86400;
 var SECONDS_PER_HOUR2 = 3600;
 var SECONDS_PER_MINUTE2 = 60;
@@ -42998,7 +43366,8 @@ function summarizeF0012(nodeData) {
       return `Autovacuum config: ${parts.join(", ")} finding${fired.length > 1 ? "s" : ""}`;
     };
     if (severity === "CRITICAL" || severity === "WARNING") {
-      return { status: "warning", message: summarize() };
+      const top = fired.find((r) => r.severity === "CRITICAL") ?? fired.find((r) => r.severity === "WARNING");
+      return { status: "warning", message: top?.conclusion ? `${summarize()}. ${top.conclusion}` : summarize() };
     }
     return { status: "info", message: summarize() };
   }
@@ -43155,6 +43524,24 @@ function summarizeG0032(nodeData) {
   };
 }
 
+// lib/json-stderr.ts
+import { format } from "node:util";
+function writeEvent(event) {
+  process.stderr.write(`${JSON.stringify(event)}
+`);
+}
+async function withJsonStderr(fn) {
+  const { error, warn } = console;
+  console.error = (...args) => writeEvent({ event: "log", level: "error", message: format(...args) });
+  console.warn = (...args) => writeEvent({ event: "log", level: "warn", message: format(...args) });
+  try {
+    return await fn();
+  } finally {
+    console.error = error;
+    console.warn = warn;
+  }
+}
+
 // lib/instances.ts
 import * as fs10 from "fs";
 class InstancesParseError2 extends Error {
@@ -43903,12 +44290,47 @@ function sanitizeTagForBackup(tag) {
   const stripped = stripMatchingQuotes(tag);
   return /^[A-Za-z0-9._-]{1,64}$/.test(stripped) ? stripped : null;
 }
-function readDeployedTag(projectDir) {
+function planUpdateTag(current, cliVersion) {
+  const semver = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(v);
+    return m ? { core: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] } : null;
+  };
+  const cli = semver(cliVersion);
+  if (!cli || cli.pre) {
+    return { tag: null, note: `PGAI_TAG stays ${current ?? "unset"}: this CLI (${cliVersion}) is not a release. To pick a stack version, set PGAI_TAG=<version> in .env and re-run 'postgresai mon update'` };
+  }
+  if (current === cliVersion)
+    return { tag: null, note: `PGAI_TAG is ${cliVersion}, matching this CLI` };
+  const cur = current ? semver(current) : null;
+  if (cur) {
+    const i = cur.core.findIndex((part, j) => part !== cli.core[j]);
+    if (i >= 0 && cur.core[i] > cli.core[i]) {
+      return { tag: null, note: `PGAI_TAG stays ${current}: it is newer than this CLI (${cliVersion}). Upgrade the CLI to move the stack: npm install -g postgresai@latest` };
+    }
+  }
+  return { tag: cliVersion, note: `PGAI_TAG: ${current ?? "unset"} -> ${cliVersion}` };
+}
+var ENV_TAG_LINE = /^([ \t]*(?:export[ \t]+)?PGAI_TAG[ \t]*=[ \t]*)(["']?)([A-Za-z0-9._-]*)\2((?:[ \t]+#[^\r\n]*)?[ \t]*\r?)$/gm;
+var ENV_TAG_ANY = /^[ \t]*(?:export[ \t]+)?PGAI_TAG[ \t]*[=:]/gm;
+function readEnvTag(projectDir) {
   const envFile = path9.resolve(projectDir, ".env");
   if (!fs11.existsSync(envFile))
-    return null;
-  const m = fs11.readFileSync(envFile, "utf8").match(/^PGAI_TAG=(.+)$/m);
-  return m ? sanitizeTagForBackup(m[1]) : null;
+    return { tag: null, plain: true };
+  const content = fs11.readFileSync(envFile, "utf8");
+  const plainLines = [...content.matchAll(ENV_TAG_LINE)];
+  if (plainLines.length !== [...content.matchAll(ENV_TAG_ANY)].length)
+    return { tag: null, plain: false };
+  const last = plainLines.at(-1);
+  return { tag: last && last[3] ? last[3] : null, plain: true };
+}
+function writeEnvTag(projectDir, tag) {
+  const envFile = path9.resolve(projectDir, ".env");
+  const existing = fs11.existsSync(envFile) ? fs11.readFileSync(envFile, "utf8") : "";
+  const content = new RegExp(ENV_TAG_LINE.source, "m").test(existing) ? existing.replace(ENV_TAG_LINE, (_match, prefix, quote, _value, rest) => `${prefix}${quote}${tag}${quote}${rest}`) : `${existing}${existing && !existing.endsWith(`
+`) ? `
+` : ""}PGAI_TAG=${tag}
+`;
+  writeEnvFile(envFile, content);
 }
 function isValidComposeYaml(text) {
   const trimmed = text.trim();
@@ -43959,7 +44381,7 @@ async function refreshBundledComposeIfStale(projectDir, oldTag) {
   const existing = fs11.readFileSync(composeFile, "utf8");
   if (composeContentEqual(existing, fetched))
     return false;
-  const deployedTag = sanitizeTagForBackup(oldTag ?? readDeployedTag(projectDir));
+  const deployedTag = sanitizeTagForBackup(oldTag ?? readEnvTag(projectDir).tag);
   const tagPart = deployedTag ?? new Date().toISOString().replace(/[:.]/g, "-");
   const oldHash = crypto2.createHash("sha256").update(existing).digest("hex").slice(0, 8);
   const backup = path9.resolve(projectDir, `docker-compose.yml.bak-${tagPart}-${oldHash}`);
@@ -44030,6 +44452,9 @@ function withOrgOptions(command) {
   ORG_SCOPED_COMMANDS.add(command);
   return command.option("--org <alias>", `organization alias (or ${ORG_ENV}); required with a global token`).option("--org-id <id>", `organization id (or ${ORG_ID_ENV}); alternative to --org`);
 }
+function jsonConnect(command) {
+  return command.parent === program2 && command.name() === "connect" && (!!command.opts().json || !process.stdout.isTTY);
+}
 program2.hook("preAction", (_thisCommand, actionCommand) => {
   const initPointsToConnect = actionCommand.parent === program2 && actionCommand.name() === "init" && !interactive(actionCommand.opts().json);
   if (!ORG_SCOPED_COMMANDS.has(actionCommand) || initPointsToConnect) {
@@ -44042,7 +44467,10 @@ program2.hook("preAction", (_thisCommand, actionCommand) => {
     setActiveOrgScope(requireOrgScope(opts, apiKey));
   } catch (err) {
     if (err instanceof OrgScopeError2) {
-      console.error(err.message);
+      if (jsonConnect(actionCommand))
+        writeEvent({ event: "log", level: "error", message: err.message });
+      else
+        console.error(err.message);
       process.exit(1);
     }
     throw err;
@@ -44264,6 +44692,7 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
           monitoringUser: opts.monitoringUser,
           includeOptionalPermissions
         });
+        v.missingOptional.push(...await legacyHelperWarnings(supabaseClient));
         if (v.ok) {
           if (jsonOutput) {
             const result = {
@@ -44386,6 +44815,7 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
         client: supabaseClient,
         plan: effectivePlan
       });
+      const legacyWarnings = await legacyHelperWarnings(supabaseClient);
       if (jsonOutput) {
         const result = {
           success: true,
@@ -44395,7 +44825,10 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
           monitoringUser: opts.monitoringUser,
           applied,
           skippedOptional,
-          warnings: skippedOptional.length > 0 ? ["Some optional steps were skipped (not supported or insufficient privileges)"] : []
+          warnings: [
+            ...skippedOptional.length > 0 ? ["Some optional steps were skipped (not supported or insufficient privileges)"] : [],
+            ...legacyWarnings
+          ]
         };
         if (passwordGenerated) {
           result.generatedPassword = monPassword;
@@ -44411,6 +44844,8 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
           for (const s of skippedOptional)
             console.error(`- ${s}`);
         }
+        for (const w of legacyWarnings)
+          console.error(`\u26A0 ${w}`);
         if (process.stdout.isTTY) {
           console.log(`Applied ${applied.length} steps`);
         }
@@ -44552,6 +44987,7 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
         includeOptionalPermissions,
         provider
       });
+      v.missingOptional.push(...await legacyHelperWarnings(client));
       if (v.ok) {
         if (jsonOutput) {
           outputJson({
@@ -44670,6 +45106,7 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
       return;
     }
     const { applied, skippedOptional } = await applyInitPlan2({ client, plan: effectivePlan });
+    const legacyWarnings = await legacyHelperWarnings(client);
     if (jsonOutput) {
       const result = {
         success: true,
@@ -44679,7 +45116,10 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
         monitoringUser: opts.monitoringUser,
         applied,
         skippedOptional,
-        warnings: skippedOptional.length > 0 ? ["Some optional steps were skipped (not supported or insufficient privileges)"] : []
+        warnings: [
+          ...skippedOptional.length > 0 ? ["Some optional steps were skipped (not supported or insufficient privileges)"] : [],
+          ...legacyWarnings
+        ]
       };
       if (passwordGenerated) {
         result.generatedPassword = monPassword;
@@ -44692,6 +45132,8 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
         for (const s of skippedOptional)
           console.error(`- ${s}`);
       }
+      for (const w of legacyWarnings)
+        console.error(`\u26A0 ${w}`);
       if (process.stdout.isTTY) {
         console.log(`Applied ${applied.length} steps`);
       }
@@ -45910,7 +46352,22 @@ function signedIn(opts) {
   }
   return !!cloudApi().apiKey;
 }
-async function runConnect(url, opts) {
+function runConnect(url, opts) {
+  return opts.json || !process.stdout.isTTY ? withJsonStderr(() => connectCommand(url, opts, true)) : connectCommand(url, opts, false);
+}
+function runLocalInstall(args, env, json) {
+  if (!json)
+    return Promise.resolve(childProcess.spawnSync(process.execPath, args, { stdio: ["ignore", 2, 2], env }).status);
+  const child = childProcess.spawn(process.execPath, args, { stdio: ["ignore", "pipe", "pipe"], env });
+  for (const stream of [child.stdout, child.stderr]) {
+    createInterface({ input: stream }).on("line", (line) => writeEvent({ event: "log", level: "info", source: "mon local-install", message: line }));
+  }
+  return new Promise((resolve) => {
+    child.on("error", () => resolve(null));
+    child.on("close", (code) => resolve(code));
+  });
+}
+async function connectCommand(url, opts, json) {
   const name = (() => {
     try {
       return databaseName2(url);
@@ -45926,38 +46383,56 @@ async function runConnect(url, opts) {
   if (!Number.isFinite(waitMinutes) || waitMinutes < 0) {
     return emitConnect({ status: "failed", provider, name, next: "--wait must be a number of minutes (0 = do not wait)" }, opts.json);
   }
-  if (!opts.selfHosted && !signedIn(opts)) {
-    return emitConnect({ status: "action_required", provider, name, next: "Sign in: pgai auth login (agents: set PGAI_API_KEY), then re-run" }, opts.json);
-  }
-  const api = cloudApi(opts.debug);
   try {
+    if (!opts.selfHosted && !signedIn(opts)) {
+      return emitConnect({ status: "action_required", provider, name, next: "Sign in: pgai auth login (agents: set PGAI_API_KEY), then re-run" }, opts.json);
+    }
+    const api = cloudApi(opts.debug);
     const result = await connect2(url, { ...opts, waitMs: waitMinutes * 60000 }, {
       ...api,
       selfHosted: async (monitoringUrl, env) => {
         const scope = getActiveOrgScope2();
         const org = scope?.alias ? ["--org", scope.alias] : scope?.id ? ["--org-id", String(scope.id)] : [];
         const project = name.replace(/[^A-Za-z0-9._-]+/g, "-");
-        const r = childProcess.spawnSync(process.execPath, [process.argv[1], "mon", "local-install", "-y", ...org, "--project", project], {
-          stdio: ["ignore", 2, 2],
-          env: { ...process.env, ...env, PGAI_DB_URL: monitoringUrl, PGAI_API_BASE_URL: api.apiBaseUrl, ...api.apiKey ? { PGAI_API_KEY: api.apiKey } : {} }
-        });
-        if (r.status !== 0)
+        const status = await runLocalInstall([process.argv[1], "mon", "local-install", "-y", ...org, "--project", project], { ...process.env, ...env, PGAI_DB_URL: monitoringUrl, PGAI_API_BASE_URL: api.apiBaseUrl, ...api.apiKey ? { PGAI_API_KEY: api.apiKey } : {} }, json);
+        if (status !== 0)
           throw new Error("mon local-install failed (see above)");
       },
       localStackRunning: () => checkRunningContainers().running,
-      progress: (line) => console.error(line)
+      confirm: async (q) => {
+        if (!interactive(opts.json))
+          return false;
+        process.exitCode = 130;
+        const answer = await question(q);
+        process.exitCode = undefined;
+        closeReadline();
+        return /^(y|yes)$/i.test(answer.trim());
+      },
+      progress: (e) => json ? writeEvent(e) : console.error(progressText(e))
     });
     emitConnect(result, opts.json);
   } catch (err) {
     emitConnect({ status: "failed", provider, name, next: err instanceof Error ? err.message : String(err) }, opts.json);
   }
 }
-withOrgOptions(program2.command("connect <database-url>")).description("put a database under PostgresAI's care: prepare it, provision monitoring, print the dashboard").option("--provider <provider>", "clickhouse | rds | supabase | self-managed (default: detected from the host)").option("--clickhouse-key <id:secret>", "ClickHouse Cloud API key (Basic Service API Reader) for CPU, memory and disk; or CLICKHOUSE_KEY_ID + CLICKHOUSE_KEY_SECRET").option("--self-hosted", "run the monitoring stack on this machine (mon local-install) instead of PostgresAI Cloud").option("--reset-password", "postgres_ai_mon exists and its password is lost: set a new one (admin URL; refused while another database on the server is monitored)").option("--wait <minutes>", "how long to wait for the monitoring box (0 = do not wait)", "20").option("-y, --yes", "never prompt").option("--json", "JSON output (default when stdout is not a TTY)").option("--debug", "print HTTP requests (secrets masked)").addHelpText("after", [
+withOrgOptions(program2.command("connect <database-url>")).configureOutput({
+  writeErr: (text) => {
+    if (!(process.argv.includes("--json") || !process.stdout.isTTY))
+      return void process.stderr.write(text);
+    for (const line of text.split(`
+`).filter((l) => l.trim() !== ""))
+      writeEvent({ event: "log", level: "error", message: line });
+  }
+}).description("put a database under PostgresAI's care: prepare it, provision monitoring, print the dashboard").option("--provider <provider>", "clickhouse | rds | supabase | self-managed (default: detected from the host)").option("--clickhouse-key <id:secret>", "ClickHouse Cloud API key (Basic Service API Reader) for CPU, memory and disk; or CLICKHOUSE_KEY_ID + CLICKHOUSE_KEY_SECRET").option("--self-hosted", "run the monitoring stack on this machine (mon local-install) instead of PostgresAI Cloud").option("--reset-password", "postgres_ai_mon exists and its password is lost: set a new one (admin URL; refused while another database on the server is monitored)").option("--wait <minutes>", "how long to wait for the monitoring box (0 = do not wait)", "20").option("--coupon <code>", "promotion code for the organization's monitoring subscription (applies when it is first created)").option("-y, --yes", "never prompt: accept the price of a billed box").option("--json", "JSON output (default when stdout is not a TTY)").option("--debug", "print HTTP requests (secrets masked)").addHelpText("after", [
   "",
   "Steps (each skipped when already done; safe to re-run): sign in, prepare the database",
   "(an admin URL creates the postgres_ai_mon role; otherwise the SQL is printed), provision",
   "the monitoring box, run the express checkup while it starts, wait, print the dashboard URL.",
   "",
+  'Billing: before a new box, connect shows its price (or "free (N of M free slots)"). A billed',
+  "box is provisioned only when accepted: at the prompt, or with --yes. With no payment method",
+  "it stops (exit 3) and names the console page to add one. --coupon applies a promotion code.",
+  "",
   'Exit codes: 0 connected or provisioning, 1 failed, 3 action required (see "next").',
   "",
   "Environment: PGAI_API_KEY (instead of signing in), PGAI_MON_PASSWORD (the password of",
@@ -46697,6 +47172,18 @@ mon.command("update").description("update monitoring stack (migrate .env, pull i
     } else {
       console.log("\u2713 .env is up to date");
     }
+    const envTag = readEnvTag(projectDir);
+    const deployedTag = envTag.tag;
+    const tagPlan = envTag.plain ? planUpdateTag(deployedTag, package_default.version) : { tag: null, note: `PGAI_TAG in .env is not a plain value, so it is left as is. To move the stack to ${package_default.version}, set PGAI_TAG=${package_default.version} in .env and re-run 'postgresai mon update'` };
+    if (process.env.PGAI_TAG && process.env.PGAI_TAG !== (tagPlan.tag ?? deployedTag)) {
+      console.error(`\u26A0 PGAI_TAG=${process.env.PGAI_TAG} is set in the environment, and docker compose prefers it over .env: unset it before 'postgresai mon stop && postgresai mon start'`);
+    }
+    if (tagPlan.tag) {
+      writeEnvTag(projectDir, tagPlan.tag);
+      if (process.env.PGAI_TAG === deployedTag)
+        process.env.PGAI_TAG = tagPlan.tag;
+    }
+    console.log(`${tagPlan.tag ? "\u2713 " : ""}${tagPlan.note}`);
     console.log();
     const gitDir = path9.resolve(projectDir, ".git");
     if (fs11.existsSync(gitDir)) {
@@ -46710,7 +47197,7 @@ mon.command("update").description("update monitoring stack (migrate .env, pull i
       console.log(pullOut);
     } else {
       console.log("(not a git checkout \u2014 checking bundled docker-compose.yml)");
-      await refreshBundledComposeIfStale(projectDir);
+      await refreshBundledComposeIfStale(projectDir, deployedTag);
     }
     console.log(`
 Updating Docker images...`);
@@ -46730,7 +47217,7 @@ Updating Docker images...`);
 \u2713 Update completed successfully`);
       console.log(`
 To apply updates, restart monitoring services:`);
-      console.log("  postgres-ai mon restart");
+      console.log("  postgresai mon stop && postgresai mon start");
     } else {
       console.error(`
 \u2717 Docker image update failed`);
@@ -47042,6 +47529,7 @@ async function syncVmalert(projectDir, apply, addOnly = false) {
     setEnvValues(projectDir, { COMPOSE_PROFILES: composeProfilesValue(current, want, "host-metrics") });
   return true;
 }
+var looksLikeConnStr = (value) => /^postgres(ql)?:\/\//i.test(value);
 async function addTarget(file, projectDir, connStr, name, env, { apply = true } = {}) {
   if (!connStr) {
     console.error("Connection string required: postgresql://user:pass@host:port/db");
@@ -47140,8 +47628,17 @@ Re-running with the same name and connection string is safe; retry after fixing
 
 Supabase: with PGAI_SUPABASE_HOST_METRICS=true (environment or .env), writes host-metrics/supabase-<name>.yml.
 RDS instance endpoint: writes RDS_DB_INSTANCE_IDENTIFIER, AWS_REGION, PGAI_CLUSTER and PGAI_NODE_NAME to .env for rds-host-stats.
+
+Environment:
+  PGAI_DB_URL  the connection string, when none is given (keeps the password out of argv);
+               the only argument is then the name: PGAI_DB_URL=... postgres-ai mon targets add my-db
 `).action(async (connStr, name) => {
   const { instancesFile: file, projectDir } = await resolveOrInitPaths();
+  const envUrl = process.env.PGAI_DB_URL || undefined;
+  if (envUrl && name === undefined && (connStr === undefined || !looksLikeConnStr(connStr))) {
+    name = connStr;
+    connStr = envUrl;
+  }
   await addTarget(file, projectDir, connStr, name, process.env);
 });
 targets.command("remove <name>").description("remove monitoring target database").action(async (name) => {
@@ -48541,7 +49038,7 @@ function tryParseJson(s) {
   }
 }
 function printJoeOutcome(outcome, json, budgetMs) {
-  const effectiveBudgetMs = typeof budgetMs === "number" && Number.isFinite(budgetMs) ? budgetMs : DEFAULT_BUDGET_MS;
+  const effectiveBudgetMs = Number.isFinite(outcome.budgetMs) ? outcome.budgetMs : typeof budgetMs === "number" && Number.isFinite(budgetMs) ? budgetMs : DEFAULT_BUDGET_MS;
   const budgetSeconds = Math.round(effectiveBudgetMs / 1000);
   if (outcome.budgetExpired) {
     if (json) {
@@ -49050,9 +49547,10 @@ export {
   monitoringHealthServices,
   persistInstanceId,
   planMonitoringRegistration,
+  planUpdateTag,
   program2 as program,
   readComposeProfiles,
-  readDeployedTag,
+  readEnvTag,
   refreshBundledComposeIfStale,
   registerMonitoringInstance,
   resolveAdoptedProject,
@@ -49060,5 +49558,6 @@ export {
   selfRegisterAndPersist,
   shouldScaleOutNodeExporter,
   statOwner,
-  updatePgwatchConfig
+  updatePgwatchConfig,
+  writeEnvTag
 };