postgresai 0.17.0-rc.3 → 0.17.0-rc.5

package/dist/bin/postgres-ai.js

@@ -13466,8 +13466,11 @@ function resolveBaseUrls2(opts, cfg, defaults = {}) {
     storageBaseUrl: normalizeBaseUrl2(storageCandidate)
   };
 }
-var DEFAULT_HTTP_REQUEST_TIMEOUT_MS2 = 25000;
-var init_util = () => {};
+var DEFAULT_HTTP_REQUEST_TIMEOUT_MS2 = 25000, SENSITIVE_KEY_SRC2 = "(?:password|passwd|db[-_]?pass|connstr|secret|token|api[-_]?key|private[-_]?key|access[-_]?key|cred(?:ential)?s?|dsn)", SENSITIVE_PAIR_SEPARATOR_SRC2 = `["']?\\s*[:=]`, CREDENTIAL_CHAR_SRC2 = "[A-Za-z0-9_+/=~.-]", TEXT_SENSITIVE_PAIR2, CREDENTIAL_RUN_ONLY2;
+var init_util = __esm(() => {
+  TEXT_SENSITIVE_PAIR2 = new RegExp(`(${SENSITIVE_KEY_SRC2}${SENSITIVE_PAIR_SEPARATOR_SRC2}\\s*)` + `(?:("[^"]*"|'[^']*')` + `|([^\\s,;&]+)` + `((?:\\s+(?![^\\s,;&]*${SENSITIVE_KEY_SRC2}${SENSITIVE_PAIR_SEPARATOR_SRC2})[^\\s,;&]+)*)` + `)`, "gi");
+  CREDENTIAL_RUN_ONLY2 = new RegExp(`^${CREDENTIAL_CHAR_SRC2}+$`);
+});
 
 // node_modules/commander/index.js
 var exports_commander = {};
@@ -13530,7 +13533,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.17.0-rc.3",
+  version: "0.17.0-rc.5",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16890,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-rc.3";
+var version = "0.17.0-rc.5";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -17166,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 {
@@ -17219,9 +17238,120 @@ function redactSecretsForLog(text) {
   return JSON.stringify(redactSecrets(parsed));
 }
 var TEXT_URL_USERINFO = /(\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+):[^\s/@]+@/gi;
-var TEXT_SENSITIVE_PAIR = /((?:password|passwd|db[-_]?pass|connstr|secret|token|api[-_]?key|private[-_]?key|access[-_]?key|cred(?:ential)?s?|dsn)["']?\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;&]+)/gi;
+var SENSITIVE_KEY_SRC = "(?:password|passwd|db[-_]?pass|connstr|secret|token|api[-_]?key|private[-_]?key|access[-_]?key|cred(?:ential)?s?|dsn)";
+var SENSITIVE_PAIR_SEPARATOR_SRC = `["']?\\s*[:=]`;
+var CREDENTIAL_CHAR_SRC = "[A-Za-z0-9_+/=~.-]";
+var MIN_CREDENTIAL_RUN = 12;
+var TEXT_SENSITIVE_PAIR = new RegExp(`(${SENSITIVE_KEY_SRC}${SENSITIVE_PAIR_SEPARATOR_SRC}\\s*)` + `(?:("[^"]*"|'[^']*')` + `|([^\\s,;&]+)` + `((?:\\s+(?![^\\s,;&]*${SENSITIVE_KEY_SRC}${SENSITIVE_PAIR_SEPARATOR_SRC})[^\\s,;&]+)*)` + `)`, "gi");
+var CREDENTIAL_RUN_ONLY = new RegExp(`^${CREDENTIAL_CHAR_SRC}+$`);
+var RUN_LEADING_PUNCTUATION = /^[("'\[{<]+/;
+var RUN_TRAILING_PUNCTUATION = /[)"'\]}>!?.,;:]+$/;
+var LONG_CONSONANT_RUN = /[bcdfghjklmnpqrstvwxzBCDFGHJKLMNPQRSTVWXZ]{5,}/;
+var UUID_SHAPE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+function isWordShaped(s) {
+  if (!/^[A-Za-z]+$/.test(s))
+    return false;
+  if (s.length <= 2)
+    return true;
+  if (hasInternalCapital(s))
+    return false;
+  if (!/[aeiouyAEIOUY]/.test(s))
+    return false;
+  return !LONG_CONSONANT_RUN.test(s);
+}
+function hasInternalCapital(s) {
+  return /[a-z]/.test(s) && /.[A-Z]/.test(s);
+}
+function hasHardStructure(core) {
+  if (/=/.test(core.replace(/={1,2}$/, "")))
+    return true;
+  return UUID_SHAPE.test(core);
+}
+function isSeparatedName(core) {
+  const segments = core.split(/[/_.-]/).filter((part) => part.length > 0);
+  if (segments.length < 2)
+    return false;
+  if (!segments.some(isNameSegment))
+    return false;
+  return segments.every((part) => isNameSegment(part) || /^[0-9]{1,4}$/.test(part));
+}
+function isNameSegment(part) {
+  return isWordShaped(part) || /^[A-Z]+$/.test(part) && part.length <= 6;
+}
+function hasTokenSignal(core) {
+  if (/[0-9_+]/.test(core))
+    return true;
+  if (/=$/.test(core))
+    return true;
+  if (hasInternalCapital(core))
+    return true;
+  return LONG_CONSONANT_RUN.test(core);
+}
+function runCore(run) {
+  return run.replace(RUN_LEADING_PUNCTUATION, "").replace(RUN_TRAILING_PUNCTUATION, "");
+}
+function looksLikeCredentialRun(core) {
+  return core.length >= MIN_CREDENTIAL_RUN && !hasHardStructure(core) && hasTokenSignal(core);
+}
+function isChainableFragment(core) {
+  return core.length > 0 && CREDENTIAL_RUN_ONLY.test(core) && !hasHardStructure(core) && !isWordShaped(core);
+}
+function replaceSensitivePair(_match, keyPrefix, quotedValue, _bareValue, tail) {
+  if (quotedValue !== undefined)
+    return `${keyPrefix}[REDACTED]`;
+  const runs = [...(tail ?? "").matchAll(/(\s+)(\S+)/g)].map((m) => {
+    const run = m[2] ?? "";
+    return { gap: m[1] ?? "", run, core: runCore(run) };
+  });
+  const absorbed = runs.map(() => false);
+  for (let i = 0;i < runs.length; ) {
+    if (!isChainableFragment(runs[i].core)) {
+      i++;
+      continue;
+    }
+    let end = i;
+    while (end < runs.length && isChainableFragment(runs[end].core))
+      end++;
+    const members = runs.slice(i, end);
+    const chain = members.map((r) => r.core).join("");
+    const allNames = members.every((r) => isSeparatedName(r.core));
+    if (!allNames && looksLikeCredentialRun(chain))
+      for (let k = i;k < end; k++)
+        absorbed[k] = true;
+    i = end;
+  }
+  let kept = "";
+  for (let k = 0;k < runs.length; k++) {
+    const r = runs[k];
+    if (!absorbed[k]) {
+      kept += r.gap + r.run;
+      continue;
+    }
+    const lead = r.run.match(RUN_LEADING_PUNCTUATION)?.[0] ?? "";
+    const trail = r.run.match(RUN_TRAILING_PUNCTUATION)?.[0] ?? "";
+    if (lead || trail)
+      kept += r.gap + lead + trail;
+  }
+  return `${keyPrefix}[REDACTED]${kept}`;
+}
 function redactTextSecrets(text) {
-  return text.replace(TEXT_URL_USERINFO, "$1:[REDACTED]@").replace(TEXT_SENSITIVE_PAIR, "$1[REDACTED]");
+  return text.replace(TEXT_URL_USERINFO, "$1:[REDACTED]@").replace(TEXT_SENSITIVE_PAIR, replaceSensitivePair);
+}
+function isControlCodePoint(cp) {
+  return cp < 32 || cp === 127 || cp >= 128 && cp <= 159 || cp === 8232 || cp === 8233;
+}
+function stripControlsToSpace(text) {
+  let out = "";
+  for (const ch of text) {
+    const cp = ch.codePointAt(0);
+    out += cp !== undefined && isControlCodePoint(cp) ? " " : ch;
+  }
+  return out;
+}
+function whitespaceTolerantSecretPattern(secret) {
+  const chars = Array.from(secret.replace(/\s+/g, ""));
+  const body = chars.map((c) => c.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("\\s*");
+  return new RegExp(body, "g");
 }
 function normalizeBaseUrl(value) {
   const trimmed = (value || "").replace(/\/$/, "");
@@ -26457,68 +26587,103 @@ function renderMarkdownForTerminal(md) {
 // lib/joe.ts
 var DEFAULT_BUDGET_MS = 25000;
 var DEFAULT_POLL_INTERVAL_MS = 800;
+var JOE_ASYNC_FALLBACK_WAIT_MS = 10 * 60 * 1000;
+var JOE_ASYNC_MAX_WAIT_MS = 60 * 60 * 1000;
+var JOE_ASYNC_MAX_POLL_FAILURES = 5;
 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);
-  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_MS, JOE_ASYNC_MAX_WAIT_MS);
+}
+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 callRpc({
+  const operation = "Failed to run Joe command";
+  const body = { instance_id: instanceId, command };
+  const { data, status } = await callRpcRaw({
     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;
@@ -26549,7 +26714,10 @@ function normalizeProjectRow(row) {
     joe_ready: Boolean(row.joe_ready ?? false),
     tunnel: Boolean(row.tunnel ?? false),
     instance_id: row.instance_id == null ? null : preserveIntegerId(row.instance_id),
-    dblab_instance_id: row.dblab_instance_id == null ? null : preserveIntegerId(row.dblab_instance_id)
+    dblab_instance_id: row.dblab_instance_id == null ? null : preserveIntegerId(row.dblab_instance_id),
+    ...row.monitoring_instance_ids !== undefined && {
+      monitoring_instance_ids: row.monitoring_instance_ids ?? []
+    }
   };
 }
 async function listProjects(params) {
@@ -26645,18 +26813,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({
@@ -26668,25 +26847,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) {
@@ -26797,46 +26979,58 @@ function formatProjectsTable(projects) {
 }
 
 // lib/joe.ts
+var JOE_ASYNC_FALLBACK_WAIT_MS2 = 10 * 60 * 1000;
+var JOE_ASYNC_MAX_WAIT_MS2 = 60 * 60 * 1000;
 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);
-  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)}`);
   }
@@ -26855,7 +27049,10 @@ function normalizeProjectRow2(row) {
     joe_ready: Boolean(row.joe_ready ?? false),
     tunnel: Boolean(row.tunnel ?? false),
     instance_id: row.instance_id == null ? null : preserveIntegerId2(row.instance_id),
-    dblab_instance_id: row.dblab_instance_id == null ? null : preserveIntegerId2(row.dblab_instance_id)
+    dblab_instance_id: row.dblab_instance_id == null ? null : preserveIntegerId2(row.dblab_instance_id),
+    ...row.monitoring_instance_ids !== undefined && {
+      monitoring_instance_ids: row.monitoring_instance_ids ?? []
+    }
   };
 }
 async function listProjects2(params) {
@@ -26914,24 +27111,10 @@ async function resolveDblabInstanceId(params) {
   }
   return String(match.dblab_instance_id);
 }
-async function callDblabApi(params) {
-  const { apiKey, apiBaseUrl, instanceId, action, method, data, operation, debug } = params;
-  if (!apiKey) {
-    throw new Error("API key is required");
-  }
-  if (!instanceId) {
-    throw new Error("instanceId is required");
-  }
+async function postDblabRpc(rpc, bodyObj, params) {
+  const { apiKey, apiBaseUrl, operation, debug } = params;
   const base = normalizeBaseUrl(apiBaseUrl);
-  const url = new URL(`${base}/rpc/dblab_api_call`);
-  const bodyObj = {
-    instance_id: instanceId,
-    action,
-    method
-  };
-  if (data !== undefined) {
-    bodyObj.data = data;
-  }
+  const url = new URL(`${base}/rpc/${rpc}`);
   const body = JSON.stringify(bodyObj);
   const headers = buildAuthHeaders(apiKey);
   if (debug) {
@@ -26955,13 +27138,163 @@ async function callDblabApi(params) {
     }
     throw new Error(describeFetchError(operation, base, err));
   }
-  const text = await response.text();
+  let text;
+  try {
+    text = await response.text();
+  } catch (err) {
+    if (isFetchTimeout(err)) {
+      throw new HttpRequestTimeoutError(operation, requestTimeout.timeoutMs);
+    }
+    throw new Error(describeFetchError(operation, base, err));
+  }
   if (debug) {
     console.error(`Debug: Response status: ${response.status}`);
     console.error(`Debug: Response body: ${redactSecretsForLog(text)}`);
   }
+  return { response, text };
+}
+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;
+var DBLAB_JOB_PENDING = new Set(["queued", "running"]);
+function dblabMayHaveLandedAdvice() {
+  return "The platform may have accepted this call even though the reply was lost — " + "check the instance's current state before running this command again.";
+}
+function dblabNotResentAdvice(jobId) {
+  return `The call (job ${jobId}) was NOT re-sent and may still complete on the instance — ` + "check its current state (e.g. `pgai dblab clone list`) before running this command again.";
+}
+function stripControlsKeepingLines(text) {
+  return text.split(`
+`).map(stripControlsToSpace).join(`
+`);
+}
+function scrubBoxText(text) {
+  return stripControlsToSpace(redactTextSecrets(redactSecretsForLog(text))).replace(/\s+/g, " ").trim();
+}
+async function pollDblabCallOnce(jobIdRaw, jobId, params) {
+  const { operation } = params;
+  const advice = dblabNotResentAdvice(jobId);
+  let response;
+  let text;
+  try {
+    ({ response, text } = await postDblabRpc("dblab_call_result", { p_job_id: jobIdRaw }, params));
+  } catch (err) {
+    return { kind: "transient", why: err instanceof Error ? err.message : String(err) };
+  }
   if (!response.ok) {
-    throw new HttpStatusError(formatHttpError(operation, response.status, text, response.statusText), response.status);
+    if (isRetryableHttpStatus(response.status)) {
+      return { kind: "transient", why: `HTTP ${response.status}` };
+    }
+    throw new HttpStatusError(`${stripControlsKeepingLines(formatHttpError(operation, response.status, text, response.statusText))}
+${advice}`, response.status);
+  }
+  let res;
+  try {
+    res = JSON.parse(text);
+  } catch {
+    throw new Error(`${operation}: failed to parse response: ${stripControlsKeepingLines(redactSecretsForLog(text))}. ${advice}`);
+  }
+  if (!res || typeof res.status !== "string") {
+    throw new Error(`${operation}: dblab_call_result returned an unexpected reply: ${stripControlsKeepingLines(redactSecretsForLog(text))}. ${advice}`);
+  }
+  return { kind: "result", res };
+}
+async function awaitDblabCall(handle, params) {
+  const { operation } = params;
+  const jobIdRaw = typeof handle.job_id === "string" ? handle.job_id : "";
+  const jobId = jobIdRaw ? scrubBoxText(jobIdRaw) : "";
+  if (!jobId) {
+    throw new Error(`${operation}: the platform accepted the call but returned no job_id. ` + dblabMayHaveLandedAdvice());
+  }
+  const now = params.now ?? (() => Date.now());
+  const sleep = params.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const waitMs = Math.min((positiveSeconds(handle.expires_in_s) ?? 0) * 1000 || DBLAB_ASYNC_FALLBACK_WAIT_MS, DBLAB_ASYNC_MAX_WAIT_MS);
+  const deadline = now() + waitMs;
+  const estimate = positiveSeconds(handle.first_answer_estimate_s);
+  let announced = false;
+  let failures = 0;
+  let lastStatus = "unknown";
+  for (let attempt = 0;; attempt++) {
+    const outcome = await pollDblabCallOnce(jobIdRaw, jobId, params);
+    if (outcome.kind === "transient") {
+      failures += 1;
+      if (failures >= DBLAB_POLL_MAX_CONSECUTIVE_FAILURES) {
+        throw new Error(`${operation}: lost contact with the platform while waiting (${failures} polls in a row failed, ` + `last: ${outcome.why}). ${dblabNotResentAdvice(jobId)}`);
+      }
+    } else {
+      failures = 0;
+      const res = outcome.res;
+      lastStatus = scrubBoxText(res.status);
+      if (res.status === "done" && res.outcome === "ok") {
+        return res.result ?? null;
+      }
+      if (!DBLAB_JOB_PENDING.has(res.status)) {
+        const why = typeof res.error === "string" && res.error ? res.error : res.status === "expired" ? "no agent claimed it before it expired" : `outcome ${String(res.outcome ?? "unknown")}`;
+        const klass = typeof res.failure_class === "string" && res.failure_class ? ` [${scrubBoxText(res.failure_class)}]` : "";
+        const advice = res.status === "expired" ? "" : ` ${dblabNotResentAdvice(jobId)}`;
+        throw new Error(`${operation}: the DBLab instance did not complete the call (status ${scrubBoxText(res.status)}) — ` + `${scrubBoxText(why)}${klass}.${advice}`);
+      }
+    }
+    if (!announced && outcome.kind === "result") {
+      announced = true;
+      console.error(`Waiting for the DBLab instance to pick up the call (job ${jobId}` + (estimate ? `, typically ~${estimate}s` : "") + ")...");
+    }
+    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));
+    }
+    await sleep(delay);
+  }
+}
+async function enqueueDblabCall(bodyObj, params, isWrite) {
+  try {
+    return await postDblabRpc("dblab_api_call", bodyObj, params);
+  } catch (err) {
+    if (!isWrite)
+      throw err;
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`${message}
+${dblabMayHaveLandedAdvice()}`, { cause: err });
+  }
+}
+async function callDblabApi(params) {
+  const { apiKey, apiBaseUrl, instanceId, action, method, data, operation, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!instanceId) {
+    throw new Error("instanceId is required");
+  }
+  const bodyObj = {
+    instance_id: instanceId,
+    action,
+    method
+  };
+  if (data !== undefined) {
+    bodyObj.data = data;
+  }
+  const rpcParams = { apiKey, apiBaseUrl, operation, debug };
+  const isWrite = method.toLowerCase() !== "get";
+  let { response, text } = await enqueueDblabCall({ ...bodyObj, accept_async: true }, rpcParams, isWrite);
+  if (isUnknownRpcSignature(response.status, text, "dblab_api_call")) {
+    ({ response, text } = await enqueueDblabCall(bodyObj, rpcParams, isWrite));
+  }
+  if (response.status === 202) {
+    let handle;
+    try {
+      handle = JSON.parse(text);
+    } catch {
+      throw new Error(`${operation}: failed to parse response: ${stripControlsKeepingLines(redactSecretsForLog(text))}. ` + dblabMayHaveLandedAdvice());
+    }
+    if (!handle || typeof handle !== "object") {
+      throw new Error(`${operation}: the platform accepted the call but returned no handle. ` + dblabMayHaveLandedAdvice());
+    }
+    return await awaitDblabCall(handle, rpcParams);
+  }
+  if (!response.ok) {
+    const lost = isWrite && response.status >= 500;
+    throw new HttpStatusError(stripControlsKeepingLines(formatHttpError(operation, response.status, text, response.statusText)) + (lost ? `
+${dblabMayHaveLandedAdvice()}` : ""), response.status);
   }
   if (text.trim() === "") {
     return null;
@@ -26969,7 +27302,7 @@ async function callDblabApi(params) {
   try {
     return JSON.parse(text);
   } catch {
-    throw new Error(`${operation}: failed to parse response: ${redactSecretsForLog(text)}`);
+    throw new Error(`${operation}: failed to parse response: ${stripControlsKeepingLines(redactSecretsForLog(text))}`);
   }
 }
 async function createClone(params) {
@@ -27206,6 +27539,37 @@ async function callRpc3(name, apiKey, body, opts) {
     throw new Error(`${name} returned a body that is not JSON`);
   }
 }
+async function resolveMonitoringInstanceId(params) {
+  const ref = String(params.project ?? "").trim();
+  if (!ref) {
+    throw new Error("project is required (--project <id|alias>)");
+  }
+  const projects = await listProjects2({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    orgId: params.orgId
+  });
+  const needle = ref.toLowerCase();
+  const matches = isNumericProjectRef2(ref) ? projects.filter((p) => String(p.project_id) === BigInt(ref).toString()) : projects.filter((p) => p.alias !== null && p.alias.toLowerCase() === needle || p.name !== null && p.name.toLowerCase() === needle);
+  if (matches.length === 0) {
+    throw new Error(`Project not found for id/alias/name '${ref}'. Run 'pgai projects' to see available projects.`);
+  }
+  if (matches.length > 1) {
+    throw new Error(`'${ref}' matches ${matches.length} projects (ids ${matches.map((p) => p.project_id).join(", ")}). ` + "Pass --project <id> instead.");
+  }
+  const match = matches[0];
+  const ids = match.monitoring_instance_ids;
+  if (ids === undefined) {
+    throw new Error("This platform does not report monitoring instances per project yet. Pass --instance <uuid> instead.");
+  }
+  if (ids.length === 0) {
+    throw new Error(`Project '${ref}' has no active monitoring instance.`);
+  }
+  if (ids.length > 1) {
+    throw new Error(`Project '${ref}' has ${ids.length} active monitoring instances: ${ids.join(", ")}. Pass --instance <uuid>.`);
+  }
+  return ids[0];
+}
 async function enqueueQuery(apiKey, args, opts) {
   const body = {
     p_instance_id: args.instanceId,
@@ -27224,9 +27588,9 @@ async function enqueueQuery(apiKey, args, opts) {
   if (!jobId) {
     throw new Error("instance_query_enqueue returned no job_id");
   }
-  return { jobId, firstAnswerEstimateS: positiveSeconds(reply?.first_answer_estimate_s) };
+  return { jobId, firstAnswerEstimateS: positiveSeconds2(reply?.first_answer_estimate_s) };
 }
-function positiveSeconds(v) {
+function positiveSeconds2(v) {
   return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : null;
 }
 async function readQueryResult(apiKey, jobId, opts) {
@@ -30566,6 +30930,38 @@ async function resolveDatasourceId(adminPassword, debug = false) {
     return null;
   }
 }
+function aasSuccessMessage(r) {
+  const armed = r.armedFor === "pull" ? " (armed for pull: the platform will query this instance's Grafana)" : r.armedFor === "jobs" ? " (armed for the job channel: this instance answers its own queries)" : "";
+  const base = `AAS auto-collection registered${armed}`;
+  if (r.vcpus === 0) {
+    return `${base} — collection stays OFF until a source-DB vCPU count is known (the platform stamps it at provision time; --vcpus <n> sets it for a manual install)`;
+  }
+  if (r.urlPending) {
+    return `${base} — collection starts once this deploy reports the Grafana url to the platform`;
+  }
+  return base;
+}
+var PLATFORM_ERROR_MAX = 300;
+function formatPlatformError(body, secrets = []) {
+  if (!body || typeof body !== "object")
+    return "";
+  const b = body;
+  const str = (v) => typeof v === "string" && v.trim() !== "" ? v.trim() : "";
+  const text = str(b.details) || str(b.message);
+  if (!text)
+    return "";
+  const code = str(b.code);
+  let out = stripControlsToSpace(code ? `${code}: ${text}` : text).replace(/\s+/g, " ").trim();
+  for (const secret of secrets) {
+    const compact = secret.replace(/\s+/g, "");
+    if (compact.length < 8)
+      continue;
+    out = out.replace(whitespaceTolerantSecretPattern(compact), "[redacted]");
+  }
+  out = redactTextSecrets(out);
+  out = out.replace(/glsa_[A-Za-z0-9_-]+/g, "[redacted]");
+  return out.length > PLATFORM_ERROR_MAX ? `${out.slice(0, PLATFORM_ERROR_MAX - 1).trimEnd()}…` : out;
+}
 async function registerAasCollection(apiKey, instanceId, opts) {
   const debug = !!opts.debug;
   try {
@@ -30615,11 +31011,19 @@ async function registerAasCollection(apiKey, instanceId, opts) {
       })
     });
     if (!res.ok) {
+      const detail = formatPlatformError(await res.json().catch(() => null), [apiKey, saToken]);
+      const suffix = detail ? ` — ${detail}` : "";
       if (debug)
-        console.error(`Debug: AAS register failed: HTTP ${res.status}`);
-      return { ok: false, reason: `platform returned HTTP ${res.status}` };
+        console.error(`Debug: AAS register failed: HTTP ${res.status}${suffix}`);
+      return { ok: false, reason: `platform returned HTTP ${res.status}${suffix}` };
     }
-    return { ok: true };
+    const reply = await res.json().catch(() => null);
+    return {
+      ok: true,
+      vcpus: typeof reply?.vcpus === "number" ? reply.vcpus : undefined,
+      urlPending: typeof reply?.url_pending === "boolean" ? reply.url_pending : undefined,
+      armedFor: typeof reply?.armed_for === "string" ? reply.armed_for : undefined
+    };
   } catch (err) {
     if (debug)
       console.error(`Debug: AAS register error: ${err.message}`);
@@ -38950,8 +39354,41 @@ var LOCAL_INSTALL_MANAGED_ENV_KEYS = [
   "VM_FORCE_MERGE_AUTH_KEY",
   "VM_PPROF_AUTH_KEY",
   "PGAI_INSTANCE_ID",
-  "INSTANCE_JOBS_USER"
+  "INSTANCE_JOBS_USER",
+  "COMPOSE_PROFILES"
 ];
+var INSTANCE_JOBS_PROFILE = "instance-jobs";
+function composeProfilesValue(existing, want) {
+  const profiles = [];
+  for (const raw of (existing ?? "").split(",")) {
+    const token = raw.trim();
+    if (token && !profiles.includes(token))
+      profiles.push(token);
+  }
+  const at = profiles.indexOf(INSTANCE_JOBS_PROFILE);
+  if (want === true && at === -1)
+    profiles.push(INSTANCE_JOBS_PROFILE);
+  if (want === false && at !== -1)
+    profiles.splice(at, 1);
+  return profiles.length > 0 ? profiles.join(",") : null;
+}
+function instanceJobsProfileEnabled(composeProfiles) {
+  return (composeProfiles ?? "").split(",").map((p) => p.trim()).includes(INSTANCE_JOBS_PROFILE);
+}
+function resolveInstanceJobsRequest(flag, envValue) {
+  if (flag !== undefined)
+    return { enabled: flag };
+  const value = (envValue ?? "").trim().toLowerCase();
+  if (value === "")
+    return {};
+  if (["1", "true", "yes", "on"].includes(value))
+    return { enabled: true };
+  if (["0", "false", "no", "off"].includes(value))
+    return { enabled: false };
+  return {
+    error: `PGAI_INSTANCE_JOBS=${envValue} is not a boolean ` + "(use true/false, 1/0, yes/no, on/off, or leave it empty to keep the current setting)"
+  };
+}
 function statOwner(file) {
   if (!file)
     return;
@@ -38970,7 +39407,7 @@ function processOwner() {
     return null;
   return `${process.getuid()}:${process.getgid()}`;
 }
-function buildLocalInstallEnv(existingEnv, imageTag, instanceId, credentialFile) {
+function buildLocalInstallEnv(existingEnv, imageTag, instanceId, credentialFile, instanceJobs) {
   const readRaw = (key) => {
     const re = new RegExp(`^[ 	]*(?:export[ 	]+)?${key}=(.*)$`, "gm");
     let value = null;
@@ -39002,6 +39439,10 @@ function buildLocalInstallEnv(existingEnv, imageTag, instanceId, credentialFile)
   const credentialOwner = owner === undefined ? processOwner() : owner;
   if (credentialOwner)
     envLines.push(`INSTANCE_JOBS_USER=${credentialOwner}`);
+  const existingProfiles = readRaw("COMPOSE_PROFILES");
+  const composeProfiles = composeProfilesValue(existingProfiles === null ? null : stripMatchingQuotes(existingProfiles), instanceJobs);
+  if (composeProfiles)
+    envLines.push(`COMPOSE_PROFILES=${composeProfiles}`);
   for (const key of VM_ADMIN_AUTH_KEYS) {
     const existing = readRaw(key);
     envLines.push(`${key}=${existing ? stripMatchingQuotes(existing) : crypto2.randomBytes(32).toString("hex")}`);
@@ -41053,7 +41494,7 @@ async function applyMonitoringTargetsConfig() {
   console.log("Restarting pgwatch collectors to pick up target changes...");
   return runCompose(["up", "-d", "--force-recreate", "pgwatch-prometheus", "pgwatch-postgres"]);
 }
-async function runCompose(args, grafanaPassword) {
+async function runCompose(args, grafanaPassword, extraEnv) {
   let composeFile;
   let projectDir;
   try {
@@ -41117,6 +41558,8 @@ async function runCompose(args, grafanaPassword) {
       }
     }
   }
+  if (extraEnv)
+    Object.assign(env, extraEnv);
   const finalArgs = [...args];
   if (process.platform === "darwin" && shouldScaleOutNodeExporter(args)) {
     finalArgs.push("--scale", "self-node-exporter=0");
@@ -41175,6 +41618,127 @@ Applying sink-prometheus config (VictoriaMetrics admin keys, #359)...`);
   console.log("\u2713 sink-prometheus is running the current config");
   return true;
 }
+function readComposeProfiles(knownProjectDir) {
+  const fromProcess = process.env.COMPOSE_PROFILES;
+  if (fromProcess !== undefined && fromProcess.trim() !== "")
+    return fromProcess;
+  let projectDir;
+  if (knownProjectDir) {
+    projectDir = knownProjectDir;
+  } else {
+    try {
+      ({ projectDir } = resolvePaths());
+    } catch {
+      projectDir = getDefaultMonitoringProjectDir();
+    }
+  }
+  const envFile = path7.resolve(projectDir, ".env");
+  let content;
+  try {
+    content = fs9.readFileSync(envFile, "utf8");
+  } catch (err) {
+    if (err?.code !== "ENOENT") {
+      console.error(`\u26A0 Could not read ${envFile}: ${err instanceof Error ? err.message : String(err)}`);
+      console.error("  Treating the instance-jobs profile as disabled; if it is in fact enabled,");
+      console.error("  an absent container will be reported as '- not enabled' rather than a fault.");
+    }
+    return null;
+  }
+  let value = null;
+  for (const m of content.matchAll(/^[ \t]*(?:export[ \t]+)?COMPOSE_PROFILES=(.*)$/gm)) {
+    value = stripMatchingQuotes(m[1].trim());
+  }
+  return value;
+}
+function instanceJobsRemovalOutcome(before, after, removeExitCode) {
+  if (before === "unknown" || after === "unknown") {
+    return {
+      ok: false,
+      message: `\u2717 Could not determine whether the instance-jobs container is present.
+` + "  The profile is off in .env, but a container left behind keeps polling."
+    };
+  }
+  if (before === "absent") {
+    return { ok: true, message: "\u2713 instance-jobs is disabled (no container was present)" };
+  }
+  if (removeExitCode !== 0 || after !== "absent") {
+    return {
+      ok: false,
+      message: `\u2717 Could not remove the instance-jobs container.
+` + `  The profile is off in .env, but the container is still there and still polling. To retry:
+` + `  COMPOSE_PROFILES=${INSTANCE_JOBS_PROFILE} docker compose rm -sf ${INSTANCE_JOBS_PROFILE}`
+    };
+  }
+  return before === "running" ? {
+    ok: true,
+    message: "\u26A0 instance-jobs was RUNNING and has been removed \u2014 outbound collection on this machine is now OFF"
+  } : { ok: true, message: "\u2713 instance-jobs container removed (it was not running)" };
+}
+function instanceJobsStartSkipReason(storeRunning) {
+  if (storeRunning === true)
+    return null;
+  return storeRunning === false ? "the stack is not running, so instance-jobs was not started - it comes up with the rest on `mon start`" : "could not tell whether the stack is running, so instance-jobs was not started - run `mon start`, then `mon health`";
+}
+async function composeServiceRunning(projectDir, service) {
+  const composeCmd = getComposeCmd();
+  if (!composeCmd)
+    return null;
+  try {
+    const { stdout } = await execFilePromise(composeCmd[0], [...composeCmd.slice(1), "-f", path7.resolve(projectDir, "docker-compose.yml"), "ps", "-q", service], { cwd: projectDir });
+    return stdout.trim().length > 0;
+  } catch {
+    return null;
+  }
+}
+async function applyInstanceJobsProfile(projectDir, enabled) {
+  if (enabled === undefined)
+    return true;
+  if (enabled) {
+    const skip = instanceJobsStartSkipReason(await composeServiceRunning(projectDir, "sink-prometheus"));
+    if (skip) {
+      console.log(`
+(${skip})`);
+      return true;
+    }
+    console.log(`
+Starting the instance-jobs container (compose profile enabled)...`);
+    const code = await runCompose(["up", "-d", "--no-deps", INSTANCE_JOBS_PROFILE]);
+    if (code !== 0) {
+      console.error("\u2717 Could not start the instance-jobs container.");
+      console.error("  The channel is enabled in .env but nothing is polling. To retry:");
+      console.error(`  docker compose up -d --no-deps ${INSTANCE_JOBS_PROFILE}`);
+      return false;
+    }
+    console.log("\u2713 instance-jobs is running");
+    return true;
+  }
+  const before = await inspectInstanceJobsState();
+  if (before === "absent" || before === "unknown") {
+    const verdict = instanceJobsRemovalOutcome(before, before, 0);
+    (verdict.ok ? console.log : console.error)(`
+${verdict.message}`);
+    return verdict.ok;
+  }
+  const code = await runCompose(["rm", "-sf", INSTANCE_JOBS_PROFILE], undefined, { COMPOSE_PROFILES: INSTANCE_JOBS_PROFILE });
+  const verdict = instanceJobsRemovalOutcome(before, await inspectInstanceJobsState(), code);
+  (verdict.ok ? console.log : console.error)(`
+${verdict.message}`);
+  return verdict.ok;
+}
+async function inspectInstanceJobsState() {
+  try {
+    const { stdout } = await execFilePromise("docker", [
+      "inspect",
+      "-f",
+      "{{.State.Running}}",
+      INSTANCE_JOBS_PROFILE
+    ]);
+    return stdout.trim() === "true" ? "running" : "stopped";
+  } catch (error) {
+    const text = error instanceof Error ? error.message : String(error);
+    return /no such (object|container)/i.test(text) ? "absent" : "unknown";
+  }
+}
 program2.command("help").description("show help").action(() => {
   program2.outputHelp();
 });
@@ -41188,7 +41752,7 @@ mon.command("local-install").description("install local monitoring stack (genera
   "      PGAI_ENABLE_IPV6=false   (accepted: true|false|yes|no, lowercase)",
   ""
 ].join(`
-`)).option("--demo", "demo mode with sample database", false).option("--api-key <key>", "Postgres AI API key for automated report uploads").option("--org <alias>", `organization alias (or ${ORG_ENV}); required to register with a global token`).option("--org-id <id>", `organization id (or ${ORG_ID_ENV}); alternative to --org`).option("--db-url <url>", "PostgreSQL connection URL to monitor").option("--tag <tag>", "Docker image tag to use (e.g., 0.14.0, 0.14.0-dev.33)").option("--project <name>", "Docker Compose project name (default: postgres_ai)").option("--instance-id <uuid>", "adopt a console-provisioned monitoring instance instead of self-registering a new one (set automatically by the provisioning flow; PGAI_INSTANCE_ID env also works)").option("--vcpus <n>", "source DB vCPU count used for AAS zone thresholds (PGAI_VCPUS env also works). Omit or 0 = unknown: the platform keeps the value it stamped at provision time. An explicit non-zero value overwrites the stored one; changing it re-arms the AAS backfill.").option("-y, --yes", "accept all defaults and skip interactive prompts", false).action(async (opts) => {
+`)).option("--demo", "demo mode with sample database", false).option("--api-key <key>", "Postgres AI API key for automated report uploads").option("--org <alias>", `organization alias (or ${ORG_ENV}); required to register with a global token`).option("--org-id <id>", `organization id (or ${ORG_ID_ENV}); alternative to --org`).option("--db-url <url>", "PostgreSQL connection URL to monitor").option("--tag <tag>", "Docker image tag to use (e.g., 0.14.0, 0.14.0-dev.33)").option("--project <name>", "Docker Compose project name (default: postgres_ai)").option("--instance-id <uuid>", "adopt a console-provisioned monitoring instance instead of self-registering a new one (set automatically by the provisioning flow; PGAI_INSTANCE_ID env also works)").option("--vcpus <n>", "source DB vCPU count used for AAS zone thresholds (PGAI_VCPUS env also works). Omit or 0 = unknown: the platform keeps the value it stamped at provision time. An explicit non-zero value overwrites the stored one; changing it re-arms the AAS backfill.").option("--instance-jobs", "enable the instance-jobs compose profile (outbound collection channel; PGAI_INSTANCE_JOBS env also works). Writes COMPOSE_PROFILES into the stack .env, so every later mon command covers the container").option("--no-instance-jobs", "disable the instance-jobs compose profile and remove its container").option("-y, --yes", "accept all defaults and skip interactive prompts", false).action(async (opts) => {
   const globalOpts = program2.opts();
   let apiKey = opts.apiKey || globalOpts.apiKey;
   console.log(`
@@ -41210,7 +41774,14 @@ mon.command("local-install").description("install local monitoring stack (genera
   const previousTagMatch = existingEnv.match(/^PGAI_TAG=(.+)$/m);
   const previousTag = previousTagMatch ? previousTagMatch[1].trim() : null;
   const imageTag = opts.tag || package_default.version;
-  const { content: envContent, preservedKeys } = buildLocalInstallEnv(existingEnv, imageTag, opts.instanceId || process.env.PGAI_INSTANCE_ID || null, path7.resolve(projectDir, ".pgwatch-config"));
+  const instanceJobsRequest = resolveInstanceJobsRequest(opts.instanceJobs, process.env.PGAI_INSTANCE_JOBS);
+  if (instanceJobsRequest.error) {
+    console.error(`\u2717 ${instanceJobsRequest.error}`);
+    process.exitCode = 1;
+    return;
+  }
+  const instanceJobs = instanceJobsRequest.enabled;
+  const { content: envContent, preservedKeys } = buildLocalInstallEnv(existingEnv, imageTag, opts.instanceId || process.env.PGAI_INSTANCE_ID || null, path7.resolve(projectDir, ".pgwatch-config"), instanceJobs);
   writeEnvFile(envFile, envContent);
   if (preservedKeys.length > 0) {
     console.log(`Preserved existing .env settings: ${preservedKeys.join(", ")}
@@ -41241,6 +41812,8 @@ Use demo mode without API key: postgres-ai mon local-install --demo`);
     console.error(`\u26A0 Monitoring services are already running: ${containers.join(", ")}`);
     console.log(`Use 'postgres-ai mon restart' to restart them
 `);
+    if (!await applyInstanceJobsProfile(projectDir, instanceJobs))
+      process.exitCode = 1;
     return;
   }
   if (!opts.demo) {
@@ -41530,6 +42103,9 @@ Searched: ${demoCandidates.join(", ")}
   }
   console.log(`\u2713 Services started
 `);
+  const instanceJobsApplied = await applyInstanceJobsProfile(projectDir, instanceJobs);
+  if (!instanceJobsApplied)
+    process.exitCode = 1;
   if (apiKey && !opts.demo) {
     let regOrgScope;
     if (isGlobalTokenValue(apiKey)) {
@@ -41571,7 +42147,7 @@ Searched: ${demoCandidates.join(", ")}
           debug: !!process.env.DEBUG
         });
         if (aas.ok) {
-          console.log(`\u2713 AAS auto-collection registered
+          console.log(`\u2713 ${aasSuccessMessage(aas)}
 `);
         } else {
           console.error(`\u26A0 AAS auto-collection not registered (${aas.reason}); it can be enabled later by re-running 'postgresai mon local-install'
@@ -41590,9 +42166,15 @@ Searched: ${demoCandidates.join(", ")}
     }
   }
   console.log("=================================");
-  console.log("  Local install completed!");
+  console.log(instanceJobsApplied ? "  Local install completed!" : "  Local install completed WITH ONE FAILURE");
   console.log(`=================================
 `);
+  if (!instanceJobsApplied) {
+    console.log(instanceJobs ? `\u2717 The instance-jobs container did not start. Everything below is running; the outbound
+` + "  collection channel is not. See the error above, then `postgres-ai mon health`.\n" : `\u2717 The instance-jobs container could not be removed. Everything below is running, and so
+` + `  is a container that keeps polling. See the error above.
+`);
+  }
   console.log("What's running:");
   if (opts.demo) {
     console.log("  \u2705 Demo PostgreSQL database (monitoring target)");
@@ -41707,7 +42289,7 @@ mon.command("logs [service]").option("-f, --follow", "follow logs", false).optio
 });
 function judgeServiceHealth(service, present, status, health) {
   if (!present) {
-    return service.optional ? { ok: true, mark: "-", label: "not enabled" } : { ok: false, mark: "\u2717", label: "unreachable" };
+    return service.optional ? { ok: true, mark: "-", label: "not enabled" } : { ok: false, mark: "\u2717", label: service.absentLabel ?? "unreachable" };
   }
   if (status !== "running") {
     return { ok: false, mark: "\u2717", label: `unhealthy (status: ${status})` };
@@ -41717,7 +42299,7 @@ function judgeServiceHealth(service, present, status, health) {
   }
   return { ok: true, mark: "\u2713", label: "healthy" };
 }
-function monitoringHealthServices() {
+function monitoringHealthServices(instanceJobsEnabled = false) {
   return [
     { name: "Grafana", container: "grafana-with-datasources" },
     { name: "Prometheus", container: "sink-prometheus" },
@@ -41725,11 +42307,17 @@ function monitoringHealthServices() {
     { name: "PGWatch (Prometheus)", container: "pgwatch-prometheus" },
     { name: "Target DB", container: "target-db" },
     { name: "Sink Postgres", container: "sink-postgres" },
-    { name: "Instance jobs", container: "instance-jobs", optional: true, readHealth: true }
+    {
+      name: "Instance jobs",
+      container: "instance-jobs",
+      optional: !instanceJobsEnabled,
+      readHealth: true,
+      absentLabel: "enabled but not running"
+    }
   ];
 }
 mon.command("health").description("health check for monitoring services").option("--wait <seconds>", "wait time in seconds for services to become healthy", parseInt, 0).action(async (opts) => {
-  const services = monitoringHealthServices();
+  const services = monitoringHealthServices(instanceJobsProfileEnabled(readComposeProfiles()));
   const waitTime = opts.wait || 0;
   const maxAttempts = waitTime > 0 ? Math.ceil(waitTime / 5) : 1;
   console.log(`Checking service health...
@@ -41863,6 +42451,12 @@ Updating Docker images...`);
         process.exitCode = 1;
         return;
       }
+      if (instanceJobsProfileEnabled(readComposeProfiles(projectDir))) {
+        if (!await applyInstanceJobsProfile(projectDir, true)) {
+          process.exitCode = 1;
+          return;
+        }
+      }
       console.log(`
 \u2713 Update completed successfully`);
       console.log(`
@@ -42564,7 +43158,7 @@ program2.command("orgs").description("list organizations this credential can rea
     process.exitCode = 1;
   }
 });
-withOrgOptions(program2.command("promql")).description("run a PromQL query on a monitoring instance's own metric store").argument("<expr>", "PromQL expression").option("--instance <uuid>", "monitoring instance id (default: this box's .pgwatch-config)").option("--at <rfc3339>", "evaluate an instant query at this time (default: now; ignored with --range)").option("--range", "run a range query (requires --start, --end, --step)").option("--start <rfc3339>", "range start").option("--end <rfc3339>", "range end").option("--step <duration>", "range step, e.g. 60s or 5m").option("--timeout <duration>", "how long to wait for an answer (default: sized from the instance's poll pacing; 11m if the platform does not report it)").option("--json", "output the raw result payload").action(async (expr, opts) => {
+withOrgOptions(program2.command("promql")).description("run a PromQL query on a monitoring instance's own metric store").argument("<expr>", "PromQL expression").option("--instance <uuid>", "monitoring instance id (default: this box's .pgwatch-config); not with --project").option("--project <id|alias>", "the project's monitoring instance, by project id, alias or name; not with --instance").option("--at <rfc3339>", "evaluate an instant query at this time (default: now; ignored with --range)").option("--range", "run a range query (requires --start, --end, --step)").option("--start <rfc3339>", "range start").option("--end <rfc3339>", "range end").option("--step <duration>", "range step, e.g. 60s or 5m").option("--timeout <duration>", "how long to wait for an answer (default: sized from the instance's poll pacing; 11m if the platform does not report it)").option("--json", "output the raw result payload").action(async (expr, opts) => {
   try {
     const rootOpts = program2.opts();
     const cfg = readConfig();
@@ -42575,9 +43169,19 @@ withOrgOptions(program2.command("promql")).description("run a PromQL query on a
       return;
     }
     const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
-    const instanceId = opts.instance || readInstanceIdFromProject();
+    if (opts.instance && opts.project) {
+      console.error("Pass --instance or --project, not both.");
+      process.exitCode = 1;
+      return;
+    }
+    const instanceId = opts.instance || (opts.project ? await resolveMonitoringInstanceId({
+      apiKey,
+      apiBaseUrl,
+      project: opts.project,
+      orgId: configOrgIdForBody(apiKey, cfg.orgId)
+    }) : readInstanceIdFromProject());
     if (!instanceId) {
-      console.error("No monitoring instance. Pass --instance <uuid>, or run this on a box whose");
+      console.error("No monitoring instance. Pass --project <id|alias> or --instance <uuid>, or run this on a box whose");
       console.error(".pgwatch-config has an instance_id (written by 'pgai mon local-install').");
       process.exitCode = 1;
       return;
@@ -42617,7 +43221,7 @@ withOrgOptions(program2.command("promql")).description("run a PromQL query on a
     });
     if (!isTerminal2(res.status)) {
       console.error(`Timed out after ${timeoutS}s. Job ${jobId} is still ${res.status}.`);
-      console.error(res.status === "queued" ? "Nothing has claimed it: check the instance-jobs container is running (it is behind " + "a compose profile), or wait \u2014 a first collection can queue ~20 periods ahead of it." : "The instance is working on it \u2014 wait, or re-run with a longer --timeout.");
+      console.error(res.status === "queued" ? "Nothing has claimed it: check the instance-jobs container is running on that instance " + "(`postgresai mon health`; it is behind a compose profile, enabled with " + "`mon local-install --instance-jobs`), or wait \u2014 a first collection can queue " + "~20 periods ahead of it." : "The instance is working on it \u2014 wait, or re-run with a longer --timeout.");
       process.exitCode = 1;
       return;
     }
@@ -43429,7 +44033,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) {
@@ -43927,17 +44531,23 @@ export {
   applyApiKey,
   applyProjectName,
   buildLocalInstallEnv,
+  composeProfilesValue,
   instanceIdToPersist,
+  instanceJobsProfileEnabled,
+  instanceJobsRemovalOutcome,
+  instanceJobsStartSkipReason,
   isValidComposeYaml,
   judgeServiceHealth,
   monitoringHealthServices,
   persistInstanceId,
   planMonitoringRegistration,
   program2 as program,
+  readComposeProfiles,
   readDeployedTag,
   refreshBundledComposeIfStale,
   registerMonitoringInstance,
   resolveAdoptedProject,
+  resolveInstanceJobsRequest,
   selfRegisterAndPersist,
   shouldScaleOutNodeExporter,
   statOwner,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.17.0-rc.3",
+  "version": "0.17.0-rc.5",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,