postgresai 0.17.0-rc.2 → 0.17.0-rc.3

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.3",
   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.3";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -17315,6 +17321,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 +17341,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 +25015,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 +25031,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 +25335,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 +25617,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 +25637,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 +27174,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";
 
@@ -38784,9 +38948,29 @@ 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"
 ];
-function buildLocalInstallEnv(existingEnv, imageTag) {
+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) {
   const readRaw = (key) => {
     const re = new RegExp(`^[ 	]*(?:export[ 	]+)?${key}=(.*)$`, "gm");
     let value = null;
@@ -38810,6 +38994,14 @@ 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}`);
   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 +40790,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 +40824,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 +40860,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 +40895,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 +40907,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 +40922,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"]);
@@ -40872,18 +41201,16 @@ 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 { content: envContent, preservedKeys } = buildLocalInstallEnv(existingEnv, imageTag, opts.instanceId || process.env.PGAI_INSTANCE_ID || null, path7.resolve(projectDir, ".pgwatch-config"));
   writeEnvFile(envFile, envContent);
   if (preservedKeys.length > 0) {
     console.log(`Preserved existing .env settings: ${preservedKeys.join(", ")}
@@ -40923,9 +41250,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 +41268,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");
@@ -41224,25 +41553,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'
 `);
@@ -41267,7 +41582,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
@@ -41336,7 +41651,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 +41705,31 @@ 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: "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() {
+  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: true, readHealth: true }
   ];
+}
+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 waitTime = opts.wait || 0;
   const maxAttempts = waitTime > 0 ? Math.ceil(waitTime / 5) : 1;
   console.log(`Checking service health...
@@ -41413,16 +41745,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;
@@ -42236,8 +42564,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 (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.");
+      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 +42659,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 +42681,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 +42719,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 +43923,23 @@ if (__require.main == __require.module) {
 export {
   LOCAL_INSTALL_MANAGED_ENV_KEYS,
   ORG_SCOPED_COMMANDS,
+  adoptAndPersist,
+  applyApiKey,
+  applyProjectName,
   buildLocalInstallEnv,
+  instanceIdToPersist,
   isValidComposeYaml,
+  judgeServiceHealth,
+  monitoringHealthServices,
+  persistInstanceId,
   planMonitoringRegistration,
   program2 as program,
   readDeployedTag,
   refreshBundledComposeIfStale,
   registerMonitoringInstance,
   resolveAdoptedProject,
+  selfRegisterAndPersist,
   shouldScaleOutNodeExporter,
+  statOwner,
   updatePgwatchConfig
 };

package/package.json

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