postgresai 0.17.0-rc.2 → 0.17.0-rc.4

package/README.md

@@ -271,6 +271,35 @@ postgresai mon check                          # System readiness check
 postgresai mon shell <service>                # Open shell to monitoring service
 ```
 
+### PromQL queries (`promql`)
+
+Ask a monitoring instance a PromQL question through the platform. The platform
+never connects to the instance: it queues the query as a job, the instance picks
+it up on its next poll, runs it against its own metric store, and posts the
+answer back.
+
+```bash
+# instant query
+pgai promql 'up' --instance <instance-uuid>
+
+# range query
+pgai promql 'sum(rate(pgwatch_db_stats_xact_commit[5m]))' \
+  --instance <instance-uuid> \
+  --range --start 2026-09-21T00:00:00Z --end 2026-09-21T01:00:00Z --step 60
+
+# on the box itself, --instance is read from .pgwatch-config
+pgai promql 'up'
+```
+
+`--at <time>` evaluates an instant query at a given moment (ignored with
+`--range`). `--json` prints every point instead of the first and last per series.
+The wait is sized from the instance's poll pacing; `--timeout` overrides it. A
+result too large for the byte budget is trimmed and flagged `truncated`.
+
+Requires platform-all !809
+(https://gitlab.com/postgres-ai/platform-all/-/merge_requests/809); until it is
+deployed the command returns a PGRST202 404.
+
 ### MCP server (`mcp` group)
 
 ```bash
@@ -299,7 +328,7 @@ required** — the server will not assume an organization. Call `orgs_list` (or
 run `pgai orgs`) to discover the available ids.
 
 Tools exposed:
-- `list_issues`: returns the same JSON as `postgresai issues list` (args: `{ org_id, status?, hidden_only?, limit?, offset?, debug? }`).
+- `list_issues`: returns the same JSON as `postgresai issues list` (args: `{ org_id, status?, hidden_only?, limit?, offset?, debug? }`). Unlike the CLI, omitting `status` returns open and closed issues; pass `status: "open"` to match the CLI default.
 - `view_issue`: view a single issue with its comments (args: `{ issue_id, org_id, debug? }`).
 - `create_issue`: create a new issue (args: `{ title, description?, org_id, project_id?, labels?, attachments?, is_hidden?, debug? }`).
 - `update_issue`: update title/description/status/labels/is_hidden (args: `{ issue_id, org_id, title?, description?, status?, labels?, attachments?, is_hidden?, debug? }`).
@@ -350,7 +379,8 @@ sensitive.
 ### Issues management (`issues` group)
 
 ```bash
-postgresai issues list                                       # List issues (shows: id, title, status, created_at; is_hidden only when set)
+postgresai issues list                                       # List OPEN issues (shows: id, title, status, created_at; is_hidden only when set)
+postgresai issues list --status closed                       # Only closed issues (--status all for both)
 postgresai issues list --hidden-only                         # Only hidden issues (PostgresAI staff)
 postgresai issues view <issueId>                             # View issue details and comments
 postgresai issues create --org-id <id> <title>               # Create a new issue

package/dist/bin/postgres-ai.js

@@ -13430,6 +13430,11 @@ var require_dist2 = __commonJS(function(exports, module) {
 });
 
 // lib/util.ts
+function requestTimeoutSignal2(timeoutMs) {
+  const requested = typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_HTTP_REQUEST_TIMEOUT_MS2;
+  const bounded = Math.max(1, Math.min(DEFAULT_HTTP_REQUEST_TIMEOUT_MS2, Math.floor(requested)));
+  return { signal: AbortSignal.timeout(bounded), timeoutMs: bounded };
+}
 function maskSecret2(secret) {
   if (!secret)
     return "";
@@ -13461,6 +13466,7 @@ function resolveBaseUrls2(opts, cfg, defaults = {}) {
     storageBaseUrl: normalizeBaseUrl2(storageCandidate)
   };
 }
+var DEFAULT_HTTP_REQUEST_TIMEOUT_MS2 = 25000;
 var init_util = () => {};
 
 // node_modules/commander/index.js
@@ -13524,7 +13530,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.17.0-rc.2",
+  version: "0.17.0-rc.4",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16884,7 +16890,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.2";
+var version = "0.17.0-rc.4";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -17217,6 +17223,22 @@ var TEXT_SENSITIVE_PAIR = /((?:password|passwd|db[-_]?pass|connstr|secret|token|
 function redactTextSecrets(text) {
   return text.replace(TEXT_URL_USERINFO, "$1:[REDACTED]@").replace(TEXT_SENSITIVE_PAIR, "$1[REDACTED]");
 }
+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(/\/$/, "");
   try {
@@ -17315,6 +17337,10 @@ function resolveMcpOrgScope(args, apiKey, cfg) {
 }
 
 // lib/issues.ts
+var IssueStatus = {
+  OPEN: 0,
+  CLOSED: 1
+};
 function issueRequestHeaders(apiKey, orgScope) {
   return buildAuthHeaders(apiKey, orgScope, {
     Prefer: "return=representation",
@@ -17331,6 +17357,17 @@ function withVisibleHiddenFlag(issue) {
   const { is_hidden: _dropped, ...rest } = issue;
   return rest;
 }
+function presentIssue(issue) {
+  const visible = withVisibleHiddenFlag(issue);
+  return { ...visible, status: issueStatusLabel(issue.status) };
+}
+function issueStatusLabel(status) {
+  if (status === IssueStatus.OPEN)
+    return "open";
+  if (status === IssueStatus.CLOSED)
+    return "closed";
+  return status;
+}
 async function fetchIssues(params) {
   const { apiKey, apiBaseUrl, orgScope, orgId, status, limit = 20, offset = 0, hiddenOnly, debug } = params;
   if (!apiKey) {
@@ -24994,7 +25031,7 @@ async function handleToolCall(req, rootOpts, extra) {
       const offset = args.offset !== undefined ? Number(args.offset) : undefined;
       const hiddenOnly = Boolean(args.hidden_only);
       const issues = await fetchIssues({ apiKey, apiBaseUrl, orgId, orgScope: scope.orgScope, status, limit, offset, hiddenOnly, debug });
-      const trimmed = issues.map((issue) => withVisibleHiddenFlag(issue));
+      const trimmed = issues.map((issue) => presentIssue(issue));
       return { content: [{ type: "text", text: JSON.stringify(trimmed, null, 2) }] };
     }
     if (toolName === "view_issue") {
@@ -25010,7 +25047,7 @@ async function handleToolCall(req, rootOpts, extra) {
         return { content: [{ type: "text", text: "Issue not found" }], isError: true };
       }
       const comments = await fetchIssueComments({ apiKey, apiBaseUrl, issueId, orgScope: scope.orgScope, debug });
-      const combined = { issue: withVisibleHiddenFlag(issue), comments };
+      const combined = { issue: presentIssue(issue), comments };
       return { content: [{ type: "text", text: JSON.stringify(combined, null, 2) }] };
     }
     if (toolName === "post_issue_comment") {
@@ -25314,7 +25351,7 @@ async function startMcpServer(rootOpts, extra) {
             type: "object",
             properties: {
               org_id: { type: "number", description: "Organization ID. Optional with a per-organization token (falls back to config); REQUIRED with a global token, which can reach every organization the user belongs to and will not assume one. Use orgs_list / `pgai orgs` to discover valid values." },
-              status: { type: "string", description: "Filter by status: 'open', 'closed', or omit for all" },
+              status: { type: "string", description: "Filter by status: 'open', 'closed', or omit for all (note: the CLI defaults to open). Rows carry status as 'open'/'closed'." },
               limit: { type: "number", description: "Max number of issues to return (default: 20)" },
               offset: { type: "number", description: "Number of issues to skip (default: 0)" },
               hidden_only: { type: "boolean", description: "List only hidden issues (PostgresAI staff; same as CLI --hidden-only)" },
@@ -25596,6 +25633,10 @@ async function startMcpServer(rootOpts, extra) {
 }
 
 // lib/issues.ts
+var IssueStatus2 = {
+  OPEN: 0,
+  CLOSED: 1
+};
 function issueRequestHeaders2(apiKey, orgScope) {
   return buildAuthHeaders(apiKey, orgScope, {
     Prefer: "return=representation",
@@ -25612,6 +25653,17 @@ function withVisibleHiddenFlag2(issue) {
   const { is_hidden: _dropped, ...rest } = issue;
   return rest;
 }
+function presentIssue2(issue) {
+  const visible = withVisibleHiddenFlag2(issue);
+  return { ...visible, status: issueStatusLabel2(issue.status) };
+}
+function issueStatusLabel2(status) {
+  if (status === IssueStatus2.OPEN)
+    return "open";
+  if (status === IssueStatus2.CLOSED)
+    return "closed";
+  return status;
+}
 async function fetchIssues2(params) {
   const { apiKey, apiBaseUrl, orgScope, orgId, status, limit = 20, offset = 0, hiddenOnly, debug } = params;
   if (!apiKey) {
@@ -27138,6 +27190,134 @@ async function destroySnapshot(params) {
 // bin/postgres-ai.ts
 init_util();
 
+// lib/promql.ts
+function describeRpcError(status, body) {
+  try {
+    const parsed = JSON.parse(body);
+    const parts = [parsed.message, parsed.details, parsed.hint].filter(Boolean);
+    if (parts.length)
+      return parts.join(" — ");
+  } catch {}
+  return body.trim() || `HTTP ${status}`;
+}
+async function callRpc3(name, apiKey, body, opts) {
+  const { apiBaseUrl } = resolveBaseUrls(opts);
+  const res = await fetch(`${apiBaseUrl}/rpc/${name}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "access-token": apiKey,
+      ...orgScopeHeaders(getActiveOrgScope())
+    },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(opts?.timeoutMs ?? 30000)
+  });
+  const text = await res.text().catch(() => "");
+  if (!res.ok) {
+    throw new Error(describeRpcError(res.status, text));
+  }
+  try {
+    return text ? JSON.parse(text) : null;
+  } catch {
+    throw new Error(`${name} returned a body that is not JSON`);
+  }
+}
+async function enqueueQuery(apiKey, args, opts) {
+  const body = {
+    p_instance_id: args.instanceId,
+    p_kind: args.kind,
+    p_query: args.query
+  };
+  if (args.kind === "promql_range") {
+    body.p_start = args.start;
+    body.p_end = args.end;
+    body.p_step_s = args.stepS;
+  } else if (args.at) {
+    body.p_at = args.at;
+  }
+  const reply = await callRpc3("instance_query_enqueue", apiKey, body, opts);
+  const jobId = reply?.job_id;
+  if (!jobId) {
+    throw new Error("instance_query_enqueue returned no job_id");
+  }
+  return { jobId, firstAnswerEstimateS: positiveSeconds(reply?.first_answer_estimate_s) };
+}
+function positiveSeconds(v) {
+  return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : null;
+}
+async function readQueryResult(apiKey, jobId, opts) {
+  const reply = await callRpc3("instance_query_result", apiKey, { p_job_id: jobId }, opts);
+  if (!reply || typeof reply.status !== "string") {
+    throw new Error("instance_query_result returned an unexpected reply");
+  }
+  return reply;
+}
+var TERMINAL = new Set(["done", "failed", "expired"]);
+function isTerminal2(status) {
+  return TERMINAL.has(status);
+}
+function pollDelay(attempt) {
+  return Math.min(1000 * 2 ** attempt, 15000);
+}
+async function awaitQueryResult(apiKey, jobId, opts) {
+  const now = opts.now ?? (() => Date.now());
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const deadline = now() + opts.timeoutMs;
+  for (let attempt = 0;; attempt++) {
+    const res = await readQueryResult(apiKey, jobId, opts);
+    if (isTerminal2(res.status))
+      return res;
+    const delay = pollDelay(attempt);
+    if (now() + delay >= deadline)
+      return res;
+    await sleep(delay);
+  }
+}
+function formatMetric(metric) {
+  const name = metric.__name__ ?? "";
+  const labels = Object.entries(metric).filter(([k]) => k !== "__name__").sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}="${v}"`);
+  if (!labels.length)
+    return name || "{}";
+  return `${name}{${labels.join(", ")}}`;
+}
+function pad(s, width) {
+  return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+function renderPromQL(payload) {
+  const lines = [];
+  if (!payload.result.length) {
+    lines.push("Empty result set.");
+  } else if (payload.resultType === "vector") {
+    const rows = payload.result.map((s) => [formatMetric(s.metric), s.value ? s.value[1] : ""]);
+    const w = Math.max(6, ...rows.map((r) => r[0].length));
+    lines.push(`${pad("SERIES", w)}  VALUE`);
+    for (const [m, v] of rows)
+      lines.push(`${pad(m, w)}  ${v}`);
+  } else {
+    const rows = payload.result.map((s) => {
+      const vs = s.values ?? [];
+      const first = vs.length ? vs[0][1] : "";
+      const last = vs.length ? vs[vs.length - 1][1] : "";
+      return [formatMetric(s.metric), String(vs.length), first, last];
+    });
+    const w = Math.max(6, ...rows.map((r) => r[0].length));
+    lines.push(`${pad("SERIES", w)}  POINTS  FIRST  LAST`);
+    for (const [m, n, f, l] of rows)
+      lines.push(`${pad(m, w)}  ${pad(n, 6)}  ${f}  ${l}`);
+    if (rows.length)
+      lines.push("(first and last sample per series; use --json for every point)");
+  }
+  const series = payload.result.length;
+  const points = payload.result.reduce((n, s) => n + (s.values?.length ?? 0) + (s.value ? 1 : 0), 0);
+  lines.push(`
+${series} series, ${points} points`);
+  if (payload.stats.truncated) {
+    lines.push("⚠ TRUNCATED: too large to return whole. Raise --step, narrow the time range, " + "or select fewer series.");
+  }
+  return lines.join(`
+`);
+}
+
 // lib/instances.ts
 import * as fs4 from "fs";
 
@@ -30402,6 +30582,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 {
@@ -30451,11 +30663,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}`);
@@ -38784,9 +39004,62 @@ var LOCAL_INSTALL_MANAGED_ENV_KEYS = [
   "VM_DELETE_AUTH_KEY",
   "VM_SNAPSHOT_AUTH_KEY",
   "VM_FORCE_MERGE_AUTH_KEY",
-  "VM_PPROF_AUTH_KEY"
+  "VM_PPROF_AUTH_KEY",
+  "PGAI_INSTANCE_ID",
+  "INSTANCE_JOBS_USER",
+  "COMPOSE_PROFILES"
 ];
-function buildLocalInstallEnv(existingEnv, imageTag) {
+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;
+  let st;
+  try {
+    st = fs9.statSync(file);
+  } catch {
+    return;
+  }
+  if (!st.isFile())
+    return null;
+  return `${st.uid}:${st.gid}`;
+}
+function processOwner() {
+  if (typeof process.getuid !== "function" || typeof process.getgid !== "function")
+    return null;
+  return `${process.getuid()}:${process.getgid()}`;
+}
+function buildLocalInstallEnv(existingEnv, imageTag, instanceId, credentialFile, instanceJobs) {
   const readRaw = (key) => {
     const re = new RegExp(`^[ 	]*(?:export[ 	]+)?${key}=(.*)$`, "gm");
     let value = null;
@@ -38810,6 +39083,18 @@ function buildLocalInstallEnv(existingEnv, imageTag) {
   envLines.push(`VM_AUTH_USERNAME=${vmAuthUsername ? stripMatchingQuotes(vmAuthUsername) : "vmauth"}`);
   const vmAuthPassword = readRaw("VM_AUTH_PASSWORD");
   envLines.push(`VM_AUTH_PASSWORD=${vmAuthPassword ? stripMatchingQuotes(vmAuthPassword) : crypto2.randomBytes(18).toString("base64")}`);
+  const instanceIdValue = instanceId?.trim() || readRaw("PGAI_INSTANCE_ID");
+  if (instanceIdValue) {
+    envLines.push(`PGAI_INSTANCE_ID=${stripMatchingQuotes(instanceIdValue)}`);
+  }
+  const owner = statOwner(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")}`);
@@ -40598,16 +40883,6 @@ function checkRunningContainers() {
     return { running: false, containers: [] };
   }
 }
-function planMonitoringRegistration(args) {
-  const projectName = args.project?.trim() || undefined;
-  if (args.instanceId) {
-    return { kind: "adopt", projectName };
-  }
-  if (!projectName) {
-    return { kind: "error-missing-project", projectName: undefined };
-  }
-  return { kind: "self-register", projectName };
-}
 async function registerMonitoringInstance(apiKey, projectName, opts) {
   const { apiBaseUrl } = resolveBaseUrls2(opts);
   const url = `${apiBaseUrl}/rpc/monitoring_instance_register`;
@@ -40642,7 +40917,8 @@ Debug: Registering monitoring instance...`);
           "Content-Type": "application/json",
           ...orgScopeHeaders2(opts?.orgScope)
         },
-        body: JSON.stringify(requestBody)
+        body: JSON.stringify(requestBody),
+        signal: requestTimeoutSignal2(opts?.timeoutMs).signal
       });
       const body = await res.text().catch(() => "");
       if (!res.ok) {
@@ -40677,6 +40953,25 @@ Debug: Registering monitoring instance...`);
   }
   return null;
 }
+var INSTANCE_ID_RE = /^[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 instanceIdToPersist(reg, requestedId) {
+  for (const candidate of [reg?.instanceId, requestedId]) {
+    const value = candidate?.trim();
+    if (value && INSTANCE_ID_RE.test(value))
+      return value;
+  }
+  return null;
+}
+function planMonitoringRegistration(args) {
+  const projectName = args.project?.trim() || undefined;
+  if (args.instanceId) {
+    return { kind: "adopt", projectName };
+  }
+  if (!projectName) {
+    return { kind: "error-missing-project", projectName: undefined };
+  }
+  return { kind: "self-register", projectName };
+}
 var PROJECT_NAME_RE = /^[A-Za-z0-9._-]+$/;
 function resolveAdoptedProject(reg) {
   if (!reg)
@@ -40693,8 +40988,11 @@ function updatePgwatchConfig(configPath, updates) {
   let lines = [];
   if (fs9.existsSync(configPath)) {
     const stats = fs9.statSync(configPath);
-    if (!stats.isDirectory()) {
-      const content = fs9.readFileSync(configPath, "utf8");
+    if (!stats.isFile()) {
+      throw new Error(`${configPath} exists but is not a regular file; refusing to write through it`);
+    }
+    {
+      const content = fs9.readFileSync(configPath, "utf8").replace(/^\uFEFF+/, "");
       lines = content.split(/\r?\n/).filter((l) => l.trim() !== "");
     }
   }
@@ -40702,6 +41000,7 @@ function updatePgwatchConfig(configPath, updates) {
     const existingIndex = lines.findIndex((l) => l.startsWith(key + "="));
     if (existingIndex >= 0) {
       lines[existingIndex] = `${key}=${value}`;
+      lines = lines.filter((l, i) => i === existingIndex || !l.startsWith(key + "="));
     } else {
       lines.push(`${key}=${value}`);
     }
@@ -40716,6 +41015,129 @@ function updatePgwatchConfig(configPath, updates) {
     console.error(`Warning: could not restrict permissions on ${configPath}: ${message}`);
   }
 }
+function applyApiKey(projectDir, apiKey) {
+  const configPath = path7.resolve(projectDir, ".pgwatch-config");
+  try {
+    updatePgwatchConfig(configPath, { api_key: apiKey });
+  } catch (err) {
+    console.error(`\u2717 ${err instanceof Error ? err.message : String(err)}`);
+    return false;
+  }
+  console.log(`\u2713 API key saved
+`);
+  return true;
+}
+var DEFAULT_PROMQL_TIMEOUT_S = 11 * 60;
+function formatSeconds(total) {
+  const s = Math.max(0, Math.round(total));
+  if (s < 90)
+    return `${s}s`;
+  const m = Math.round(s / 60);
+  if (m < 60)
+    return `${m}m`;
+  const h = Math.floor(m / 60);
+  const rem = m % 60;
+  return rem ? `${h}h${rem}m` : `${h}h`;
+}
+function parseDurationSeconds(v) {
+  const m = /^(\d+)(s|m|h)?$/.exec(v.trim());
+  if (!m)
+    return null;
+  const n = parseInt(m[1], 10);
+  if (!Number.isFinite(n))
+    return null;
+  return n * (m[2] === "h" ? 3600 : m[2] === "m" ? 60 : 1);
+}
+function readInstanceIdFromProject() {
+  try {
+    const { projectDir } = resolvePaths();
+    const configPath = path7.resolve(projectDir, ".pgwatch-config");
+    if (!fs9.existsSync(configPath))
+      return null;
+    const line = fs9.readFileSync(configPath, "utf8").replace(/^\uFEFF+/, "").split(/\r?\n/).find((l) => l.startsWith("instance_id="));
+    const value = line?.slice("instance_id=".length).trim();
+    return value && INSTANCE_ID_RE.test(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function applyProjectName(projectDir, project) {
+  const configPath = path7.resolve(projectDir, ".pgwatch-config");
+  try {
+    updatePgwatchConfig(configPath, { project_name: project });
+  } catch (err) {
+    console.error(`\u2717 ${err instanceof Error ? err.message : String(err)}`);
+    return false;
+  }
+  console.log(`Using project name: ${project}
+`);
+  return true;
+}
+function persistInstanceId(projectDir, reg, requestedId, alsoWrite = {}) {
+  const instanceId = instanceIdToPersist(reg, requestedId);
+  const updates = { ...alsoWrite, ...instanceId ? { instance_id: instanceId } : {} };
+  if (Object.keys(updates).length === 0)
+    return false;
+  const configPath = path7.resolve(projectDir, ".pgwatch-config");
+  try {
+    updatePgwatchConfig(configPath, updates);
+    return instanceId != null;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Warning: could not record the monitoring instance id in ${configPath}: ${message}`);
+    return false;
+  }
+}
+async function adoptAndPersist(projectDir, apiKey, projectName, instanceId, opts, register = registerMonitoringInstance) {
+  const reg = await register(apiKey, projectName, {
+    orgScope: opts.orgScope,
+    apiBaseUrl: opts.apiBaseUrl,
+    debug: opts.debug,
+    instanceId
+  });
+  const adoptedProject = resolveAdoptedProject(reg);
+  const persisted = persistInstanceId(projectDir, reg, instanceId, {
+    ...adoptedProject != null ? { project_name: adoptedProject } : {}
+  });
+  if (!persisted) {
+    console.error(`\u26A0 Adopted instance ${instanceId} but could not record it in .pgwatch-config \u2014 ` + `instance jobs will idle until that file is writable and local-install is re-run
+`);
+  }
+  if (adoptedProject != null) {
+    const verb = reg?.created ? "Registered" : "Adopted";
+    console.log(`\u2713 ${verb} monitoring instance (project: ${adoptedProject})
+`);
+  } else if (reg) {
+    console.error(`\u26A0 Adopted provisioned instance ${instanceId} but the platform returned no project` + (projectName ? ` \u2014 reports will use project '${projectName}'` : ` \u2014 reports will have no project until 'postgresai mon local-install' is re-run with --project <name>`));
+  } else {
+    console.error(`\u26A0 Could not adopt provisioned instance ${instanceId}` + (projectName ? ` \u2014 reports will use project '${projectName}' until 'postgresai mon local-install' is re-run` : ` \u2014 reports will have no project until 'postgresai mon local-install' is re-run with --project <name>`));
+  }
+  return reg;
+}
+async function selfRegisterAndPersist(projectDir, apiKey, projectName, opts, register = registerMonitoringInstance) {
+  const reg = await register(apiKey, projectName, {
+    apiBaseUrl: opts.apiBaseUrl,
+    debug: opts.debug,
+    orgScope: opts.orgScope
+  });
+  const persisted = persistInstanceId(projectDir, reg, undefined);
+  if (persisted) {
+    console.log(`\u2713 Registered monitoring instance (project: ${projectName})
+`);
+    return reg;
+  }
+  const minted = reg?.instanceId?.trim();
+  if (minted) {
+    console.error(`\u26A0 Registered monitoring instance ${minted} but could not record it in .pgwatch-config \u2014 ` + `instance jobs will idle. Add 'instance_id=${minted}' to that file, or re-run with ` + `--instance-id ${minted} (which adopts it rather than registering a second one)
+`);
+  } else {
+    const reRun = projectName ? `'postgresai mon local-install --project ${projectName}'` : "'postgresai mon local-install --project <name>'";
+    console.error(`\u26A0 Could not register this monitoring instance \u2014 instance jobs will idle until ` + `${reRun} is re-run
+`);
+  }
+  process.exitCode = 1;
+  return reg;
+}
 async function applyMonitoringTargetsConfig() {
   console.log("Applying monitoring target configuration...");
   const generateCode = await runCompose(["run", "--rm", "sources-generator"]);
@@ -40724,7 +41146,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 {
@@ -40788,6 +41210,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");
@@ -40846,6 +41270,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();
 });
@@ -40859,7 +41404,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(`
@@ -40872,18 +41417,23 @@ mon.command("local-install").description("install local monitoring stack (genera
   const { projectDir, instancesFile: instancesPath } = await resolveOrInitPaths();
   console.log(`Project directory: ${projectDir}
 `);
-  if (opts.project) {
-    const cfgPath = path7.resolve(projectDir, ".pgwatch-config");
-    updatePgwatchConfig(cfgPath, { project_name: opts.project });
-    console.log(`Using project name: ${opts.project}
-`);
+  if (opts.project && !applyProjectName(projectDir, opts.project)) {
+    process.exitCode = 1;
+    return;
   }
   const envFile = path7.resolve(projectDir, ".env");
   const existingEnv = fs9.existsSync(envFile) ? fs9.readFileSync(envFile, "utf8") : "";
   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);
+  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(", ")}
@@ -40914,6 +41464,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) {
@@ -40923,9 +41475,10 @@ Use demo mode without API key: postgres-ai mon local-install --demo`);
     if (apiKey) {
       console.log("Using API key provided via --api-key parameter");
       writeConfig({ apiKey });
-      updatePgwatchConfig(path7.resolve(projectDir, ".pgwatch-config"), { api_key: apiKey });
-      console.log(`\u2713 API key saved
-`);
+      if (!applyApiKey(projectDir, apiKey)) {
+        process.exitCode = 1;
+        return;
+      }
     } else if (opts.yes) {
       console.log("Auto-yes mode: no API key provided, skipping API key setup");
       console.error("\u26A0 Reports will be generated locally only");
@@ -40940,10 +41493,11 @@ Use demo mode without API key: postgres-ai mon local-install --demo`);
           const trimmedKey = inputApiKey.trim();
           if (trimmedKey) {
             writeConfig({ apiKey: trimmedKey });
-            updatePgwatchConfig(path7.resolve(projectDir, ".pgwatch-config"), { api_key: trimmedKey });
+            if (!applyApiKey(projectDir, trimmedKey)) {
+              process.exitCode = 1;
+              return;
+            }
             apiKey = trimmedKey;
-            console.log(`\u2713 API key saved
-`);
             break;
           }
           console.error("\u26A0 API key cannot be empty");
@@ -41201,6 +41755,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)) {
@@ -41224,25 +41781,11 @@ Searched: ${demoCandidates.join(", ")}
     const plan = planMonitoringRegistration({ project: opts.project, instanceId });
     const projectName = plan.projectName;
     if (instanceId) {
-      const reg = await registerMonitoringInstance(apiKey, projectName, {
+      const reg = await adoptAndPersist(projectDir, apiKey, projectName, instanceId, {
         orgScope: regOrgScope,
         apiBaseUrl: globalOpts.apiBaseUrl,
-        debug: !!process.env.DEBUG,
-        instanceId
+        debug: !!process.env.DEBUG
       });
-      const adoptedProject = resolveAdoptedProject(reg);
-      if (adoptedProject != null) {
-        updatePgwatchConfig(path7.resolve(projectDir, ".pgwatch-config"), {
-          project_name: adoptedProject
-        });
-        const verb = reg?.created ? "Registered" : "Adopted";
-        console.log(`\u2713 ${verb} monitoring instance (project: ${adoptedProject})
-`);
-      } else if (reg) {
-        console.error(`\u26A0 Adopted provisioned instance ${instanceId} but the platform returned no project` + (projectName ? ` \u2014 reports will use project '${projectName}'` : ` \u2014 reports will have no project until 'postgresai mon local-install' is re-run with --project <name>`));
-      } else {
-        console.error(`\u26A0 Could not adopt provisioned instance ${instanceId}` + (projectName ? ` \u2014 reports will use project '${projectName}' until 'postgresai mon local-install' is re-run` : ` \u2014 reports will have no project until 'postgresai mon local-install' is re-run with --project <name>`));
-      }
       if (reg === null) {
         console.error(`\u26A0 Skipping AAS auto-collection arming because instance adoption failed; it can be enabled later by re-running 'postgresai mon local-install'
 `);
@@ -41256,7 +41799,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'
@@ -41267,7 +41810,7 @@ Searched: ${demoCandidates.join(", ")}
       console.error("\u2717 A project name is required for self-registration (the 'postgres-ai-monitoring' default was removed). " + "Re-run with --project <name>, or adopt a console-provisioned instance with --instance-id <uuid>.");
       process.exitCode = 1;
     } else {
-      registerMonitoringInstance(apiKey, projectName, {
+      await selfRegisterAndPersist(projectDir, apiKey, projectName, {
         apiBaseUrl: globalOpts.apiBaseUrl,
         debug: !!process.env.DEBUG,
         orgScope: regOrgScope
@@ -41275,9 +41818,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)");
@@ -41336,7 +41885,8 @@ var MONITORING_CONTAINERS = [
   "self-postgres-exporter",
   "flask-pgss-api",
   "sources-generator",
-  "postgres-reports"
+  "postgres-reports",
+  "instance-jobs"
 ];
 var COMPOSE_PROJECT_NAME = "postgres_ai";
 var DOCKER_NETWORK_NAME = `${COMPOSE_PROJECT_NAME}_default`;
@@ -41389,15 +41939,37 @@ mon.command("logs [service]").option("-f, --follow", "follow logs", false).optio
   if (code !== 0)
     process.exitCode = code;
 });
-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 = [
+function judgeServiceHealth(service, present, status, health) {
+  if (!present) {
+    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})` };
+  }
+  if (service.readHealth && health && health !== "healthy" && health !== "starting") {
+    return { ok: false, mark: "\u2717", label: `unhealthy (${health})` };
+  }
+  return { ok: true, mark: "\u2713", label: "healthy" };
+}
+function monitoringHealthServices(instanceJobsEnabled = false) {
+  return [
     { name: "Grafana", container: "grafana-with-datasources" },
     { name: "Prometheus", container: "sink-prometheus" },
     { name: "PGWatch (Postgres)", container: "pgwatch-postgres" },
     { name: "PGWatch (Prometheus)", container: "pgwatch-prometheus" },
     { name: "Target DB", container: "target-db" },
-    { name: "Sink Postgres", container: "sink-postgres" }
+    { name: "Sink Postgres", container: "sink-postgres" },
+    {
+      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(instanceJobsProfileEnabled(readComposeProfiles()));
   const waitTime = opts.wait || 0;
   const maxAttempts = waitTime > 0 ? Math.ceil(waitTime / 5) : 1;
   console.log(`Checking service health...
@@ -41413,16 +41985,12 @@ mon.command("health").description("health check for monitoring services").option
     for (const service of services) {
       try {
         const result = spawnSync2("docker", ["inspect", "-f", "{{.State.Status}}", service.container], { stdio: "pipe" });
-        const status = result.stdout.trim();
-        if (result.status === 0 && status === "running") {
-          console.log(`\u2713 ${service.name}: healthy`);
-        } else if (result.status === 0) {
-          console.log(`\u2717 ${service.name}: unhealthy (status: ${status})`);
+        const present = result.status === 0;
+        const health = present && service.readHealth ? (spawnSync2("docker", ["inspect", "-f", "{{if .State.Health}}{{.State.Health.Status}}{{end}}", service.container], { stdio: "pipe" }).stdout || "").trim() : "";
+        const verdict = judgeServiceHealth(service, present, (result.stdout || "").trim(), health);
+        console.log(`${verdict.mark} ${service.name}: ${verdict.label}`);
+        if (!verdict.ok)
           allHealthy = false;
-        } else {
-          console.log(`\u2717 ${service.name}: unreachable`);
-          allHealthy = false;
-        }
       } catch (error) {
         console.log(`\u2717 ${service.name}: unreachable`);
         allHealthy = false;
@@ -41535,6 +42103,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(`
@@ -42236,8 +42810,87 @@ 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) => {
+  try {
+    const rootOpts = program2.opts();
+    const cfg = readConfig();
+    const { apiKey } = getConfig(rootOpts);
+    if (!apiKey) {
+      console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+      process.exitCode = 1;
+      return;
+    }
+    const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+    const instanceId = opts.instance || readInstanceIdFromProject();
+    if (!instanceId) {
+      console.error("No monitoring instance. Pass --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;
+    }
+    const kind = opts.range ? "promql_range" : "promql_instant";
+    const enqueue = { instanceId, kind, query: expr };
+    if (opts.range) {
+      if (!opts.start || !opts.end || !opts.step) {
+        console.error("--range needs --start, --end and --step.");
+        process.exitCode = 1;
+        return;
+      }
+      const stepS = parseDurationSeconds(opts.step);
+      if (stepS === null || stepS < 1) {
+        console.error(`Invalid --step ${opts.step}: expected a duration like 60s, 5m or 1h.`);
+        process.exitCode = 1;
+        return;
+      }
+      enqueue.start = opts.start;
+      enqueue.end = opts.end;
+      enqueue.stepS = stepS;
+    } else if (opts.at) {
+      enqueue.at = opts.at;
+    }
+    const explicitTimeoutS = opts.timeout ? parseDurationSeconds(opts.timeout) : null;
+    if (opts.timeout && (explicitTimeoutS === null || explicitTimeoutS < 1)) {
+      console.error(`Invalid --timeout ${opts.timeout}: expected a duration like 60s or 2m.`);
+      process.exitCode = 1;
+      return;
+    }
+    const { jobId, firstAnswerEstimateS } = await enqueueQuery(apiKey, enqueue, { apiBaseUrl });
+    const timeoutS = explicitTimeoutS ?? (firstAnswerEstimateS === null ? DEFAULT_PROMQL_TIMEOUT_S : Math.min(Math.max(Math.ceil(firstAnswerEstimateS * 1.5) + 30, 60), 1800));
+    console.error(firstAnswerEstimateS === null ? `Queued as job ${jobId}; waiting up to ${formatSeconds(timeoutS)} for the instance's next poll.` : `Queued as job ${jobId}; this instance polls roughly every ${formatSeconds(firstAnswerEstimateS)} ` + `(jittered, so sometimes longer). Waiting up to ${formatSeconds(timeoutS)}.`);
+    const res = await awaitQueryResult(apiKey, jobId, {
+      apiBaseUrl,
+      timeoutMs: timeoutS * 1000
+    });
+    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 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;
+    }
+    if (res.status !== "done" || res.outcome !== "ok") {
+      console.error(`Query ${res.status}${res.failure_class ? ` (${res.failure_class})` : ""}.`);
+      if (res.error)
+        console.error(res.error);
+      process.exitCode = 1;
+      return;
+    }
+    if (!res.result) {
+      console.error("The job finished but carried no result.");
+      process.exitCode = 1;
+      return;
+    }
+    if (opts.json) {
+      console.log(JSON.stringify(res.result, null, 2));
+      return;
+    }
+    console.log(renderPromQL(res.result));
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+});
 var issues = program2.command("issues").description("issues management");
-withOrgOptions(issues.command("list")).description("list issues").option("--status <status>", "filter by status: open, closed, or all (default: all)").option("--limit <n>", "max number of issues to return (default: 20)", parseInt).option("--offset <n>", "number of issues to skip (default: 0)", parseInt).option("--hidden-only", "list only hidden issues (PostgresAI staff)").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
+withOrgOptions(issues.command("list")).description("list issues").option("--status <status>", "filter by status: open (default), closed, or all").option("--limit <n>", "max number of issues to return (default: 20)", parseInt).option("--offset <n>", "number of issues to skip (default: 0)", parseInt).option("--hidden-only", "list only hidden issues (PostgresAI staff)").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
   const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Fetching issues...");
   try {
     const rootOpts = program2.opts();
@@ -42252,11 +42905,15 @@ withOrgOptions(issues.command("list")).description("list issues").option("--stat
     const orgScope = getActiveOrgScope2() ?? { source: "token" };
     const orgId = configOrgIdForBody(apiKey, cfg.orgId);
     const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+    const statusArg = (opts.status ?? "open").trim().toLowerCase();
     let statusFilter;
-    if (opts.status === "open") {
-      statusFilter = "open";
-    } else if (opts.status === "closed") {
-      statusFilter = "closed";
+    if (statusArg === "open" || statusArg === "closed") {
+      statusFilter = statusArg;
+    } else if (statusArg !== "all") {
+      spinner.stop();
+      console.error("--status must be open, closed, or all");
+      process.exitCode = 1;
+      return;
     }
     const result = await fetchIssues2({
       apiKey,
@@ -42270,7 +42927,7 @@ withOrgOptions(issues.command("list")).description("list issues").option("--stat
       debug: !!opts.debug
     });
     spinner.stop();
-    const trimmed = Array.isArray(result) ? result.map((r) => withVisibleHiddenFlag2({
+    const trimmed = Array.isArray(result) ? result.map((r) => presentIssue2({
       id: r.id,
       title: r.title,
       status: r.status,
@@ -42308,7 +42965,7 @@ withOrgOptions(issues.command("view <issueId>")).description("view issue details
     spinner.update("Fetching comments...");
     const comments = await fetchIssueComments2({ apiKey, apiBaseUrl, issueId, debug: !!opts.debug });
     spinner.stop();
-    const combined = { issue: withVisibleHiddenFlag2(issue), comments };
+    const combined = { issue: presentIssue2(issue), comments };
     printResult(combined, opts.json);
   } catch (err) {
     spinner.stop();
@@ -43512,14 +44169,29 @@ if (__require.main == __require.module) {
 export {
   LOCAL_INSTALL_MANAGED_ENV_KEYS,
   ORG_SCOPED_COMMANDS,
+  adoptAndPersist,
+  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,
   updatePgwatchConfig
 };

package/package.json

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